ref(types): Verbosify envelope types (#4609)

This PR refactors our `Envelope` types, with the goal of both slightly simplifying the implementation and (primarily) moving from having values inlined to assigning them to variables, in order to make it easier to see how all of the parts fit together.

Notes:

- In addition to the envelope types, there are two new types, `UserFeedback` and `ClientReport`, representing the payloads of their respective envelope types.
- Both envelope and item headers base types are now objects containing all optional and required properties (as well as an index signature allowing them to be extended). This allows us to avoid having to perform type intersections in the item and envelope types, thus making them easier to parse.
- All formerly inlined values are split out into variables, in order to be able to use naming as a way to show exactly what's in each successive wrapper type.
- All of the base types are exported in order to allow them to be extended in other SDKs. Also exported, primarily for the purposes of type casting, are the various item and envelope types. Header types aren't exported because they're internal to items and envelopes, which are the only two units upon which outside code should be acting.

Author: lobsterkatie

packages/types/src/clientreport.ts

@@ -0,0 +1,7 @@
+import { SentryRequestType } from './request';
+import { Outcome } from './transport';
+
+export type ClientReport = {
+  timestamp: number;
+  discarded_events: { reason: Outcome; category: SentryRequestType; quantity: number };
+};

packages/types/src/envelope.ts

@@ -1,70 +1,51 @@
+import { ClientReport } from './clientreport';
 import { Event } from './event';
-import { SentryRequestType } from './request';
 import { SdkInfo } from './sdkinfo';
 import { Session, SessionAggregates } from './session';
-import { Outcome } from './transport';
-import { User } from './user';
+import { UserFeedback } from './user';
 
 // Based on: https://develop.sentry.dev/sdk/envelopes/
 
-type CommonEnvelopeHeaders = {
+export type BaseEnvelopeHeaders = {
+  [key: string]: unknown;
   dsn?: string;
   sdk?: SdkInfo;
 };
 
-type CommonEnvelopeItemHeaders = {
+export type BaseEnvelopeItemHeaders = {
+  [key: string]: unknown;
+  type: string;
   length?: number;
 };
 
-/**
- * 1st Item: Item headers
- * 2nd Item: Item payload
- */
-type BaseEnvelopeItem<ItemHeader extends { type: string }, Payload = unknown> = [
-  CommonEnvelopeItemHeaders & ItemHeader,
-  Payload,
-];
-
-type UnknownEnvelopeItem = BaseEnvelopeItem<{ type: '__unknown__' }>;
-
-type BaseEnvelope<
-  EnvelopeHeaders extends Record<string, unknown>,
-  EnvelopeItem extends BaseEnvelopeItem<{ type: string }>,
-> = {
-  headers: CommonEnvelopeHeaders & EnvelopeHeaders;
-  items: Array<EnvelopeItem | UnknownEnvelopeItem>;
-};
-
-export type EventEnvelopeItem = BaseEnvelopeItem<{ type: 'event' | 'transaction' }, Event>;
-
-type AttachmentEnvelopeItem = BaseEnvelopeItem<{ type: 'attachment'; filename: 'string' }>;
-
-type UserFeedbackEnvelopeItem = BaseEnvelopeItem<
-  { type: 'user_report' },
-  {
-    event_id: string;
-    email: User['email'];
-    name: string;
-    comments: string;
-  }
->;
-
-export type EventEnvelope = BaseEnvelope<
-  { event_id: string; sent_at: string },
-  EventEnvelopeItem | AttachmentEnvelopeItem | UserFeedbackEnvelopeItem
->;
-
-export type SessionEnvelopeItem =
-  | BaseEnvelopeItem<{ type: 'session' }, Session>
-  | BaseEnvelopeItem<{ type: 'sessions' }, SessionAggregates>;
-
-export type SessionEnvelope = BaseEnvelope<{ sent_at: string }, SessionEnvelopeItem>;
-
-export type ClientReportEnvelopeItem = BaseEnvelopeItem<
-  { type: 'client_report' },
-  { timestamp: number; discarded_events: { reason: Outcome; category: SentryRequestType; quantity: number } }
->;
-
-export type ClientReportEnvelope = BaseEnvelope<Record<string, unknown>, ClientReportEnvelopeItem>;
+export type BaseEnvelopeItem<IH extends BaseEnvelopeItemHeaders, P extends unknown> = [IH, P]; // P is for payload
+
+export type BaseEnvelope<
+  EH extends BaseEnvelopeHeaders,
+  I extends BaseEnvelopeItem<BaseEnvelopeItemHeaders, unknown>,
+> = [EH, I[]];
+
+type EventItemHeaders = { type: 'event' | 'transaction' };
+type AttachmentItemHeaders = { type: 'attachment'; filename: string };
+type UserFeedbackItemHeaders = { type: 'user_report' };
+type SessionItemHeaders = { type: 'session' };
+type SessionAggregatesItemHeaders = { type: 'sessions' };
+type ClientReportItemHeaders = { type: 'client_report' };
+
+export type EventItem = BaseEnvelopeItem<EventItemHeaders, Event>;
+export type AttachmentItem = BaseEnvelopeItem<AttachmentItemHeaders, unknown>;
+export type UserFeedbackItem = BaseEnvelopeItem<UserFeedbackItemHeaders, UserFeedback>;
+export type SessionItem =
+  | BaseEnvelopeItem<SessionItemHeaders, Session>
+  | BaseEnvelopeItem<SessionAggregatesItemHeaders, SessionAggregates>;
+export type ClientReportItem = BaseEnvelopeItem<ClientReportItemHeaders, ClientReport>;
+
+type EventEnvelopeHeaders = { event_id: string; sent_at: string };
+type SessionEnvelopeHeaders = { sent_at: string };
+type ClientReportEnvelopeHeaders = BaseEnvelopeHeaders;
+
+export type EventEnvelope = BaseEnvelope<EventEnvelopeHeaders, EventItem | AttachmentItem | UserFeedbackItem>;
+export type SessionEnvelope = BaseEnvelope<SessionEnvelopeHeaders, SessionItem>;
+export type ClientReportEnvelope = BaseEnvelope<ClientReportEnvelopeHeaders, ClientReportItem>;
 
 export type Envelope = EventEnvelope | SessionEnvelope | ClientReportEnvelope;

packages/types/src/index.ts

@@ -1,16 +1,23 @@
 export { Breadcrumb, BreadcrumbHint } from './breadcrumb';
 export { Client } from './client';
+export { ClientReport } from './clientreport';
 export { Context, Contexts } from './context';
 export { DsnComponents, DsnLike, DsnProtocol } from './dsn';
 export { DebugImage, DebugImageType, DebugMeta } from './debugMeta';
 export {
+  AttachmentItem,
+  BaseEnvelope,
+  BaseEnvelopeHeaders,
+  BaseEnvelopeItem,
+  BaseEnvelopeItemHeaders,
   ClientReportEnvelope,
-  ClientReportEnvelopeItem,
+  ClientReportItem,
   Envelope,
   EventEnvelope,
-  EventEnvelopeItem,
+  EventItem,
   SessionEnvelope,
-  SessionEnvelopeItem,
+  SessionItem,
+  UserFeedbackItem,
 } from './envelope';
 export { ExtendedError } from './error';
 export { Event, EventHint } from './event';
@@ -58,5 +65,5 @@ export {
 } from './transaction';
 export { Thread } from './thread';
 export { Outcome, Transport, TransportOptions, TransportClass } from './transport';
-export { User } from './user';
+export { User, UserFeedback } from './user';
 export { WrappedFunction } from './wrappedfunction';

packages/types/src/user.ts

@@ -6,3 +6,10 @@ export interface User {
   email?: string;
   username?: string;
 }
+
+export interface UserFeedback {
+  event_id: string;
+  email: User['email'];
+  name: string;
+  comments: string;
+}