feat(types): Add Envelope types (#4527)

To prep for the introduction of formal envelopes API, add types
representing envelopes and their items. These are based on the
documentation from the develop docs at the time of this patch.

Envelope items are stored as a tuple of length 2 (item headers and
payload) to reduce bundle size. This is as array access is smaller than
having to access through object properties, and they will stay constant.

Each Envelope is generic over a `BaseEnvelope` type, which allows for
items and headers to be configured, but sets a `CommonEnvelopeHeaders`
alongside a default `UnknownEnvelopeItem` (as per the spec).

Each Envelope item is generic over a `BaseEnvelopeItem` type, which
establishs `CommonEnvelopeItemHeaders` over an arbitrary item payload.

Envelope items are defined for events, attachments, user feedback,
sessions, and client reports. Envelopes are defined for events,
sessions, and client reports. This is as attachments and user feedback
(for now) must be in the envelope alongside the event.

As User Feedback and Attachment envelopes are currently not supported in
the SDK, they are not exported, but will be once v7 is introduced.

The next step from the patch is to add the public API around creating
and mutating Envelopes of different natures, as well as mapping from an
Envelope -> `SentryRequest`.

See: https://develop.sentry.dev/sdk/envelopes/

packages/types/src/envelope.ts

@@ -0,0 +1,69 @@
+import { SentryRequestType } from './request';
+import { SdkInfo } from './sdkinfo';
+import { Session, SessionAggregates } from './session';
+import { Outcome } from './transport';
+import { User } from './user';
+
+// Based on: https://develop.sentry.dev/sdk/envelopes/
+
+type CommonEnvelopeHeaders = {
+  dsn?: string;
+  sdk?: SdkInfo;
+};
+
+type CommonEnvelopeItemHeaders = {
+  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 Envelope = EventEnvelope | SessionEnvelope | ClientReportEnvelope;

packages/types/src/index.ts

@@ -3,6 +3,15 @@ export { Client } from './client';
 export { Context, Contexts } from './context';
 export { DsnComponents, DsnLike, DsnProtocol } from './dsn';
 export { DebugImage, DebugImageType, DebugMeta } from './debugMeta';
+export {
+  ClientReportEnvelope,
+  ClientReportEnvelopeItem,
+  Envelope,
+  EventEnvelope,
+  EventEnvelopeItem,
+  SessionEnvelope,
+  SessionEnvelopeItem,
+} from './envelope';
 export { ExtendedError } from './error';
 export { Event, EventHint } from './event';
 export { EventStatus } from './eventstatus';