@stack0/sdk 0.5.18 → 0.6.1

package/dist/mail/index.d.mts

@@ -906,6 +906,14 @@ interface Mailbox {
     createdAt: Date | string;
     updatedAt?: Date | string;
 }
+/** A mailbox as `create` returns it, with its webhook signing secret. Store the secret: only `create` and `rotateSecret` return it. */
+interface MailboxWithSecret extends Mailbox {
+    webhookSecret: string;
+}
+interface RotateMailboxSecretResponse {
+    id: string;
+    webhookSecret: string;
+}
 interface CreateMailboxRequest {
     projectSlug?: string;
     environment?: Environment;
@@ -945,12 +953,18 @@ interface InboundAttachment {
     filename: string;
     contentType: string;
     size: number;
-    url?: string;
+    /** Presigned GET URL, valid until `expiresAt` (one hour after the webhook attempt or API read). Null when the attachment could not be signed. */
+    url: string | null;
+    expiresAt: string | null;
 }
+/** Headers of an inbound email: lowercased name to value, or to every value of a repeated header (Received). */
+type InboundHeaders = Record<string, string | string[]>;
 interface InboundMessage {
     id: string;
     mailboxId: string;
     mailbox: string;
+    /** The part after "+" when the email came to `local+tag@domain` and routed to the mailbox `local@domain`. */
+    tag: string | null;
     messageId?: string;
     inReplyTo?: string;
     references?: string;
@@ -962,9 +976,12 @@ interface InboundMessage {
     subject?: string;
     html?: string;
     text?: string;
+    headers: InboundHeaders;
     attachments?: InboundAttachment[];
     webhookDelivered: boolean;
     webhookAttempts: number;
+    /** Why the last delivery failed, or `DAILY_LIMIT_REACHED: ...` when the message arrived over `maxInboundPerDay` and was not delivered. */
+    webhookLastError: string | null;
     createdAt: Date | string;
 }
 interface ListInboundMessagesRequest {
@@ -977,10 +994,18 @@ interface ListInboundMessagesResponse {
     hasMore: boolean;
     nextCursor?: string;
 }
+/**
+ * The body of an `email.inbound` webhook. Verify it with `verifyInboundWebhook`
+ * before trusting it. `id` is the same on every retry of one message
+ * (and equals the `webhook-id` header), so deduplicate on it.
+ */
 interface InboundWebhookPayload {
+    id: string;
     event: "email.inbound";
     mailbox: string;
     mailboxId: string;
+    /** The part after "+" when the email came to `local+tag@domain` and routed to the mailbox `local@domain`. */
+    tag: string | null;
     from: InboundEmailAddress;
     to: string;
     cc?: string[];
@@ -992,6 +1017,7 @@ interface InboundWebhookPayload {
     messageId?: string;
     inReplyTo?: string;
     references?: string[];
+    headers: InboundHeaders;
     attachments?: InboundAttachment[];
     metadata?: Record<string, unknown>;
     receivedAt: string;
@@ -1212,9 +1238,15 @@ declare class Mailboxes {
     private http;
     constructor(http: HttpClient);
     /**
-     * Create a new mailbox
+     * Create a new mailbox. The result carries `webhookSecret`, which signs every
+     * inbound delivery; store it now (only `create` and `rotateSecret` return it).
+     */
+    create(request: CreateMailboxRequest): Promise<MailboxWithSecret>;
+    /**
+     * Replace a mailbox's webhook secret and return the new one. Deliveries are
+     * signed with the new secret from then on.
      */
-    create(request: CreateMailboxRequest): Promise<Mailbox>;
+    rotateSecret(id: string): Promise<RotateMailboxSecretResponse>;
     /**
      * Get a mailbox by ID
      */
@@ -1519,4 +1551,44 @@ declare class Mail {
     listSenders(request?: ListSendersRequest): Promise<ListSendersResponse>;
 }
 
-export { type AddContactToSequenceRequest, type AddContactsToAudienceRequest, type AddContactsToAudienceResponse, type AddDomainRequest, type AddDomainResponse, type ArchiveSequenceResponse, type Attachment, type Audience, type AudienceContact, Audiences, type BatchTrackEventsRequest, type BatchTrackEventsResponse, type Campaign, type CampaignStatsResponse, type CampaignStatus, Campaigns, type CancelCampaignResponse, type CancelEmailResponse, type ConnectionType, type ContactStatus, Contacts, type CreateAudienceRequest, type CreateCampaignRequest, type CreateConnectionRequest, type CreateContactRequest, type CreateEventRequest, type CreateMailboxRequest, type CreateNodeRequest, type CreateSequenceRequest, type CreateTemplateRequest, type DeleteAudienceResponse, type DeleteCampaignResponse, type DeleteConnectionResponse, type DeleteContactResponse, type DeleteDomainResponse, type DeleteEventResponse, type DeleteNodeResponse, type DeleteSequenceResponse, type DeleteTemplateResponse, type DnsRecord, type Domain, type DomainStatus, Domains, type Email, type EmailAddress, type EmailAnalyticsResponse, type EmailRecipient, type EmailStatus, type EventAnalyticsResponse, type EventOccurrence, type EventPropertiesSchema, type EventProperty, Events, type GetDnsRecordsResponse, type GetEmailResponse, type HourlyAnalyticsDataPoint, type HourlyAnalyticsResponse, type ImportContactsRequest, type ImportContactsResponse, type InboundAttachment, type InboundEmailAddress, type InboundMessage, type InboundWebhookPayload, type ListAudienceContactsRequest, type ListAudienceContactsResponse, type ListAudiencesRequest, type ListAudiencesResponse, type ListCampaignsRequest, type ListCampaignsResponse, type ListContactsRequest, type ListContactsResponse, type ListDomainsRequest, type ListDomainsResponse, type ListEmailsRequest, type ListEmailsResponse, type ListEventOccurrencesRequest, type ListEventOccurrencesResponse, type ListEventsRequest, type ListEventsResponse, type ListInboundMessagesRequest, type ListInboundMessagesResponse, type ListMailboxesRequest, type ListMailboxesResponse, type ListSendersRequest, type ListSendersResponse, type ListSequenceEntriesRequest, type ListSequenceEntriesResponse, type ListSequencesRequest, type ListSequencesResponse, type ListTemplatesRequest, type ListTemplatesResponse, Mail, type MailContact, type MailEvent, type Mailbox, Mailboxes, type PauseCampaignResponse, type PauseSequenceResponse, type PreviewTemplateRequest, type PreviewTemplateResponse, type PublishSequenceResponse, type RemoveContactFromSequenceRequest, type RemoveContactFromSequenceResponse, type RemoveContactsFromAudienceRequest, type RemoveContactsFromAudienceResponse, type ResendEmailResponse, type ResumeSequenceResponse, type SendBatchEmailRequest, type SendBatchEmailResponse, type SendBroadcastEmailRequest, type SendBroadcastEmailResponse, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, type Sender, type Sequence, type SequenceAnalyticsResponse, type SequenceConnection, type SequenceEntry, type SequenceEntryStatus, type SequenceNode, type SequenceNodeType, type SequenceStatus, type SequenceTriggerFrequency, type SequenceTriggerType, type SequenceWithNodes, Sequences, type SetDefaultDomainResponse, type SetNodeBranchRequest, type SetNodeEmailRequest, type SetNodeExperimentRequest, type SetNodeFilterRequest, type SetNodeTimerRequest, type Template, Templates, type TimeSeriesAnalyticsRequest, type TimeSeriesAnalyticsResponse, type TimeSeriesDataPoint, type TrackEventRequest, type TrackEventResponse, type UpdateAudienceRequest, type UpdateCampaignRequest, type UpdateContactRequest, type UpdateEventRequest, type UpdateMailboxRequest, type UpdateNodePositionRequest, type UpdateNodeRequest, type UpdateSequenceRequest, type UpdateTemplateRequest, type VerifyDomainResponse };
+/**
+ * Verify inbound email webhooks.
+ *
+ * Stack0 signs each delivery with the Standard Webhooks scheme
+ * (https://www.standardwebhooks.com): `webhook-signature` is
+ * `v1,<base64 HMAC-SHA256 of "<webhook-id>.<webhook-timestamp>.<raw body>">`,
+ * keyed by the mailbox secret, base64-decoded. Uses Web Crypto, so it runs in
+ * Node 18+, Bun, Deno, and edge runtimes.
+ */
+
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+interface VerifyInboundWebhookOptions {
+    /** The raw request body, exactly as received. Do not parse and re-serialize it first. */
+    payload: string | Uint8Array | ArrayBuffer;
+    /** The request headers: a `Headers` object or a plain record (any case). */
+    headers: Headers | Record<string, string | string[] | undefined>;
+    /** The mailbox's webhook secret, from `mailboxes.create` or `mailboxes.rotateSecret`. */
+    secret: string;
+    /** How far the timestamp may be from now, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** The current time, for tests. */
+    now?: Date;
+}
+/**
+ * Check an inbound email webhook and return its payload. Throws
+ * `WebhookVerificationError` when a header is missing, the timestamp is
+ * outside the tolerance (a replay), or no signature matches.
+ *
+ * ```ts
+ * const event = await verifyInboundWebhook({
+ *   payload: await request.text(),
+ *   headers: request.headers,
+ *   secret: process.env.STACK0_MAILBOX_SECRET!,
+ * });
+ * ```
+ */
+declare function verifyInboundWebhook(options: VerifyInboundWebhookOptions): Promise<InboundWebhookPayload>;
+
+export { type AddContactToSequenceRequest, type AddContactsToAudienceRequest, type AddContactsToAudienceResponse, type AddDomainRequest, type AddDomainResponse, type ArchiveSequenceResponse, type Attachment, type Audience, type AudienceContact, Audiences, type BatchTrackEventsRequest, type BatchTrackEventsResponse, type Campaign, type CampaignStatsResponse, type CampaignStatus, Campaigns, type CancelCampaignResponse, type CancelEmailResponse, type ConnectionType, type ContactStatus, Contacts, type CreateAudienceRequest, type CreateCampaignRequest, type CreateConnectionRequest, type CreateContactRequest, type CreateEventRequest, type CreateMailboxRequest, type CreateNodeRequest, type CreateSequenceRequest, type CreateTemplateRequest, type DeleteAudienceResponse, type DeleteCampaignResponse, type DeleteConnectionResponse, type DeleteContactResponse, type DeleteDomainResponse, type DeleteEventResponse, type DeleteNodeResponse, type DeleteSequenceResponse, type DeleteTemplateResponse, type DnsRecord, type Domain, type DomainStatus, Domains, type Email, type EmailAddress, type EmailAnalyticsResponse, type EmailRecipient, type EmailStatus, type EventAnalyticsResponse, type EventOccurrence, type EventPropertiesSchema, type EventProperty, Events, type GetDnsRecordsResponse, type GetEmailResponse, type HourlyAnalyticsDataPoint, type HourlyAnalyticsResponse, type ImportContactsRequest, type ImportContactsResponse, type InboundAttachment, type InboundEmailAddress, type InboundHeaders, type InboundMessage, type InboundWebhookPayload, type ListAudienceContactsRequest, type ListAudienceContactsResponse, type ListAudiencesRequest, type ListAudiencesResponse, type ListCampaignsRequest, type ListCampaignsResponse, type ListContactsRequest, type ListContactsResponse, type ListDomainsRequest, type ListDomainsResponse, type ListEmailsRequest, type ListEmailsResponse, type ListEventOccurrencesRequest, type ListEventOccurrencesResponse, type ListEventsRequest, type ListEventsResponse, type ListInboundMessagesRequest, type ListInboundMessagesResponse, type ListMailboxesRequest, type ListMailboxesResponse, type ListSendersRequest, type ListSendersResponse, type ListSequenceEntriesRequest, type ListSequenceEntriesResponse, type ListSequencesRequest, type ListSequencesResponse, type ListTemplatesRequest, type ListTemplatesResponse, Mail, type MailContact, type MailEvent, type Mailbox, type MailboxWithSecret, Mailboxes, type PauseCampaignResponse, type PauseSequenceResponse, type PreviewTemplateRequest, type PreviewTemplateResponse, type PublishSequenceResponse, type RemoveContactFromSequenceRequest, type RemoveContactFromSequenceResponse, type RemoveContactsFromAudienceRequest, type RemoveContactsFromAudienceResponse, type ResendEmailResponse, type ResumeSequenceResponse, type RotateMailboxSecretResponse, type SendBatchEmailRequest, type SendBatchEmailResponse, type SendBroadcastEmailRequest, type SendBroadcastEmailResponse, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, type Sender, type Sequence, type SequenceAnalyticsResponse, type SequenceConnection, type SequenceEntry, type SequenceEntryStatus, type SequenceNode, type SequenceNodeType, type SequenceStatus, type SequenceTriggerFrequency, type SequenceTriggerType, type SequenceWithNodes, Sequences, type SetDefaultDomainResponse, type SetNodeBranchRequest, type SetNodeEmailRequest, type SetNodeExperimentRequest, type SetNodeFilterRequest, type SetNodeTimerRequest, type Template, Templates, type TimeSeriesAnalyticsRequest, type TimeSeriesAnalyticsResponse, type TimeSeriesDataPoint, type TrackEventRequest, type TrackEventResponse, type UpdateAudienceRequest, type UpdateCampaignRequest, type UpdateContactRequest, type UpdateEventRequest, type UpdateMailboxRequest, type UpdateNodePositionRequest, type UpdateNodeRequest, type UpdateSequenceRequest, type UpdateTemplateRequest, type VerifyDomainResponse, type VerifyInboundWebhookOptions, WebhookVerificationError, verifyInboundWebhook };

package/dist/mail/index.d.ts

@@ -906,6 +906,14 @@ interface Mailbox {
     createdAt: Date | string;
     updatedAt?: Date | string;
 }
+/** A mailbox as `create` returns it, with its webhook signing secret. Store the secret: only `create` and `rotateSecret` return it. */
+interface MailboxWithSecret extends Mailbox {
+    webhookSecret: string;
+}
+interface RotateMailboxSecretResponse {
+    id: string;
+    webhookSecret: string;
+}
 interface CreateMailboxRequest {
     projectSlug?: string;
     environment?: Environment;
@@ -945,12 +953,18 @@ interface InboundAttachment {
     filename: string;
     contentType: string;
     size: number;
-    url?: string;
+    /** Presigned GET URL, valid until `expiresAt` (one hour after the webhook attempt or API read). Null when the attachment could not be signed. */
+    url: string | null;
+    expiresAt: string | null;
 }
+/** Headers of an inbound email: lowercased name to value, or to every value of a repeated header (Received). */
+type InboundHeaders = Record<string, string | string[]>;
 interface InboundMessage {
     id: string;
     mailboxId: string;
     mailbox: string;
+    /** The part after "+" when the email came to `local+tag@domain` and routed to the mailbox `local@domain`. */
+    tag: string | null;
     messageId?: string;
     inReplyTo?: string;
     references?: string;
@@ -962,9 +976,12 @@ interface InboundMessage {
     subject?: string;
     html?: string;
     text?: string;
+    headers: InboundHeaders;
     attachments?: InboundAttachment[];
     webhookDelivered: boolean;
     webhookAttempts: number;
+    /** Why the last delivery failed, or `DAILY_LIMIT_REACHED: ...` when the message arrived over `maxInboundPerDay` and was not delivered. */
+    webhookLastError: string | null;
     createdAt: Date | string;
 }
 interface ListInboundMessagesRequest {
@@ -977,10 +994,18 @@ interface ListInboundMessagesResponse {
     hasMore: boolean;
     nextCursor?: string;
 }
+/**
+ * The body of an `email.inbound` webhook. Verify it with `verifyInboundWebhook`
+ * before trusting it. `id` is the same on every retry of one message
+ * (and equals the `webhook-id` header), so deduplicate on it.
+ */
 interface InboundWebhookPayload {
+    id: string;
     event: "email.inbound";
     mailbox: string;
     mailboxId: string;
+    /** The part after "+" when the email came to `local+tag@domain` and routed to the mailbox `local@domain`. */
+    tag: string | null;
     from: InboundEmailAddress;
     to: string;
     cc?: string[];
@@ -992,6 +1017,7 @@ interface InboundWebhookPayload {
     messageId?: string;
     inReplyTo?: string;
     references?: string[];
+    headers: InboundHeaders;
     attachments?: InboundAttachment[];
     metadata?: Record<string, unknown>;
     receivedAt: string;
@@ -1212,9 +1238,15 @@ declare class Mailboxes {
     private http;
     constructor(http: HttpClient);
     /**
-     * Create a new mailbox
+     * Create a new mailbox. The result carries `webhookSecret`, which signs every
+     * inbound delivery; store it now (only `create` and `rotateSecret` return it).
+     */
+    create(request: CreateMailboxRequest): Promise<MailboxWithSecret>;
+    /**
+     * Replace a mailbox's webhook secret and return the new one. Deliveries are
+     * signed with the new secret from then on.
      */
-    create(request: CreateMailboxRequest): Promise<Mailbox>;
+    rotateSecret(id: string): Promise<RotateMailboxSecretResponse>;
     /**
      * Get a mailbox by ID
      */
@@ -1519,4 +1551,44 @@ declare class Mail {
     listSenders(request?: ListSendersRequest): Promise<ListSendersResponse>;
 }
 
-export { type AddContactToSequenceRequest, type AddContactsToAudienceRequest, type AddContactsToAudienceResponse, type AddDomainRequest, type AddDomainResponse, type ArchiveSequenceResponse, type Attachment, type Audience, type AudienceContact, Audiences, type BatchTrackEventsRequest, type BatchTrackEventsResponse, type Campaign, type CampaignStatsResponse, type CampaignStatus, Campaigns, type CancelCampaignResponse, type CancelEmailResponse, type ConnectionType, type ContactStatus, Contacts, type CreateAudienceRequest, type CreateCampaignRequest, type CreateConnectionRequest, type CreateContactRequest, type CreateEventRequest, type CreateMailboxRequest, type CreateNodeRequest, type CreateSequenceRequest, type CreateTemplateRequest, type DeleteAudienceResponse, type DeleteCampaignResponse, type DeleteConnectionResponse, type DeleteContactResponse, type DeleteDomainResponse, type DeleteEventResponse, type DeleteNodeResponse, type DeleteSequenceResponse, type DeleteTemplateResponse, type DnsRecord, type Domain, type DomainStatus, Domains, type Email, type EmailAddress, type EmailAnalyticsResponse, type EmailRecipient, type EmailStatus, type EventAnalyticsResponse, type EventOccurrence, type EventPropertiesSchema, type EventProperty, Events, type GetDnsRecordsResponse, type GetEmailResponse, type HourlyAnalyticsDataPoint, type HourlyAnalyticsResponse, type ImportContactsRequest, type ImportContactsResponse, type InboundAttachment, type InboundEmailAddress, type InboundMessage, type InboundWebhookPayload, type ListAudienceContactsRequest, type ListAudienceContactsResponse, type ListAudiencesRequest, type ListAudiencesResponse, type ListCampaignsRequest, type ListCampaignsResponse, type ListContactsRequest, type ListContactsResponse, type ListDomainsRequest, type ListDomainsResponse, type ListEmailsRequest, type ListEmailsResponse, type ListEventOccurrencesRequest, type ListEventOccurrencesResponse, type ListEventsRequest, type ListEventsResponse, type ListInboundMessagesRequest, type ListInboundMessagesResponse, type ListMailboxesRequest, type ListMailboxesResponse, type ListSendersRequest, type ListSendersResponse, type ListSequenceEntriesRequest, type ListSequenceEntriesResponse, type ListSequencesRequest, type ListSequencesResponse, type ListTemplatesRequest, type ListTemplatesResponse, Mail, type MailContact, type MailEvent, type Mailbox, Mailboxes, type PauseCampaignResponse, type PauseSequenceResponse, type PreviewTemplateRequest, type PreviewTemplateResponse, type PublishSequenceResponse, type RemoveContactFromSequenceRequest, type RemoveContactFromSequenceResponse, type RemoveContactsFromAudienceRequest, type RemoveContactsFromAudienceResponse, type ResendEmailResponse, type ResumeSequenceResponse, type SendBatchEmailRequest, type SendBatchEmailResponse, type SendBroadcastEmailRequest, type SendBroadcastEmailResponse, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, type Sender, type Sequence, type SequenceAnalyticsResponse, type SequenceConnection, type SequenceEntry, type SequenceEntryStatus, type SequenceNode, type SequenceNodeType, type SequenceStatus, type SequenceTriggerFrequency, type SequenceTriggerType, type SequenceWithNodes, Sequences, type SetDefaultDomainResponse, type SetNodeBranchRequest, type SetNodeEmailRequest, type SetNodeExperimentRequest, type SetNodeFilterRequest, type SetNodeTimerRequest, type Template, Templates, type TimeSeriesAnalyticsRequest, type TimeSeriesAnalyticsResponse, type TimeSeriesDataPoint, type TrackEventRequest, type TrackEventResponse, type UpdateAudienceRequest, type UpdateCampaignRequest, type UpdateContactRequest, type UpdateEventRequest, type UpdateMailboxRequest, type UpdateNodePositionRequest, type UpdateNodeRequest, type UpdateSequenceRequest, type UpdateTemplateRequest, type VerifyDomainResponse };
+/**
+ * Verify inbound email webhooks.
+ *
+ * Stack0 signs each delivery with the Standard Webhooks scheme
+ * (https://www.standardwebhooks.com): `webhook-signature` is
+ * `v1,<base64 HMAC-SHA256 of "<webhook-id>.<webhook-timestamp>.<raw body>">`,
+ * keyed by the mailbox secret, base64-decoded. Uses Web Crypto, so it runs in
+ * Node 18+, Bun, Deno, and edge runtimes.
+ */
+
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+interface VerifyInboundWebhookOptions {
+    /** The raw request body, exactly as received. Do not parse and re-serialize it first. */
+    payload: string | Uint8Array | ArrayBuffer;
+    /** The request headers: a `Headers` object or a plain record (any case). */
+    headers: Headers | Record<string, string | string[] | undefined>;
+    /** The mailbox's webhook secret, from `mailboxes.create` or `mailboxes.rotateSecret`. */
+    secret: string;
+    /** How far the timestamp may be from now, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** The current time, for tests. */
+    now?: Date;
+}
+/**
+ * Check an inbound email webhook and return its payload. Throws
+ * `WebhookVerificationError` when a header is missing, the timestamp is
+ * outside the tolerance (a replay), or no signature matches.
+ *
+ * ```ts
+ * const event = await verifyInboundWebhook({
+ *   payload: await request.text(),
+ *   headers: request.headers,
+ *   secret: process.env.STACK0_MAILBOX_SECRET!,
+ * });
+ * ```
+ */
+declare function verifyInboundWebhook(options: VerifyInboundWebhookOptions): Promise<InboundWebhookPayload>;
+
+export { type AddContactToSequenceRequest, type AddContactsToAudienceRequest, type AddContactsToAudienceResponse, type AddDomainRequest, type AddDomainResponse, type ArchiveSequenceResponse, type Attachment, type Audience, type AudienceContact, Audiences, type BatchTrackEventsRequest, type BatchTrackEventsResponse, type Campaign, type CampaignStatsResponse, type CampaignStatus, Campaigns, type CancelCampaignResponse, type CancelEmailResponse, type ConnectionType, type ContactStatus, Contacts, type CreateAudienceRequest, type CreateCampaignRequest, type CreateConnectionRequest, type CreateContactRequest, type CreateEventRequest, type CreateMailboxRequest, type CreateNodeRequest, type CreateSequenceRequest, type CreateTemplateRequest, type DeleteAudienceResponse, type DeleteCampaignResponse, type DeleteConnectionResponse, type DeleteContactResponse, type DeleteDomainResponse, type DeleteEventResponse, type DeleteNodeResponse, type DeleteSequenceResponse, type DeleteTemplateResponse, type DnsRecord, type Domain, type DomainStatus, Domains, type Email, type EmailAddress, type EmailAnalyticsResponse, type EmailRecipient, type EmailStatus, type EventAnalyticsResponse, type EventOccurrence, type EventPropertiesSchema, type EventProperty, Events, type GetDnsRecordsResponse, type GetEmailResponse, type HourlyAnalyticsDataPoint, type HourlyAnalyticsResponse, type ImportContactsRequest, type ImportContactsResponse, type InboundAttachment, type InboundEmailAddress, type InboundHeaders, type InboundMessage, type InboundWebhookPayload, type ListAudienceContactsRequest, type ListAudienceContactsResponse, type ListAudiencesRequest, type ListAudiencesResponse, type ListCampaignsRequest, type ListCampaignsResponse, type ListContactsRequest, type ListContactsResponse, type ListDomainsRequest, type ListDomainsResponse, type ListEmailsRequest, type ListEmailsResponse, type ListEventOccurrencesRequest, type ListEventOccurrencesResponse, type ListEventsRequest, type ListEventsResponse, type ListInboundMessagesRequest, type ListInboundMessagesResponse, type ListMailboxesRequest, type ListMailboxesResponse, type ListSendersRequest, type ListSendersResponse, type ListSequenceEntriesRequest, type ListSequenceEntriesResponse, type ListSequencesRequest, type ListSequencesResponse, type ListTemplatesRequest, type ListTemplatesResponse, Mail, type MailContact, type MailEvent, type Mailbox, type MailboxWithSecret, Mailboxes, type PauseCampaignResponse, type PauseSequenceResponse, type PreviewTemplateRequest, type PreviewTemplateResponse, type PublishSequenceResponse, type RemoveContactFromSequenceRequest, type RemoveContactFromSequenceResponse, type RemoveContactsFromAudienceRequest, type RemoveContactsFromAudienceResponse, type ResendEmailResponse, type ResumeSequenceResponse, type RotateMailboxSecretResponse, type SendBatchEmailRequest, type SendBatchEmailResponse, type SendBroadcastEmailRequest, type SendBroadcastEmailResponse, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, type Sender, type Sequence, type SequenceAnalyticsResponse, type SequenceConnection, type SequenceEntry, type SequenceEntryStatus, type SequenceNode, type SequenceNodeType, type SequenceStatus, type SequenceTriggerFrequency, type SequenceTriggerType, type SequenceWithNodes, Sequences, type SetDefaultDomainResponse, type SetNodeBranchRequest, type SetNodeEmailRequest, type SetNodeExperimentRequest, type SetNodeFilterRequest, type SetNodeTimerRequest, type Template, Templates, type TimeSeriesAnalyticsRequest, type TimeSeriesAnalyticsResponse, type TimeSeriesDataPoint, type TrackEventRequest, type TrackEventResponse, type UpdateAudienceRequest, type UpdateCampaignRequest, type UpdateContactRequest, type UpdateEventRequest, type UpdateMailboxRequest, type UpdateNodePositionRequest, type UpdateNodeRequest, type UpdateSequenceRequest, type UpdateTemplateRequest, type VerifyDomainResponse, type VerifyInboundWebhookOptions, WebhookVerificationError, verifyInboundWebhook };

package/dist/mail/index.js

@@ -430,11 +430,19 @@ var Mailboxes = class {
   }
   http;
   /**
-   * Create a new mailbox
+   * Create a new mailbox. The result carries `webhookSecret`, which signs every
+   * inbound delivery; store it now (only `create` and `rotateSecret` return it).
    */
   async create(request) {
     return this.http.post("/mail/mailboxes", request);
   }
+  /**
+   * Replace a mailbox's webhook secret and return the new one. Deliveries are
+   * signed with the new secret from then on.
+   */
+  async rotateSecret(id) {
+    return this.http.post(`/mail/mailboxes/${id}/rotate-secret`, {});
+  }
   /**
    * Get a mailbox by ID
    */
@@ -968,6 +976,92 @@ var Mail = class {
   }
 };
 
+// src/mail/webhooks.ts
+var WebhookVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookVerificationError";
+  }
+};
+function header(headers, name) {
+  if (typeof headers.get === "function") return headers.get(name) ?? void 0;
+  const record = headers;
+  for (const key of Object.keys(record)) {
+    if (key.toLowerCase() === name) {
+      const v = record[key];
+      return Array.isArray(v) ? v[0] : v;
+    }
+  }
+  return void 0;
+}
+function base64ToBytes(b64) {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function bytesToBase64(bytes) {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin);
+}
+async function subtle() {
+  const global = globalThis.crypto;
+  if (global?.subtle) return global.subtle;
+  const specifier = "node:crypto";
+  const nodeCrypto = await import(
+    /* webpackIgnore: true */
+    /* @vite-ignore */
+    specifier
+  );
+  return nodeCrypto.webcrypto.subtle;
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+async function verifyInboundWebhook(options) {
+  const id = header(options.headers, "webhook-id");
+  const timestamp = header(options.headers, "webhook-timestamp");
+  const signatures = header(options.headers, "webhook-signature");
+  if (!id || !timestamp || !signatures) {
+    throw new WebhookVerificationError("missing webhook-id, webhook-timestamp, or webhook-signature header");
+  }
+  const seconds = Number(timestamp);
+  if (!Number.isInteger(seconds)) throw new WebhookVerificationError("webhook-timestamp is not a whole number");
+  const now = Math.floor((options.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+  const tolerance = options.toleranceSeconds ?? 300;
+  if (Math.abs(now - seconds) > tolerance) {
+    throw new WebhookVerificationError(`webhook-timestamp is more than ${tolerance} seconds from now`);
+  }
+  const body = typeof options.payload === "string" ? options.payload : new TextDecoder().decode(options.payload instanceof ArrayBuffer ? new Uint8Array(options.payload) : options.payload);
+  const secret = options.secret.startsWith("whsec_") ? options.secret.slice(6) : options.secret;
+  const webcrypto = await subtle();
+  const key = await webcrypto.importKey(
+    "raw",
+    base64ToBytes(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const mac = new Uint8Array(
+    await webcrypto.sign("HMAC", key, new TextEncoder().encode(`${id}.${seconds}.${body}`))
+  );
+  const expected = bytesToBase64(mac);
+  const matched = signatures.split(" ").map((s) => s.split(",", 2)).some(([version, sig]) => version === "v1" && sig !== void 0 && timingSafeEqual(sig, expected));
+  if (!matched) throw new WebhookVerificationError("no webhook-signature matches");
+  let payload;
+  try {
+    payload = JSON.parse(body);
+  } catch {
+    throw new WebhookVerificationError("the payload is not JSON");
+  }
+  if (payload.id !== id) throw new WebhookVerificationError("the payload id does not match webhook-id");
+  return payload;
+}
+
 exports.Audiences = Audiences;
 exports.Campaigns = Campaigns;
 exports.Contacts = Contacts;
@@ -977,5 +1071,7 @@ exports.Mail = Mail;
 exports.Mailboxes = Mailboxes;
 exports.Sequences = Sequences;
 exports.Templates = Templates;
+exports.WebhookVerificationError = WebhookVerificationError;
+exports.verifyInboundWebhook = verifyInboundWebhook;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map