@primitivedotdev/sdk 0.3.0 → 0.5.0

package/dist/api/generated/sdk.gen.js

@@ -188,8 +188,10 @@ export const downloadAttachments = (options) => (options.client ?? client).get({
  * Replay email webhooks
  *
  * Re-delivers the webhook payload for this email to all active
- * endpoints matching the email's domain. Includes rate limiting
- * to prevent stampeding.
+ * endpoints matching the email's domain. Rate limited per-email
+ * (short cooldown between successive replays of the same email)
+ * and per-org (burst + sustained windows), sharing an org-wide
+ * budget with delivery replays.
  *
  */
 export const replayEmailWebhooks = (options) => (options.client ?? client).post({
@@ -333,8 +335,9 @@ export const listDeliveries = (options) => (options?.client ?? client).get({
  *
  * Re-sends the stored webhook payload from a previous delivery attempt.
  * If the original endpoint is still active, it is targeted. If the
- * original endpoint was deleted, the first active endpoint is used.
- * Deactivated endpoints cannot be replayed to.
+ * original endpoint was deleted, the oldest active endpoint is used.
+ * Deactivated endpoints cannot be replayed to. Rate limited per-org,
+ * sharing an org-wide budget with email replays.
  *
  */
 export const replayDelivery = (options) => (options.client ?? client).post({

package/dist/api/index.d.ts

@@ -348,8 +348,30 @@ type PaginationMeta = {
 type ErrorResponse = {
   success: boolean;
   error: {
-    code: 'unauthorized' | 'forbidden' | 'not_found' | 'validation_error' | 'rate_limit_exceeded' | 'internal_error';
+    code: 'unauthorized' | 'forbidden' | 'not_found' | 'validation_error' | 'rate_limit_exceeded' | 'internal_error' | 'conflict' | 'mx_conflict';
     message: string;
+    /**
+     * Optional structured data that callers can inspect to recover
+     * from the error. The fields present depend on `code`. Additional
+     * keys may be added over time without a major-version bump.
+     *
+     */
+    details?: {
+      /**
+       * Present when `code == mx_conflict`.
+       */
+      mx_conflict?: {
+        /**
+         * Human-readable name of the detected mailbox provider (e.g. "Google Workspace").
+         */
+        provider_name: string;
+        /**
+         * Subdomain to try instead (e.g. "mail" for `mail.example.com`).
+         */
+        suggested_subdomain: string;
+      };
+      [key: string]: unknown;
+    };
   };
 };
 type Account = {
@@ -866,6 +888,18 @@ type AddDomainErrors = {
    * Invalid or missing API key
    */
   401: ErrorResponse;
+  /**
+   * Domain claim conflicts with existing state. Two error codes
+   * are possible:
+   * * `mx_conflict`: the domain's current MX records point at
+   * another mailbox provider. The response includes
+   * `error.details.mx_conflict` with the detected provider
+   * and a suggested subdomain.
+   * * `conflict`: the domain is already claimed by another
+   * org, or a pending claim exists for another user.
+   *
+   */
+  409: ErrorResponse;
 };
 type AddDomainError = AddDomainErrors[keyof AddDomainErrors];
 type AddDomainResponses = {
@@ -1213,6 +1247,10 @@ type ReplayEmailWebhooksErrors = {
    * Resource not found
    */
   404: ErrorResponse;
+  /**
+   * Rate limit exceeded
+   */
+  429: ErrorResponse;
 };
 type ReplayEmailWebhooksError = ReplayEmailWebhooksErrors[keyof ReplayEmailWebhooksErrors];
 type ReplayEmailWebhooksResponses = {
@@ -1584,6 +1622,10 @@ type ReplayDeliveryErrors = {
    * Resource not found
    */
   404: ErrorResponse;
+  /**
+   * Rate limit exceeded
+   */
+  429: ErrorResponse;
 };
 type ReplayDeliveryError = ReplayDeliveryErrors[keyof ReplayDeliveryErrors];
 type ReplayDeliveryResponses = {
@@ -1720,8 +1762,10 @@ declare const downloadAttachments: <ThrowOnError extends boolean = false>(option
  * Replay email webhooks
  *
  * Re-delivers the webhook payload for this email to all active
- * endpoints matching the email's domain. Includes rate limiting
- * to prevent stampeding.
+ * endpoints matching the email's domain. Rate limited per-email
+ * (short cooldown between successive replays of the same email)
+ * and per-org (burst + sustained windows), sharing an org-wide
+ * budget with delivery replays.
  *
  */
 declare const replayEmailWebhooks: <ThrowOnError extends boolean = false>(options: Options$1<ReplayEmailWebhooksData, ThrowOnError>) => RequestResult<ReplayEmailWebhooksResponses, ReplayEmailWebhooksErrors, ThrowOnError, "fields">;
@@ -1805,8 +1849,9 @@ declare const listDeliveries: <ThrowOnError extends boolean = false>(options?: O
  *
  * Re-sends the stored webhook payload from a previous delivery attempt.
  * If the original endpoint is still active, it is targeted. If the
- * original endpoint was deleted, the first active endpoint is used.
- * Deactivated endpoints cannot be replayed to.
+ * original endpoint was deleted, the oldest active endpoint is used.
+ * Deactivated endpoints cannot be replayed to. Rate limited per-org,
+ * sharing an org-wide budget with email replays.
  *
  */
 declare const replayDelivery: <ThrowOnError extends boolean = false>(options: Options$1<ReplayDeliveryData, ThrowOnError>) => RequestResult<ReplayDeliveryResponses, ReplayDeliveryErrors, ThrowOnError, "fields">;

package/dist/contract/index.d.ts

@@ -1,5 +1,5 @@
 import { EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, ParsedDataComplete, ParsedDataFailed, ParsedError, RawContentDownloadOnly, RawContentInline, WebhookAttachment } from "../types-C3ms4R0d.js";
-import { SignResult, StandardWebhooksSignResult, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload } from "../index-D2OuDGVz.js";
+import { SignResult, StandardWebhooksSignResult, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload } from "../index-C7tHPMZM.js";
 
 //#region src/contract/contract.d.ts
 /** Maximum raw email size for inline inclusion (256 KB). */
@@ -146,5 +146,83 @@ declare function buildEmailReceivedEvent(input: EmailReceivedEventInput, options
   event_id?: string;
   /** Override the attempted-at timestamp, typically for tests. */
   attempted_at?: string;
-}): EmailReceivedEvent; //#endregion
-export { EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EmailReceivedEventInput, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedInput, ParsedInputComplete, ParsedInputFailed, RAW_EMAIL_INLINE_THRESHOLD, RawContentDownloadOnly, RawContentInline, SignResult, StandardWebhooksSignResult, WEBHOOK_VERSION, WebhookAttachment, buildEmailReceivedEvent, generateEventId, signStandardWebhooksPayload, signWebhookPayload };
+}): EmailReceivedEvent;
+/**
+ * Input for building an `EmailReceivedEvent` directly from parser output.
+ */
+interface BuildEventFromParsedDataOptions {
+  /** Unique email ID chosen by the producer. */
+  emailId: string;
+  /** ID of the webhook endpoint receiving this event. */
+  endpointId: string;
+  /** Raw RFC 5322 bytes. Used to compute sha256 and inline data. */
+  rawBytes: Buffer;
+  /** Parser output with attachments, body, and threading headers populated. */
+  parsed: ParsedDataComplete;
+  /** Message-ID header value, or null if the email had none. */
+  messageId: string | null;
+  /** From header value. */
+  sender: string;
+  /** To header value. */
+  recipient: string;
+  /** Subject header value, or null. */
+  subject: string | null;
+  /** ISO 8601 timestamp when the producer accepted the email. */
+  receivedAt: string;
+  /** SMTP HELO/EHLO hostname, or null if not captured. */
+  smtpHelo: string | null;
+  /** SMTP envelope MAIL FROM. */
+  smtpMailFrom: string;
+  /** SMTP envelope RCPT TO recipients. Must contain at least one entry. */
+  smtpRcptTo: [string, ...string[]];
+  /** Email authentication results (camelCase per the schema). */
+  auth: EmailAuth;
+  /** Email analysis block. */
+  analysis: EmailAnalysis;
+  /** HTTPS download URL for the raw email. Always populated. */
+  downloadUrl: string;
+  /** ISO 8601 expiry for the raw-email download URL. */
+  downloadExpiresAt: string;
+  /**
+   * Download URL for the attachments tarball.
+   * Must be null iff `parsed.attachments` is empty — mismatch throws.
+   */
+  attachmentsDownloadUrl: string | null;
+  /** Delivery attempt number, starting at 1. */
+  attemptCount: number;
+  /** Original Date header value, or null. */
+  dateHeader?: string | null;
+  /** Optional overrides forwarded to `buildEmailReceivedEvent`. */
+  buildOptions?: {
+    event_id?: string;
+    attempted_at?: string;
+  };
+}
+/**
+ * Build an `EmailReceivedEvent` from parsed email data plus delivery metadata.
+ *
+ * Pure adapter: the caller supplies the raw bytes and the already-parsed
+ * data; this function computes sha256 and size, enforces the attachments
+ * invariant, and delegates to `buildEmailReceivedEvent` for schema
+ * validation. It never reads from disk, so it is safe to use in any
+ * runtime that has the data in memory.
+ *
+ * Inline vs. download-only behavior: when `rawBytes.length` is at or below
+ * `RAW_EMAIL_INLINE_THRESHOLD`, the event's `raw.data` is populated and
+ * `download.url` is still populated. Above the threshold, only `download.url`
+ * is populated. The download URL is always set regardless of inline status.
+ *
+ * Callers using the bundled parser can populate the header fields
+ * (`messageId`, `sender`, `recipient`, `subject`, `dateHeader`) directly
+ * from `toCanonicalHeaders(parsed)`. Accepting the flat fields rather than
+ * a canonical-headers object keeps this function usable by callers that
+ * do not use the bundled parser. A future release may add an optional
+ * canonical-headers parameter as an ergonomic alternative.
+ *
+ * @throws Error if `attachmentsDownloadUrl` disagrees with whether
+ *   `parsed.attachments` is empty.
+ * @throws Error if `smtpRcptTo` is empty.
+ * @throws WebhookValidationError if the assembled event fails schema validation.
+ */
+declare function buildEventFromParsedData(params: BuildEventFromParsedDataOptions): EmailReceivedEvent; //#endregion
+export { BuildEventFromParsedDataOptions, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EmailReceivedEventInput, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedInput, ParsedInputComplete, ParsedInputFailed, RAW_EMAIL_INLINE_THRESHOLD, RawContentDownloadOnly, RawContentInline, SignResult, StandardWebhooksSignResult, WEBHOOK_VERSION, WebhookAttachment, buildEmailReceivedEvent, buildEventFromParsedData, generateEventId, signStandardWebhooksPayload, signWebhookPayload };

package/dist/contract/index.js

@@ -1,4 +1,4 @@
-import { WEBHOOK_VERSION, signStandardWebhooksPayload, signWebhookPayload, validateEmailReceivedEvent } from "../webhook-uSco6pyX.js";
+import { WEBHOOK_VERSION, signStandardWebhooksPayload, signWebhookPayload, validateEmailReceivedEvent } from "../webhook-C5kOt3fb.js";
 import { createHash } from "node:crypto";
 
 //#region src/contract/contract.ts
@@ -194,6 +194,76 @@ function buildEmailReceivedEvent(input, options) {
 	};
 	return validateEmailReceivedEvent(event);
 }
+/**
+* Build an `EmailReceivedEvent` from parsed email data plus delivery metadata.
+*
+* Pure adapter: the caller supplies the raw bytes and the already-parsed
+* data; this function computes sha256 and size, enforces the attachments
+* invariant, and delegates to `buildEmailReceivedEvent` for schema
+* validation. It never reads from disk, so it is safe to use in any
+* runtime that has the data in memory.
+*
+* Inline vs. download-only behavior: when `rawBytes.length` is at or below
+* `RAW_EMAIL_INLINE_THRESHOLD`, the event's `raw.data` is populated and
+* `download.url` is still populated. Above the threshold, only `download.url`
+* is populated. The download URL is always set regardless of inline status.
+*
+* Callers using the bundled parser can populate the header fields
+* (`messageId`, `sender`, `recipient`, `subject`, `dateHeader`) directly
+* from `toCanonicalHeaders(parsed)`. Accepting the flat fields rather than
+* a canonical-headers object keeps this function usable by callers that
+* do not use the bundled parser. A future release may add an optional
+* canonical-headers parameter as an ergonomic alternative.
+*
+* @throws Error if `attachmentsDownloadUrl` disagrees with whether
+*   `parsed.attachments` is empty.
+* @throws Error if `smtpRcptTo` is empty.
+* @throws WebhookValidationError if the assembled event fails schema validation.
+*/
+function buildEventFromParsedData(params) {
+	const { parsed, attachmentsDownloadUrl, smtpRcptTo } = params;
+	const hasAttachments = parsed.attachments.length > 0;
+	if (hasAttachments && attachmentsDownloadUrl === null) throw new Error(`[@primitivedotdev/sdk/contract] attachmentsDownloadUrl must be non-null when parsed.attachments has ${parsed.attachments.length} entries`);
+	if (!hasAttachments && attachmentsDownloadUrl !== null) throw new Error(`[@primitivedotdev/sdk/contract] attachmentsDownloadUrl must be null when parsed.attachments is empty (got: ${JSON.stringify(attachmentsDownloadUrl)})`);
+	if (smtpRcptTo.length === 0) throw new Error("[@primitivedotdev/sdk/contract] smtpRcptTo must contain at least one recipient");
+	const raw_size_bytes = params.rawBytes.length;
+	const raw_sha256 = createHash("sha256").update(params.rawBytes).digest("hex");
+	const parsedInput = {
+		status: "complete",
+		body_text: parsed.body_text,
+		body_html: parsed.body_html,
+		reply_to: parsed.reply_to,
+		cc: parsed.cc,
+		bcc: parsed.bcc,
+		in_reply_to: parsed.in_reply_to,
+		references: parsed.references,
+		attachments: parsed.attachments
+	};
+	const input = {
+		email_id: params.emailId,
+		endpoint_id: params.endpointId,
+		message_id: params.messageId,
+		sender: params.sender,
+		recipient: params.recipient,
+		subject: params.subject,
+		received_at: params.receivedAt,
+		smtp_helo: params.smtpHelo,
+		smtp_mail_from: params.smtpMailFrom,
+		smtp_rcpt_to: smtpRcptTo,
+		raw_bytes: params.rawBytes,
+		raw_sha256,
+		raw_size_bytes,
+		attempt_count: params.attemptCount,
+		date_header: params.dateHeader ?? null,
+		download_url: params.downloadUrl,
+		download_expires_at: params.downloadExpiresAt,
+		attachments_download_url: attachmentsDownloadUrl,
+		parsed: parsedInput,
+		auth: params.auth,
+		analysis: params.analysis
+	};
+	return buildEmailReceivedEvent(input, params.buildOptions);
+}
 
 //#endregion
-export { RAW_EMAIL_INLINE_THRESHOLD, WEBHOOK_VERSION, buildEmailReceivedEvent, generateEventId, signStandardWebhooksPayload, signWebhookPayload };
+export { RAW_EMAIL_INLINE_THRESHOLD, WEBHOOK_VERSION, buildEmailReceivedEvent, buildEventFromParsedData, generateEventId, signStandardWebhooksPayload, signWebhookPayload };

package/dist/{index-D2OuDGVz.d.ts → index-C7tHPMZM.d.ts}

@@ -224,6 +224,95 @@ type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
 declare function validateEmailReceivedEvent(input: unknown): EmailReceivedEvent;
 declare function safeValidateEmailReceivedEvent(input: unknown): ValidationResult<EmailReceivedEvent>;
 
+//#endregion
+//#region src/webhook/download-tokens.d.ts
+/**
+ * Signed download tokens.
+ *
+ * A download token is a self-describing bearer credential for fetching a
+ * specific email's raw bytes or attachment bundle from a per-deployment
+ * download endpoint. It binds:
+ *
+ * - `email_id` — the specific email the token authorizes.
+ * - `aud` — a caller-chosen audience label (e.g. the resource kind being
+ *   downloaded). Tokens minted for one audience will not verify under another.
+ * - `exp` — an absolute expiration time (unix seconds).
+ *
+ * Format: `<base64url(payload)>.<base64url(signature)>` where `signature`
+ * is HMAC-SHA256 over the base64url-encoded payload using the shared secret.
+ *
+ * The audience is an opaque caller-chosen string. Both the issuer and the
+ * verifier must agree on the exact bytes; the SDK does not prescribe a
+ * convention. New integrations are encouraged to namespace audiences
+ * (e.g. `primitive:raw-download`).
+ *
+ * Tokens are stateless: verification needs only the shared secret. Keep
+ * expirations as short as operationally tolerable.
+ */
+/**
+ * Input for issuing a download token.
+ */
+interface GenerateDownloadTokenOptions {
+  /** The email ID the token authorizes. */
+  emailId: string;
+  /** Absolute expiration as unix seconds (not a TTL). */
+  expiresAt: number;
+  /** Caller-chosen audience label; the verifier must supply the same value. */
+  audience: string;
+  /** Shared HMAC secret. */
+  secret: string;
+}
+/**
+ * Issue a signed download token.
+ *
+ * The resulting token is `<base64url-payload>.<base64url-signature>`, where
+ * the payload is `{"email_id":"...","exp":...,"aud":"..."}` (snake_case,
+ * field order fixed) and the signature is HMAC-SHA256 of the base64url
+ * payload string using `secret`.
+ *
+ * @param params - Token inputs.
+ * @returns The signed token string.
+ */
+declare function generateDownloadToken(params: GenerateDownloadTokenOptions): string;
+/**
+ * Input for verifying a download token.
+ */
+interface VerifyDownloadTokenOptions {
+  /** The token string to verify. */
+  token: string;
+  /** Expected email ID — must match the token payload exactly. */
+  emailId: string;
+  /** Expected audience — must match the token payload exactly. */
+  audience: string;
+  /** Shared HMAC secret. */
+  secret: string;
+  /** Override the current time (unix seconds) for deterministic tests. */
+  nowSeconds?: number;
+}
+/**
+ * Result of verifying a download token.
+ *
+ * On failure, `error` is a short human-readable reason suitable for logs.
+ * Do not surface it to untrusted clients — it may reveal which check failed.
+ */
+type VerifyDownloadTokenResult = {
+  valid: true;
+} | {
+  valid: false;
+  error: string;
+};
+/**
+ * Verify a signed download token.
+ *
+ * Returns a discriminated-union result. The function never throws for
+ * verification failures — only malformed inputs at the crypto layer would
+ * surface. Callers should check `result.valid` and log `result.error`.
+ *
+ * @param params - Verification inputs.
+ * @returns Whether the token is valid, plus a reason on failure.
+ */
+declare function verifyDownloadToken(params: VerifyDownloadTokenOptions): VerifyDownloadTokenResult;
+
 //#endregion
 //#region src/webhook/signing.d.ts
 /**
@@ -1552,4 +1641,4 @@ declare function decodeRawEmail(event: EmailReceivedEvent, options?: DecodeRawEm
 declare function verifyRawEmailDownload(downloaded: Buffer | ArrayBuffer | Uint8Array, event: EmailReceivedEvent): Buffer;
 
 //#endregion
-export { DecodeRawEmailOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER as LEGACY_CONFIRMED_HEADER$1, LEGACY_SIGNATURE_HEADER as LEGACY_SIGNATURE_HEADER$1, PAYLOAD_ERRORS as PAYLOAD_ERRORS$1, PRIMITIVE_CONFIRMED_HEADER as PRIMITIVE_CONFIRMED_HEADER$1, PRIMITIVE_SIGNATURE_HEADER as PRIMITIVE_SIGNATURE_HEADER$1, PrimitiveWebhookError as PrimitiveWebhookError$1, RAW_EMAIL_ERRORS as RAW_EMAIL_ERRORS$1, RawEmailDecodeError as RawEmailDecodeError$1, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER as STANDARD_WEBHOOK_ID_HEADER$1, STANDARD_WEBHOOK_SIGNATURE_HEADER as STANDARD_WEBHOOK_SIGNATURE_HEADER$1, STANDARD_WEBHOOK_TIMESTAMP_HEADER as STANDARD_WEBHOOK_TIMESTAMP_HEADER$1, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS as VERIFICATION_ERRORS$1, VerifyOptions, WEBHOOK_VERSION as WEBHOOK_VERSION$1, WebhookErrorCode, WebhookHeaders, WebhookPayloadError as WebhookPayloadError$1, WebhookPayloadErrorCode, WebhookValidationError as WebhookValidationError$1, WebhookValidationErrorCode, WebhookVerificationError as WebhookVerificationError$1, WebhookVerificationErrorCode, confirmedHeaders as confirmedHeaders$1, decodeRawEmail as decodeRawEmail$1, emailReceivedEventJsonSchema as emailReceivedEventJsonSchema$1, getDownloadTimeRemaining as getDownloadTimeRemaining$1, handleWebhook as handleWebhook$1, isDownloadExpired as isDownloadExpired$1, isEmailReceivedEvent as isEmailReceivedEvent$1, isRawIncluded as isRawIncluded$1, parseWebhookEvent as parseWebhookEvent$1, safeValidateEmailReceivedEvent as safeValidateEmailReceivedEvent$1, signStandardWebhooksPayload as signStandardWebhooksPayload$1, signWebhookPayload as signWebhookPayload$1, validateEmailAuth as validateEmailAuth$1, validateEmailReceivedEvent as validateEmailReceivedEvent$1, verifyRawEmailDownload as verifyRawEmailDownload$1, verifyStandardWebhooksSignature as verifyStandardWebhooksSignature$1, verifyWebhookSignature as verifyWebhookSignature$1 };
+export { DecodeRawEmailOptions, GenerateDownloadTokenOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER as LEGACY_CONFIRMED_HEADER$1, LEGACY_SIGNATURE_HEADER as LEGACY_SIGNATURE_HEADER$1, PAYLOAD_ERRORS as PAYLOAD_ERRORS$1, PRIMITIVE_CONFIRMED_HEADER as PRIMITIVE_CONFIRMED_HEADER$1, PRIMITIVE_SIGNATURE_HEADER as PRIMITIVE_SIGNATURE_HEADER$1, PrimitiveWebhookError as PrimitiveWebhookError$1, RAW_EMAIL_ERRORS as RAW_EMAIL_ERRORS$1, RawEmailDecodeError as RawEmailDecodeError$1, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER as STANDARD_WEBHOOK_ID_HEADER$1, STANDARD_WEBHOOK_SIGNATURE_HEADER as STANDARD_WEBHOOK_SIGNATURE_HEADER$1, STANDARD_WEBHOOK_TIMESTAMP_HEADER as STANDARD_WEBHOOK_TIMESTAMP_HEADER$1, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS as VERIFICATION_ERRORS$1, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION as WEBHOOK_VERSION$1, WebhookErrorCode, WebhookHeaders, WebhookPayloadError as WebhookPayloadError$1, WebhookPayloadErrorCode, WebhookValidationError as WebhookValidationError$1, WebhookValidationErrorCode, WebhookVerificationError as WebhookVerificationError$1, WebhookVerificationErrorCode, confirmedHeaders as confirmedHeaders$1, decodeRawEmail as decodeRawEmail$1, emailReceivedEventJsonSchema as emailReceivedEventJsonSchema$1, generateDownloadToken as generateDownloadToken$1, getDownloadTimeRemaining as getDownloadTimeRemaining$1, handleWebhook as handleWebhook$1, isDownloadExpired as isDownloadExpired$1, isEmailReceivedEvent as isEmailReceivedEvent$1, isRawIncluded as isRawIncluded$1, parseWebhookEvent as parseWebhookEvent$1, safeValidateEmailReceivedEvent as safeValidateEmailReceivedEvent$1, signStandardWebhooksPayload as signStandardWebhooksPayload$1, signWebhookPayload as signWebhookPayload$1, validateEmailAuth as validateEmailAuth$1, validateEmailReceivedEvent as validateEmailReceivedEvent$1, verifyDownloadToken as verifyDownloadToken$1, verifyRawEmailDownload as verifyRawEmailDownload$1, verifyStandardWebhooksSignature as verifyStandardWebhooksSignature$1, verifyWebhookSignature as verifyWebhookSignature$1 };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 import { AuthConfidence$1 as AuthConfidence, AuthVerdict$1 as AuthVerdict, DkimResult$1 as DkimResult, DkimSignature, DmarcPolicy$1 as DmarcPolicy, DmarcResult$1 as DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType$1 as EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict$1 as ForwardVerdict, ForwardVerification, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus$1 as ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, SpfResult$1 as SpfResult, UnknownEvent, ValidateEmailAuthResult, WebhookAttachment, WebhookEvent } from "./types-C3ms4R0d.js";
-import { DecodeRawEmailOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER$1 as LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER$1 as LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER$1 as PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER$1 as PRIMITIVE_SIGNATURE_HEADER, PrimitiveWebhookError$1 as PrimitiveWebhookError, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER$1 as STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER$1 as STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER$1 as STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, VerifyOptions, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookErrorCode, WebhookHeaders, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders$1 as confirmedHeaders, decodeRawEmail$1 as decodeRawEmail, emailReceivedEventJsonSchema$1 as emailReceivedEventJsonSchema, getDownloadTimeRemaining$1 as getDownloadTimeRemaining, handleWebhook$1 as handleWebhook, isDownloadExpired$1 as isDownloadExpired, isEmailReceivedEvent$1 as isEmailReceivedEvent, isRawIncluded$1 as isRawIncluded, parseWebhookEvent$1 as parseWebhookEvent, safeValidateEmailReceivedEvent$1 as safeValidateEmailReceivedEvent, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload, validateEmailAuth$1 as validateEmailAuth, validateEmailReceivedEvent$1 as validateEmailReceivedEvent, verifyRawEmailDownload$1 as verifyRawEmailDownload, verifyStandardWebhooksSignature$1 as verifyStandardWebhooksSignature, verifyWebhookSignature$1 as verifyWebhookSignature } from "./index-D2OuDGVz.js";
-export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+import { DecodeRawEmailOptions, GenerateDownloadTokenOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER$1 as LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER$1 as LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER$1 as PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER$1 as PRIMITIVE_SIGNATURE_HEADER, PrimitiveWebhookError$1 as PrimitiveWebhookError, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER$1 as STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER$1 as STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER$1 as STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookErrorCode, WebhookHeaders, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders$1 as confirmedHeaders, decodeRawEmail$1 as decodeRawEmail, emailReceivedEventJsonSchema$1 as emailReceivedEventJsonSchema, generateDownloadToken$1 as generateDownloadToken, getDownloadTimeRemaining$1 as getDownloadTimeRemaining, handleWebhook$1 as handleWebhook, isDownloadExpired$1 as isDownloadExpired, isEmailReceivedEvent$1 as isEmailReceivedEvent, isRawIncluded$1 as isRawIncluded, parseWebhookEvent$1 as parseWebhookEvent, safeValidateEmailReceivedEvent$1 as safeValidateEmailReceivedEvent, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload, validateEmailAuth$1 as validateEmailAuth, validateEmailReceivedEvent$1 as validateEmailReceivedEvent, verifyDownloadToken$1 as verifyDownloadToken, verifyRawEmailDownload$1 as verifyRawEmailDownload, verifyStandardWebhooksSignature$1 as verifyStandardWebhooksSignature, verifyWebhookSignature$1 as verifyWebhookSignature } from "./index-C7tHPMZM.js";
+export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, GenerateDownloadTokenOptions, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature } from "./webhook-uSco6pyX.js";
+import { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature } from "./webhook-C5kOt3fb.js";
 
-export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/oclif/api-command.js

@@ -7,7 +7,7 @@ function flagName(parameterName) {
 function flagDescription(parameter) {
     return parameter.description ?? parameter.name;
 }
-function flagForParameter(parameter) {
+export function flagForParameter(parameter) {
     const common = {
         description: flagDescription(parameter),
         required: parameter.required,
@@ -18,6 +18,9 @@ function flagForParameter(parameter) {
     if (parameter.type === "integer") {
         return Flags.integer(common);
     }
+    if (parameter.enum && parameter.enum.length > 0) {
+        return Flags.string({ ...common, options: parameter.enum });
+    }
     return Flags.string(common);
 }
 function coerceParameterValue(parameter, value) {
@@ -41,20 +44,82 @@ function coerceParameterValue(parameter, value) {
     }
     throw new Errors.CLIError(`Unsupported flag value for --${parameter.name}`);
 }
-function readJsonBody(flags) {
+function cliError(message) {
+    return new Errors.CLIError(message, { exit: 1 });
+}
+function parseJson(source, flagLabel) {
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw cliError(`${flagLabel} is not valid JSON: ${detail}`);
+    }
+}
+export function readJsonBody(flags) {
     const bodyFile = flags["body-file"];
     const body = flags.body;
     if (bodyFile && body) {
-        throw new Errors.CLIError("Use either --body or --body-file, not both");
+        throw cliError("Use either --body or --body-file, not both");
     }
     if (typeof bodyFile === "string") {
-        return JSON.parse(readFileSync(bodyFile, "utf8"));
+        let contents;
+        try {
+            contents = readFileSync(bodyFile, "utf8");
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw cliError(`Could not read --body-file ${bodyFile}: ${detail}`);
+        }
+        return parseJson(contents, `--body-file ${bodyFile}`);
     }
     if (typeof body === "string") {
-        return JSON.parse(body);
+        return parseJson(body, "--body");
     }
     return undefined;
 }
+export function extractErrorPayload(raw) {
+    if (raw &&
+        typeof raw === "object" &&
+        !(raw instanceof Error) &&
+        "error" in raw) {
+        const inner = raw.error;
+        if (inner !== null && inner !== undefined) {
+            return inner;
+        }
+    }
+    return raw;
+}
+function extractCauseDetails(cause) {
+    const details = {};
+    let code;
+    if (!cause || typeof cause !== "object") {
+        return { details };
+    }
+    for (const [key, value] of Object.entries(cause)) {
+        if (typeof value === "string" || typeof value === "number") {
+            details[key] = value;
+            if (key === "code" && typeof value === "string") {
+                code = value;
+            }
+        }
+    }
+    return { code, details };
+}
+export function formatErrorPayload(payload) {
+    if (payload instanceof Error) {
+        const { code, details } = extractCauseDetails(payload.cause);
+        const body = {
+            code: code ?? "client_error",
+            message: payload.message || payload.name || String(payload),
+        };
+        if (Object.keys(details).length > 0) {
+            body.cause = details;
+        }
+        return JSON.stringify(body, null, 2);
+    }
+    return JSON.stringify(payload, null, 2);
+}
 function buildFlags(operation) {
     const flags = {
         "api-key": Flags.string({
@@ -125,9 +190,8 @@ export function createOperationCommand(operation) {
                 responseStyle: "fields",
             });
             if (result.error) {
-                const errorEnvelope = result.error;
-                const errorPayload = errorEnvelope?.error ?? result.error;
-                process.stderr.write(`${JSON.stringify(errorPayload, null, 2)}\n`);
+                const errorPayload = extractErrorPayload(result.error);
+                process.stderr.write(`${formatErrorPayload(errorPayload)}\n`);
                 process.exitCode = 1;
                 return;
             }

package/dist/openapi/index.d.ts

@@ -17,6 +17,7 @@ declare const openapiDocument: Record<string, unknown>;
  */
 type PrimitiveParameterManifest = {
   description: string | null;
+  enum: string[] | null;
   name: string;
   required: boolean;
   type: string;

package/dist/openapi/openapi.generated.js

@@ -355,6 +355,44 @@ export const openapiDocument = {
                     },
                     "401": {
                         "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "409": {
+                        "description": "Domain claim conflicts with existing state. Two error codes\nare possible:\n  * `mx_conflict`: the domain's current MX records point at\n    another mailbox provider. The response includes\n    `error.details.mx_conflict` with the detected provider\n    and a suggested subdomain.\n  * `conflict`: the domain is already claimed by another\n    org, or a pending claim exists for another user.\n",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                },
+                                "examples": {
+                                    "mx_conflict": {
+                                        "summary": "Domain has MX records on another provider",
+                                        "value": {
+                                            "success": false,
+                                            "error": {
+                                                "code": "mx_conflict",
+                                                "message": "Domain is currently receiving mail via another provider",
+                                                "details": {
+                                                    "mx_conflict": {
+                                                        "provider_name": "Google Workspace",
+                                                        "suggested_subdomain": "mail"
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    },
+                                    "already_claimed": {
+                                        "summary": "Domain already claimed by another org",
+                                        "value": {
+                                            "success": false,
+                                            "error": {
+                                                "code": "conflict",
+                                                "message": "Domain is already claimed by another organization"
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
                     }
                 }
             }
@@ -809,7 +847,7 @@ export const openapiDocument = {
             "post": {
                 "operationId": "replayEmailWebhooks",
                 "summary": "Replay email webhooks",
-                "description": "Re-delivers the webhook payload for this email to all active\nendpoints matching the email's domain. Includes rate limiting\nto prevent stampeding.\n",
+                "description": "Re-delivers the webhook payload for this email to all active\nendpoints matching the email's domain. Rate limited per-email\n(short cooldown between successive replays of the same email)\nand per-org (burst + sustained windows), sharing an org-wide\nbudget with delivery replays.\n",
                 "tags": [
                     "Emails"
                 ],
@@ -844,6 +882,9 @@ export const openapiDocument = {
                     },
                     "404": {
                         "$ref": "#/components/responses/NotFound"
+                    },
+                    "429": {
+                        "$ref": "#/components/responses/RateLimited"
                     }
                 }
             }
@@ -1345,7 +1386,7 @@ export const openapiDocument = {
             "post": {
                 "operationId": "replayDelivery",
                 "summary": "Replay a webhook delivery",
-                "description": "Re-sends the stored webhook payload from a previous delivery attempt.\nIf the original endpoint is still active, it is targeted. If the\noriginal endpoint was deleted, the first active endpoint is used.\nDeactivated endpoints cannot be replayed to.\n",
+                "description": "Re-sends the stored webhook payload from a previous delivery attempt.\nIf the original endpoint is still active, it is targeted. If the\noriginal endpoint was deleted, the oldest active endpoint is used.\nDeactivated endpoints cannot be replayed to. Rate limited per-org,\nsharing an org-wide budget with email replays.\n",
                 "tags": [
                     "Webhook Deliveries"
                 ],
@@ -1380,6 +1421,9 @@ export const openapiDocument = {
                     },
                     "404": {
                         "$ref": "#/components/responses/NotFound"
+                    },
+                    "429": {
+                        "$ref": "#/components/responses/RateLimited"
                     }
                 }
             }
@@ -1613,11 +1657,38 @@ export const openapiDocument = {
                                     "not_found",
                                     "validation_error",
                                     "rate_limit_exceeded",
-                                    "internal_error"
+                                    "internal_error",
+                                    "conflict",
+                                    "mx_conflict"
                                 ]
                             },
                             "message": {
                                 "type": "string"
+                            },
+                            "details": {
+                                "type": "object",
+                                "description": "Optional structured data that callers can inspect to recover\nfrom the error. The fields present depend on `code`. Additional\nkeys may be added over time without a major-version bump.\n",
+                                "additionalProperties": true,
+                                "properties": {
+                                    "mx_conflict": {
+                                        "type": "object",
+                                        "description": "Present when `code == mx_conflict`.",
+                                        "required": [
+                                            "provider_name",
+                                            "suggested_subdomain"
+                                        ],
+                                        "properties": {
+                                            "provider_name": {
+                                                "type": "string",
+                                                "description": "Human-readable name of the detected mailbox provider (e.g. \"Google Workspace\")."
+                                            },
+                                            "suggested_subdomain": {
+                                                "type": "string",
+                                                "description": "Subdomain to try instead (e.g. \"mail\" for `mail.example.com`)."
+                                            }
+                                        }
+                                    }
+                                }
                             }
                         },
                         "required": [

package/dist/openapi/operations.generated.js

@@ -113,6 +113,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -152,6 +153,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -175,6 +177,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -198,6 +201,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -221,6 +225,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -229,6 +234,7 @@ export const operationManifest = [
         "queryParams": [
             {
                 "description": "Signed download token from webhook payload",
+                "enum": null,
                 "name": "token",
                 "required": false,
                 "type": "string"
@@ -251,6 +257,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -259,6 +266,7 @@ export const operationManifest = [
         "queryParams": [
             {
                 "description": "Signed download token from webhook payload",
+                "enum": null,
                 "name": "token",
                 "required": false,
                 "type": "string"
@@ -281,6 +289,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -305,42 +314,54 @@ export const operationManifest = [
         "queryParams": [
             {
                 "description": "Pagination cursor from a previous response's `meta.cursor` field.\nFormat: `{ISO-datetime}|{id}`\n",
+                "enum": null,
                 "name": "cursor",
                 "required": false,
                 "type": "string"
             },
             {
                 "description": "Number of results per page",
+                "enum": null,
                 "name": "limit",
                 "required": false,
                 "type": "integer"
             },
             {
                 "description": "Filter by domain ID",
+                "enum": null,
                 "name": "domain_id",
                 "required": false,
                 "type": "string"
             },
             {
                 "description": "Filter by email status",
+                "enum": [
+                    "pending",
+                    "accepted",
+                    "completed",
+                    "rejected"
+                ],
                 "name": "status",
                 "required": false,
                 "type": "string"
             },
             {
                 "description": "Search subject, sender, and recipient (case-insensitive)",
+                "enum": null,
                 "name": "search",
                 "required": false,
                 "type": "string"
             },
             {
                 "description": "Filter emails created on or after this timestamp",
+                "enum": null,
                 "name": "date_from",
                 "required": false,
                 "type": "string"
             },
             {
                 "description": "Filter emails created on or before this timestamp",
+                "enum": null,
                 "name": "date_to",
                 "required": false,
                 "type": "string"
@@ -355,7 +376,7 @@ export const operationManifest = [
         "binaryResponse": false,
         "bodyRequired": false,
         "command": "replay-email-webhooks",
-        "description": "Re-delivers the webhook payload for this email to all active\nendpoints matching the email's domain. Includes rate limiting\nto prevent stampeding.\n",
+        "description": "Re-delivers the webhook payload for this email to all active\nendpoints matching the email's domain. Rate limited per-email\n(short cooldown between successive replays of the same email)\nand per-org (burst + sustained windows), sharing an org-wide\nbudget with delivery replays.\n",
         "hasJsonBody": false,
         "method": "POST",
         "operationId": "replayEmailWebhooks",
@@ -363,6 +384,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -402,6 +424,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -441,6 +464,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -464,6 +488,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -503,6 +528,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -542,6 +568,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Resource UUID",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"
@@ -566,36 +593,47 @@ export const operationManifest = [
         "queryParams": [
             {
                 "description": "Pagination cursor from a previous response's `meta.cursor` field.\nFormat: `{ISO-datetime}|{id}`\n",
+                "enum": null,
                 "name": "cursor",
                 "required": false,
                 "type": "string"
             },
             {
                 "description": "Number of results per page",
+                "enum": null,
                 "name": "limit",
                 "required": false,
                 "type": "integer"
             },
             {
                 "description": "Filter by email ID",
+                "enum": null,
                 "name": "email_id",
                 "required": false,
                 "type": "string"
             },
             {
                 "description": "Filter by delivery status",
+                "enum": [
+                    "pending",
+                    "delivered",
+                    "header_confirmed",
+                    "failed"
+                ],
                 "name": "status",
                 "required": false,
                 "type": "string"
             },
             {
                 "description": "Filter deliveries created on or after this timestamp",
+                "enum": null,
                 "name": "date_from",
                 "required": false,
                 "type": "string"
             },
             {
                 "description": "Filter deliveries created on or before this timestamp",
+                "enum": null,
                 "name": "date_to",
                 "required": false,
                 "type": "string"
@@ -610,7 +648,7 @@ export const operationManifest = [
         "binaryResponse": false,
         "bodyRequired": false,
         "command": "replay-delivery",
-        "description": "Re-sends the stored webhook payload from a previous delivery attempt.\nIf the original endpoint is still active, it is targeted. If the\noriginal endpoint was deleted, the first active endpoint is used.\nDeactivated endpoints cannot be replayed to.\n",
+        "description": "Re-sends the stored webhook payload from a previous delivery attempt.\nIf the original endpoint is still active, it is targeted. If the\noriginal endpoint was deleted, the oldest active endpoint is used.\nDeactivated endpoints cannot be replayed to. Rate limited per-org,\nsharing an org-wide budget with email replays.\n",
         "hasJsonBody": false,
         "method": "POST",
         "operationId": "replayDelivery",
@@ -618,6 +656,7 @@ export const operationManifest = [
         "pathParams": [
             {
                 "description": "Delivery ID (numeric)",
+                "enum": null,
                 "name": "id",
                 "required": true,
                 "type": "string"

package/dist/webhook/index.d.ts

@@ -1,3 +1,3 @@
 import { AuthConfidence$1 as AuthConfidence, AuthVerdict$1 as AuthVerdict, DkimResult$1 as DkimResult, DkimSignature, DmarcPolicy$1 as DmarcPolicy, DmarcResult$1 as DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType$1 as EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict$1 as ForwardVerdict, ForwardVerification, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus$1 as ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, SpfResult$1 as SpfResult, UnknownEvent, ValidateEmailAuthResult, WebhookAttachment, WebhookEvent } from "../types-C3ms4R0d.js";
-import { DecodeRawEmailOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER$1 as LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER$1 as LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER$1 as PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER$1 as PRIMITIVE_SIGNATURE_HEADER, PrimitiveWebhookError$1 as PrimitiveWebhookError, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER$1 as STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER$1 as STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER$1 as STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, VerifyOptions, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookErrorCode, WebhookHeaders, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders$1 as confirmedHeaders, decodeRawEmail$1 as decodeRawEmail, emailReceivedEventJsonSchema$1 as emailReceivedEventJsonSchema, getDownloadTimeRemaining$1 as getDownloadTimeRemaining, handleWebhook$1 as handleWebhook, isDownloadExpired$1 as isDownloadExpired, isEmailReceivedEvent$1 as isEmailReceivedEvent, isRawIncluded$1 as isRawIncluded, parseWebhookEvent$1 as parseWebhookEvent, safeValidateEmailReceivedEvent$1 as safeValidateEmailReceivedEvent, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload, validateEmailAuth$1 as validateEmailAuth, validateEmailReceivedEvent$1 as validateEmailReceivedEvent, verifyRawEmailDownload$1 as verifyRawEmailDownload, verifyStandardWebhooksSignature$1 as verifyStandardWebhooksSignature, verifyWebhookSignature$1 as verifyWebhookSignature } from "../index-D2OuDGVz.js";
-export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+import { DecodeRawEmailOptions, GenerateDownloadTokenOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER$1 as LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER$1 as LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER$1 as PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER$1 as PRIMITIVE_SIGNATURE_HEADER, PrimitiveWebhookError$1 as PrimitiveWebhookError, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER$1 as STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER$1 as STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER$1 as STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookErrorCode, WebhookHeaders, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders$1 as confirmedHeaders, decodeRawEmail$1 as decodeRawEmail, emailReceivedEventJsonSchema$1 as emailReceivedEventJsonSchema, generateDownloadToken$1 as generateDownloadToken, getDownloadTimeRemaining$1 as getDownloadTimeRemaining, handleWebhook$1 as handleWebhook, isDownloadExpired$1 as isDownloadExpired, isEmailReceivedEvent$1 as isEmailReceivedEvent, isRawIncluded$1 as isRawIncluded, parseWebhookEvent$1 as parseWebhookEvent, safeValidateEmailReceivedEvent$1 as safeValidateEmailReceivedEvent, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload, validateEmailAuth$1 as validateEmailAuth, validateEmailReceivedEvent$1 as validateEmailReceivedEvent, verifyDownloadToken$1 as verifyDownloadToken, verifyRawEmailDownload$1 as verifyRawEmailDownload, verifyStandardWebhooksSignature$1 as verifyStandardWebhooksSignature, verifyWebhookSignature$1 as verifyWebhookSignature } from "../index-C7tHPMZM.js";
+export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, GenerateDownloadTokenOptions, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/webhook/index.js

@@ -1,3 +1,3 @@
-import { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature } from "../webhook-uSco6pyX.js";
+import { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature } from "../webhook-C5kOt3fb.js";
 
-export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/{webhook-uSco6pyX.js → webhook-C5kOt3fb.js}

@@ -6043,6 +6043,102 @@ function safeValidateEmailReceivedEvent(input) {
 	};
 }
 
+//#endregion
+//#region src/webhook/download-tokens.ts
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+/**
+* Issue a signed download token.
+*
+* The resulting token is `<base64url-payload>.<base64url-signature>`, where
+* the payload is `{"email_id":"...","exp":...,"aud":"..."}` (snake_case,
+* field order fixed) and the signature is HMAC-SHA256 of the base64url
+* payload string using `secret`.
+*
+* @param params - Token inputs.
+* @returns The signed token string.
+*/
+function generateDownloadToken(params) {
+	const { emailId, expiresAt, audience, secret } = params;
+	const payload = {
+		email_id: emailId,
+		exp: expiresAt,
+		aud: audience
+	};
+	const payloadJson = JSON.stringify(payload);
+	const payloadStr = Buffer.from(payloadJson, "utf8").toString("base64url");
+	const signature = createHmac("sha256", secret).update(payloadStr).digest("base64url");
+	return `${payloadStr}.${signature}`;
+}
+/**
+* Verify a signed download token.
+*
+* Returns a discriminated-union result. The function never throws for
+* verification failures — only malformed inputs at the crypto layer would
+* surface. Callers should check `result.valid` and log `result.error`.
+*
+* @param params - Verification inputs.
+* @returns Whether the token is valid, plus a reason on failure.
+*/
+function verifyDownloadToken(params) {
+	const { token, emailId, audience, secret, nowSeconds } = params;
+	if (typeof token !== "string" || token.length === 0) return {
+		valid: false,
+		error: "Token is empty"
+	};
+	const firstDot = token.indexOf(".");
+	const lastDot = token.lastIndexOf(".");
+	if (firstDot === -1 || firstDot !== lastDot) return {
+		valid: false,
+		error: "Token is malformed: expected one '.'"
+	};
+	const payloadStr = token.slice(0, firstDot);
+	const providedSignature = token.slice(firstDot + 1);
+	if (payloadStr.length === 0 || providedSignature.length === 0) return {
+		valid: false,
+		error: "Token is malformed: empty part"
+	};
+	const expectedSignature = createHmac("sha256", secret).update(payloadStr).digest("base64url");
+	const providedBytes = Buffer.from(providedSignature, "base64url");
+	const expectedBytes = Buffer.from(expectedSignature, "base64url");
+	if (providedBytes.length !== expectedBytes.length || !timingSafeEqual(providedBytes, expectedBytes)) return {
+		valid: false,
+		error: "Invalid signature"
+	};
+	if (!BASE64URL_PATTERN.test(payloadStr)) return {
+		valid: false,
+		error: "Token payload is not valid base64url"
+	};
+	const decodedJson = Buffer.from(payloadStr, "base64url").toString("utf8");
+	let payload;
+	try {
+		payload = JSON.parse(decodedJson);
+	} catch {
+		return {
+			valid: false,
+			error: "Token payload is not valid JSON"
+		};
+	}
+	if (!payload || typeof payload !== "object" || Array.isArray(payload) || typeof payload.email_id !== "string" || typeof payload.aud !== "string" || typeof payload.exp !== "number") return {
+		valid: false,
+		error: "Token payload has wrong shape"
+	};
+	const { email_id, aud, exp } = payload;
+	if (aud !== audience) return {
+		valid: false,
+		error: "Audience mismatch"
+	};
+	if (email_id !== emailId) return {
+		valid: false,
+		error: "Email ID mismatch"
+	};
+	const now = nowSeconds ?? Math.floor(Date.now() / 1e3);
+	if (exp <= now) return {
+		valid: false,
+		error: "Token is expired"
+	};
+	return { valid: true };
+}
+
 //#endregion
 //#region src/webhook/encoding.ts
 const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
@@ -7907,4 +8003,4 @@ function verifyRawEmailDownload(downloaded, event) {
 }
 
 //#endregion
-export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/oclif.manifest.json

@@ -669,6 +669,12 @@
           "required": false,
           "hasDynamicHelp": false,
           "multiple": false,
+          "options": [
+            "pending",
+            "accepted",
+            "completed",
+            "rejected"
+          ],
           "type": "option"
         },
         "search": {
@@ -709,7 +715,7 @@
     "emails:replay-email-webhooks": {
       "aliases": [],
       "args": {},
-      "description": "Re-delivers the webhook payload for this email to all active\nendpoints matching the email's domain. Includes rate limiting\nto prevent stampeding.\n",
+      "description": "Re-delivers the webhook payload for this email to all active\nendpoints matching the email's domain. Rate limited per-email\n(short cooldown between successive replays of the same email)\nand per-org (burst + sustained windows), sharing an org-wide\nbudget with delivery replays.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -1181,6 +1187,12 @@
           "required": false,
           "hasDynamicHelp": false,
           "multiple": false,
+          "options": [
+            "pending",
+            "delivered",
+            "header_confirmed",
+            "failed"
+          ],
           "type": "option"
         },
         "date-from": {
@@ -1213,7 +1225,7 @@
     "webhook-deliveries:replay-delivery": {
       "aliases": [],
       "args": {},
-      "description": "Re-sends the stored webhook payload from a previous delivery attempt.\nIf the original endpoint is still active, it is targeted. If the\noriginal endpoint was deleted, the first active endpoint is used.\nDeactivated endpoints cannot be replayed to.\n",
+      "description": "Re-sends the stored webhook payload from a previous delivery attempt.\nIf the original endpoint is still active, it is targeted. If the\noriginal endpoint was deleted, the oldest active endpoint is used.\nDeactivated endpoints cannot be replayed to. Rate limited per-org,\nsharing an org-wide budget with email replays.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -1251,5 +1263,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.3.0"
+  "version": "0.5.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Official Primitive Node.js SDK — webhook, api, openapi, contract, and parser modules",
   "type": "module",
   "module": "./dist/index.js",
@@ -93,9 +93,9 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
-    "typecheck": "pnpm generate && tsc --noEmit",
-    "lint": "biome check src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/openapi/index.ts src/oclif tests/",
-    "lint:fix": "biome check --write src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/openapi/index.ts src/oclif tests/",
+    "typecheck": "pnpm generate && tsc --noEmit -p tsconfig.typecheck.json",
+    "lint": "biome check --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/openapi/index.ts src/oclif tests/",
+    "lint:fix": "biome check --write --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/openapi/index.ts src/oclif tests/",
     "prepack": "pnpm build && oclif manifest",
     "postpack": "shx rm -f oclif.manifest.json",
     "prepublishOnly": "pnpm build"