@primitivedotdev/sdk 0.24.0 → 0.25.1

package/dist/{index-QTYQpSFt.d.ts → index-DdITDPea.d.ts}

@@ -1,4 +1,4 @@
-import { t as ReceivedEmail } from "./received-email-DNjpq_Wt.js";
+import { m as ReceivedEmail } from "./errors-C53fe686.js";
 
 //#region src/api/generated/core/auth.gen.d.ts
 type AuthToken = string | undefined;
@@ -3369,7 +3369,19 @@ type UpdateFunctionResponses = {
 };
 type UpdateFunctionResponse = UpdateFunctionResponses[keyof UpdateFunctionResponses];
 type TestFunctionData = {
-  body?: never;
+  body?: {
+    /**
+     * Override the synthetic local-part. When set, the
+     * test email is sent to `<local_part>@<picked-domain>`
+     * instead of the default
+     * `__primitive_function_test+<random>@<picked-domain>`.
+     * Must start with an alphanumeric and contain only
+     * letters, digits, dots, plus signs, hyphens, or
+     * underscores; 1-64 characters total.
+     *
+     */
+    local_part?: string;
+  };
   path: {
     /**
      * Resource UUID
@@ -4104,8 +4116,14 @@ declare const updateFunction: <ThrowOnError extends boolean = false>(options: Op
  * Send a test invocation
  *
  * Sends a real test email from a Primitive-controlled sender to a
- * synthetic local-part on one of the org's verified inbound
- * domains. The function fires through the normal MX delivery
+ * local-part on one of the org's verified inbound domains. By
+ * default the recipient is a synthetic
+ * `__primitive_function_test+<random>@<domain>` address that
+ * every handler's catch-all routing receives identically; pass
+ * `local_part` to override and exercise routing logic that
+ * branches on a specific recipient (the common pattern when one
+ * function handles multiple inboxes like `summarize@` and
+ * `action@`). The function fires through the normal MX delivery
  * path, so reply / send-mail calls from inside the handler
  * against the inbound's `email.id` work the same as in
  * production. Returns immediately after the send is queued; the
@@ -4115,6 +4133,8 @@ declare const updateFunction: <ThrowOnError extends boolean = false>(options: Op
  * Requires that the function is currently `deployed`. Returns 422
  * if the function is in `pending` or `failed` state, or if the
  * org has no verified inbound domain to receive the test mail.
+ * Returns 400 if `local_part` is set to a value that does not
+ * match the local-part character set.
  *
  */
 declare const testFunction: <ThrowOnError extends boolean = false>(options: Options<TestFunctionData, ThrowOnError>) => RequestResult<TestFunctionResponses, TestFunctionErrors, ThrowOnError, "fields">;
@@ -4172,6 +4192,86 @@ declare const deleteFunctionSecret: <ThrowOnError extends boolean = false>(optio
  */
 declare const setFunctionSecret: <ThrowOnError extends boolean = false>(options: Options<SetFunctionSecretData, ThrowOnError>) => RequestResult<SetFunctionSecretResponses, SetFunctionSecretErrors, ThrowOnError, "fields">;
 //#endregion
+//#region src/api/verify-signature.d.ts
+/**
+ * Workers-safe webhook signature verification.
+ *
+ * Mirrors `verifyWebhookSignature` from `@primitivedotdev/sdk` but
+ * implements the HMAC-SHA256 step with the Web Crypto API
+ * (`crypto.subtle`) instead of `node:crypto`. The Node version is
+ * still the right choice for server-side handlers running on Node
+ * (it's measurably faster and supports Buffer bodies); this one
+ * exists so a Primitive Function handler can bundle the verifier
+ * without dragging in a `node:crypto` polyfill that inflates the
+ * deploy artifact past the size cap.
+ *
+ * Available natively in Workers, Node 22+, browsers, Deno, and Bun.
+ * Zero polyfill weight, zero new runtime dependencies.
+ *
+ * Surface contract matches the Node verifier exactly: same input
+ * shape, same `WebhookVerificationError` class, same set of error
+ * codes. Existing callers can swap the import path with no other
+ * code changes:
+ *
+ *   // Node (existing):
+ *   import { verifyWebhookSignature } from '@primitivedotdev/sdk';
+ *
+ *   // Workers / in-handler (this file):
+ *   import { verifyWebhookSignature } from '@primitivedotdev/sdk/api';
+ */
+declare const PRIMITIVE_SIGNATURE_HEADER = "Primitive-Signature";
+interface VerifyOptions {
+  /**
+   * The raw request body string. MUST be the exact bytes Primitive
+   * signed; re-serializing parsed JSON produces a different string
+   * and the verification will fail.
+   */
+  rawBody: string;
+  /** Value of the `Primitive-Signature` header. */
+  signatureHeader: string;
+  /** Webhook signing secret. Auto-injected into Function handlers as `env.PRIMITIVE_WEBHOOK_SECRET`. */
+  secret: string;
+  /** Max age in seconds (default: 300). */
+  toleranceSeconds?: number;
+  /** Override current time for testing (unix seconds). */
+  nowSeconds?: number;
+}
+/**
+ * Verify a webhook signature using the Web Crypto API.
+ *
+ * Throws `WebhookVerificationError` on failure with a specific error
+ * code matching the Node verifier's set. Returns `true` on success.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   verifyWebhookSignature,
+ *   WebhookVerificationError,
+ *   PRIMITIVE_SIGNATURE_HEADER,
+ * } from '@primitivedotdev/sdk/api';
+ *
+ * export default {
+ *   async fetch(request: Request, env: { PRIMITIVE_WEBHOOK_SECRET: string }) {
+ *     const rawBody = await request.text();
+ *     try {
+ *       await verifyWebhookSignature({
+ *         rawBody,
+ *         signatureHeader: request.headers.get(PRIMITIVE_SIGNATURE_HEADER) ?? '',
+ *         secret: env.PRIMITIVE_WEBHOOK_SECRET,
+ *       });
+ *     } catch (err) {
+ *       if (err instanceof WebhookVerificationError) {
+ *         return new Response('invalid signature', { status: 401 });
+ *       }
+ *       throw err;
+ *     }
+ *     // ... process the webhook
+ *   },
+ * };
+ * ```
+ */
+declare function verifyWebhookSignature(opts: VerifyOptions): Promise<true>;
+//#endregion
 //#region src/api/index.d.ts
 declare const DEFAULT_API_BASE_URL_1 = "https://www.primitive.dev/api/v1";
 declare const DEFAULT_API_BASE_URL_2 = "https://api.primitive.dev/v1";
@@ -4327,4 +4427,4 @@ declare function createPrimitiveClient(options?: PrimitiveClientOptions): Primit
 declare function client(options?: PrimitiveClientOptions): PrimitiveClient;
 declare const operations: typeof sdk_gen_d_exports;
 //#endregion
-export { replyToEmail as $, TestEndpointError as $a, ReplayDeliveryResponses as $i, EmailDetail as $n, RequestOptions$1 as $o, GetWebhookSecretResponses as $r, CreateFunctionSecretInput as $t, deleteFunction as A, SendPermissionAnyRecipient as Aa, ListFunctionSecretsResponse as Ai, DeleteFunctionSecretErrors as An, UpdateFilterError as Ao, GetFunctionError as Ar, ClientOptions as At, getStorageStats as B, SetFunctionSecretErrors as Ba, ListSentEmailsResponse as Bi, DiscardEmailContentResponses as Bn, UpdateFunctionResponses as Bo, GetSentEmailError as Br, CreateFilterInput as Bt, createFilter as C, SendEmailError as Ca, ListFiltersError as Ci, DeleteFunctionData as Cn, UpdateEndpointData as Co, GetAccountResponses as Cr, CliLogoutData as Ct, deleteEmail as D, SendMailInput as Da, ListFunctionSecretsData as Di, DeleteFunctionResponses as Dn, UpdateEndpointResponse as Do, GetEmailResponse as Dr, CliLogoutResponse as Dt, deleteDomain as E, SendEmailResponses as Ea, ListFiltersResponses as Ei, DeleteFunctionResponse as En, UpdateEndpointInput as Eo, GetEmailErrors as Er, CliLogoutInput as Et, getAccount as F, SentEmailDetail as Fa, ListFunctionsResponse as Fi, DiscardContentResult as Fn, UpdateFunctionData as Fo, GetSendPermissionsError as Fr, CreateEndpointResponse as Ft, listEndpoints as G, StartCliLoginError as Ga, PollCliLoginErrors as Gi, DownloadAttachmentsErrors as Gn, VerifyDomainResponse as Go, GetStorageStatsError as Gr, CreateFunctionErrors as Gt, listDeliveries as H, SetFunctionSecretResponse as Ha, PaginationMeta as Hi, DomainVerifyResult as Hn, VerifyDomainData as Ho, GetSentEmailResponse as Hr, CreateFilterResponses as Ht, getEmail as I, SentEmailStatus as Ia, ListFunctionsResponses as Ii, DiscardEmailContentData as In, UpdateFunctionError as Io, GetSendPermissionsErrors as Ir, CreateEndpointResponses as It, listFunctions as J, StartCliLoginResponse as Ja, PollCliLoginResponses as Ji, DownloadRawEmailData as Jn, Client as Jo, GetStorageStatsResponses as Jr, CreateFunctionResponses as Jt, listFilters as K, StartCliLoginErrors as Ka, PollCliLoginInput as Ki, DownloadAttachmentsResponse as Kn, VerifyDomainResponses as Ko, GetStorageStatsErrors as Kr, CreateFunctionInput as Kt, getFunction as L, SentEmailSummary as La, ListSentEmailsData as Li, DiscardEmailContentError as Ln, UpdateFunctionErrors as Lo, GetSendPermissionsResponse as Lr, CreateFilterData as Lt, discardEmailContent as M, SendPermissionRule as Ma, ListFunctionsData as Mi, DeleteFunctionSecretResponses as Mn, UpdateFilterInput as Mo, GetFunctionResponse as Mr, CreateEndpointError as Mt, downloadAttachments as N, SendPermissionYourDomain as Na, ListFunctionsError as Ni, DeliveryStatus as Nn, UpdateFilterResponse as No, GetFunctionResponses as Nr, CreateEndpointErrors as Nt, deleteEndpoint as O, SendMailResult as Oa, ListFunctionSecretsError as Oi, DeleteFunctionSecretData as On, UpdateEndpointResponses as Oo, GetEmailResponses as Or, CliLogoutResponses as Ot, downloadRawEmail as P, SendPermissionsMeta as Pa, ListFunctionsErrors as Pi, DeliverySummary as Pn, UpdateFilterResponses as Po, GetSendPermissionsData as Pr, CreateEndpointInput as Pt, replayEmailWebhooks as Q, TestEndpointData as Qa, ReplayDeliveryResponse as Qi, DownloadRawEmailResponses as Qn, Options$1 as Qo, GetWebhookSecretResponse as Qr, CreateFunctionSecretErrors as Qt, getSendPermissions as R, SetFunctionSecretData as Ra, ListSentEmailsError as Ri, DiscardEmailContentErrors as Rn, UpdateFunctionInput as Ro, GetSendPermissionsResponses as Rr, CreateFilterError as Rt, createEndpoint as S, SendEmailData as Sa, ListFiltersData as Si, DeleteFilterResponses as Sn, UpdateDomainResponses as So, GetAccountResponse as Sr, CliLoginStartResult as St, createFunctionSecret as T, SendEmailResponse as Ta, ListFiltersResponse as Ti, DeleteFunctionErrors as Tn, UpdateEndpointErrors as To, GetEmailError as Tr, CliLogoutErrors as Tt, listDomains as U, SetFunctionSecretResponses as Ua, PollCliLoginData as Ui, DownloadAttachmentsData as Un, VerifyDomainError as Uo, GetSentEmailResponses as Ur, CreateFunctionData as Ut, getWebhookSecret as V, SetFunctionSecretInput as Va, ListSentEmailsResponses as Vi, Domain as Vn, VerifiedDomain as Vo, GetSentEmailErrors as Vr, CreateFilterResponse as Vt, listEmails as W, StartCliLoginData as Wa, PollCliLoginError as Wi, DownloadAttachmentsError as Wn, VerifyDomainErrors as Wo, GetStorageStatsData as Wr, CreateFunctionError as Wt, pollCliLogin as X, StorageStats as Xa, ReplayDeliveryError as Xi, DownloadRawEmailErrors as Xn, Config as Xo, GetWebhookSecretError as Xr, CreateFunctionSecretData as Xt, listSentEmails as Y, StartCliLoginResponses as Ya, ReplayDeliveryData as Yi, DownloadRawEmailError as Yn, ClientOptions$1 as Yo, GetWebhookSecretData as Yr, CreateFunctionResult as Yt, replayDelivery as Z, SuccessEnvelope as Za, ReplayDeliveryErrors as Zi, DownloadRawEmailResponse as Zn, CreateClientConfig as Zo, GetWebhookSecretErrors as Zr, CreateFunctionSecretError as Zt, createPrimitiveClient as _, SearchEmailsData as _a, ListEndpointsError as _i, DeleteEndpointResponses as _n, UpdateDomainData as _o, GateDenial as _r, AddDomainErrors as _t, PrimitiveApiClientOptions as a, ReplayResult as aa, ListDeliveriesResponses as ai, DeleteDomainErrors as an, TestFunctionErrors as ao, EmailSearchResult as ar, testEndpoint as at, addDomain as b, SearchEmailsResponse as ba, ListEndpointsResponses as bi, DeleteFilterErrors as bn, UpdateDomainInput as bo, GetAccountError as br, AddDomainResponses as bt, PrimitiveClient as c, ReplyToEmailErrors as ca, ListDomainsErrors as ci, DeleteEmailData as cn, TestInvocationResult as co, EmailWebhookStatus as cr, updateDomain as ct, RequestOptions as d, ResourceId as da, ListEmailsData as di, DeleteEmailResponse as dn, UpdateAccountData as do, Filter as dr, updateFunction as dt, ReplayEmailWebhooksData as ea, Limit as ei, CreateFunctionSecretResponse as en, TestEndpointErrors as eo, EmailDetailReply as er, RequestResult as es, rotateWebhookSecret as et, SendInput as f, RotateWebhookSecretData as fa, ListEmailsError as fi, DeleteEmailResponses as fn, UpdateAccountError as fo, FunctionDeployStatus as fr, verifyDomain as ft, createPrimitiveApiClient as g, RotateWebhookSecretResponses as ga, ListEndpointsData as gi, DeleteEndpointResponse as gn, UpdateAccountResponses as go, FunctionSecretWriteResult as gr, AddDomainError as gt, client as h, RotateWebhookSecretResponse as ha, ListEmailsResponses as hi, DeleteEndpointErrors as hn, UpdateAccountResponse as ho, FunctionSecretListItem as hr, AddDomainData as ht, PrimitiveApiClient as i, ReplayEmailWebhooksResponses as ia, ListDeliveriesResponse as ii, DeleteDomainError as in, TestFunctionError as io, EmailSearchMeta as ir, startCliLogin as it, deleteFunctionSecret as j, SendPermissionManagedZone as ja, ListFunctionSecretsResponses as ji, DeleteFunctionSecretResponse as jn, UpdateFilterErrors as jo, GetFunctionErrors as jr, CreateEndpointData as jt, deleteFilter as k, SendPermissionAddress as ka, ListFunctionSecretsErrors as ki, DeleteFunctionSecretError as kn, UpdateFilterData as ko, GetFunctionData as kr, CliLogoutResult as kt, PrimitiveClientOptions as l, ReplyToEmailResponse as la, ListDomainsResponse as li, DeleteEmailError as ln, TestResult as lo, Endpoint as lr, updateEndpoint as lt, SendThreadInput as m, RotateWebhookSecretErrors as ma, ListEmailsResponse as mi, DeleteEndpointError as mn, UpdateAccountInput as mo, FunctionListItem as mr, AccountUpdated as mt, DEFAULT_API_BASE_URL_2 as n, ReplayEmailWebhooksErrors as na, ListDeliveriesError as ni, Cursor as nn, TestEndpointResponses as no, EmailSearchFacets as nr, Auth as ns, sendEmail as nt, PrimitiveApiError as o, ReplyToEmailData as oa, ListDomainsData as oi, DeleteDomainResponse as on, TestFunctionResponse as oo, EmailStatus as or, testFunction as ot, SendResult as p, RotateWebhookSecretError as pa, ListEmailsErrors as pi, DeleteEndpointData as pn, UpdateAccountErrors as po, FunctionDetail as pr, Account as pt, listFunctionSecrets as q, StartCliLoginInput as qa, PollCliLoginResponse as qi, DownloadAttachmentsResponses as qn, WebhookSecret as qo, GetStorageStatsResponse as qr, CreateFunctionResponse as qt, ForwardInput as r, ReplayEmailWebhooksResponse as ra, ListDeliveriesErrors as ri, DeleteDomainData as rn, TestFunctionData as ro, EmailSearchHighlights as rr, setFunctionSecret as rt, PrimitiveApiErrorDetails as s, ReplyToEmailError as sa, ListDomainsError as si, DeleteDomainResponses as sn, TestFunctionResponses as so, EmailSummary as sr, updateAccount as st, DEFAULT_API_BASE_URL_1 as t, ReplayEmailWebhooksError as ta, ListDeliveriesData as ti, CreateFunctionSecretResponses as tn, TestEndpointResponse as to, EmailSearchFacetBucket as tr, ResponseStyle as ts, searchEmails as tt, ReplyInput as u, ReplyToEmailResponses as ua, ListDomainsResponses as ui, DeleteEmailErrors as un, UnverifiedDomain as uo, ErrorResponse as ur, updateFilter as ut, operations as v, SearchEmailsError as va, ListEndpointsErrors as vi, DeleteFilterData as vn, UpdateDomainError as vo, GateFix as vr, AddDomainInput as vt, createFunction as w, SendEmailErrors as wa, ListFiltersErrors as wi, DeleteFunctionError as wn, UpdateEndpointError as wo, GetEmailData as wr, CliLogoutError as wt, cliLogout as x, SearchEmailsResponses as xa, ListEnvelope as xi, DeleteFilterResponse as xn, UpdateDomainResponse as xo, GetAccountErrors as xr, CliLoginPollResult as xt, Options as y, SearchEmailsErrors as ya, ListEndpointsResponse as yi, DeleteFilterError as yn, UpdateDomainErrors as yo, GetAccountData as yr, AddDomainResponse as yt, getSentEmail as z, SetFunctionSecretError as za, ListSentEmailsErrors as zi, DiscardEmailContentResponse as zn, UpdateFunctionResponse as zo, GetSentEmailData as zr, CreateFilterErrors as zt };
+export { pollCliLogin as $, StorageStats as $a, ReplayDeliveryError as $i, DownloadRawEmailErrors as $n, Config as $o, GetWebhookSecretError as $r, CreateFunctionSecretData as $t, deleteEmail as A, SendMailInput as Aa, ListFunctionSecretsData as Ai, DeleteFunctionResponses as An, UpdateEndpointResponse as Ao, GetEmailResponse as Ar, CliLogoutResponse as At, getFunction as B, SentEmailSummary as Ba, ListSentEmailsData as Bi, DiscardEmailContentError as Bn, UpdateFunctionErrors as Bo, GetSendPermissionsResponse as Br, CreateFilterData as Bt, addDomain as C, SearchEmailsResponse as Ca, ListEndpointsResponses as Ci, DeleteFilterErrors as Cn, UpdateDomainInput as Co, GetAccountError as Cr, AddDomainResponses as Ct, createFunction as D, SendEmailErrors as Da, ListFiltersErrors as Di, DeleteFunctionError as Dn, UpdateEndpointError as Do, GetEmailData as Dr, CliLogoutError as Dt, createFilter as E, SendEmailError as Ea, ListFiltersError as Ei, DeleteFunctionData as En, UpdateEndpointData as Eo, GetAccountResponses as Er, CliLogoutData as Et, discardEmailContent as F, SendPermissionRule as Fa, ListFunctionsData as Fi, DeleteFunctionSecretResponses as Fn, UpdateFilterInput as Fo, GetFunctionResponse as Fr, CreateEndpointError as Ft, listDeliveries as G, SetFunctionSecretResponse as Ga, PaginationMeta as Gi, DomainVerifyResult as Gn, VerifyDomainData as Go, GetSentEmailResponse as Gr, CreateFilterResponses as Gt, getSentEmail as H, SetFunctionSecretError as Ha, ListSentEmailsErrors as Hi, DiscardEmailContentResponse as Hn, UpdateFunctionResponse as Ho, GetSentEmailData as Hr, CreateFilterErrors as Ht, downloadAttachments as I, SendPermissionYourDomain as Ia, ListFunctionsError as Ii, DeliveryStatus as In, UpdateFilterResponse as Io, GetFunctionResponses as Ir, CreateEndpointErrors as It, listEndpoints as J, StartCliLoginError as Ja, PollCliLoginErrors as Ji, DownloadAttachmentsErrors as Jn, VerifyDomainResponse as Jo, GetStorageStatsError as Jr, CreateFunctionErrors as Jt, listDomains as K, SetFunctionSecretResponses as Ka, PollCliLoginData as Ki, DownloadAttachmentsData as Kn, VerifyDomainError as Ko, GetSentEmailResponses as Kr, CreateFunctionData as Kt, downloadRawEmail as L, SendPermissionsMeta as La, ListFunctionsErrors as Li, DeliverySummary as Ln, UpdateFilterResponses as Lo, GetSendPermissionsData as Lr, CreateEndpointInput as Lt, deleteFilter as M, SendPermissionAddress as Ma, ListFunctionSecretsErrors as Mi, DeleteFunctionSecretError as Mn, UpdateFilterData as Mo, GetFunctionData as Mr, CliLogoutResult as Mt, deleteFunction as N, SendPermissionAnyRecipient as Na, ListFunctionSecretsResponse as Ni, DeleteFunctionSecretErrors as Nn, UpdateFilterError as No, GetFunctionError as Nr, ClientOptions as Nt, createFunctionSecret as O, SendEmailResponse as Oa, ListFiltersResponse as Oi, DeleteFunctionErrors as On, UpdateEndpointErrors as Oo, GetEmailError as Or, CliLogoutErrors as Ot, deleteFunctionSecret as P, SendPermissionManagedZone as Pa, ListFunctionSecretsResponses as Pi, DeleteFunctionSecretResponse as Pn, UpdateFilterErrors as Po, GetFunctionErrors as Pr, CreateEndpointData as Pt, listSentEmails as Q, StartCliLoginResponses as Qa, ReplayDeliveryData as Qi, DownloadRawEmailError as Qn, ClientOptions$1 as Qo, GetWebhookSecretData as Qr, CreateFunctionResult as Qt, getAccount as R, SentEmailDetail as Ra, ListFunctionsResponse as Ri, DiscardContentResult as Rn, UpdateFunctionData as Ro, GetSendPermissionsError as Rr, CreateEndpointResponse as Rt, Options as S, SearchEmailsErrors as Sa, ListEndpointsResponse as Si, DeleteFilterError as Sn, UpdateDomainErrors as So, GetAccountData as Sr, AddDomainResponse as St, createEndpoint as T, SendEmailData as Ta, ListFiltersData as Ti, DeleteFilterResponses as Tn, UpdateDomainResponses as To, GetAccountResponse as Tr, CliLoginStartResult as Tt, getStorageStats as U, SetFunctionSecretErrors as Ua, ListSentEmailsResponse as Ui, DiscardEmailContentResponses as Un, UpdateFunctionResponses as Uo, GetSentEmailError as Ur, CreateFilterInput as Ut, getSendPermissions as V, SetFunctionSecretData as Va, ListSentEmailsError as Vi, DiscardEmailContentErrors as Vn, UpdateFunctionInput as Vo, GetSendPermissionsResponses as Vr, CreateFilterError as Vt, getWebhookSecret as W, SetFunctionSecretInput as Wa, ListSentEmailsResponses as Wi, Domain as Wn, VerifiedDomain as Wo, GetSentEmailErrors as Wr, CreateFilterResponse as Wt, listFunctionSecrets as X, StartCliLoginInput as Xa, PollCliLoginResponse as Xi, DownloadAttachmentsResponses as Xn, WebhookSecret as Xo, GetStorageStatsResponse as Xr, CreateFunctionResponse as Xt, listFilters as Y, StartCliLoginErrors as Ya, PollCliLoginInput as Yi, DownloadAttachmentsResponse as Yn, VerifyDomainResponses as Yo, GetStorageStatsErrors as Yr, CreateFunctionInput as Yt, listFunctions as Z, StartCliLoginResponse as Za, PollCliLoginResponses as Zi, DownloadRawEmailData as Zn, Client as Zo, GetStorageStatsResponses as Zr, CreateFunctionResponses as Zt, createPrimitiveClient as _, RotateWebhookSecretErrors as _a, ListEmailsResponse as _i, DeleteEndpointError as _n, UpdateAccountInput as _o, FunctionListItem as _r, AccountUpdated as _t, PrimitiveApiClientOptions as a, ReplayEmailWebhooksErrors as aa, ListDeliveriesError as ai, Cursor as an, TestEndpointResponses as ao, EmailSearchFacets as ar, Auth as as, sendEmail as at, VerifyOptions as b, SearchEmailsData as ba, ListEndpointsError as bi, DeleteEndpointResponses as bn, UpdateDomainData as bo, GateDenial as br, AddDomainErrors as bt, PrimitiveClient as c, ReplayResult as ca, ListDeliveriesResponses as ci, DeleteDomainErrors as cn, TestFunctionErrors as co, EmailSearchResult as cr, testEndpoint as ct, RequestOptions as d, ReplyToEmailErrors as da, ListDomainsErrors as di, DeleteEmailData as dn, TestInvocationResult as do, EmailWebhookStatus as dr, updateDomain as dt, ReplayDeliveryErrors as ea, GetWebhookSecretErrors as ei, CreateFunctionSecretError as en, SuccessEnvelope as eo, DownloadRawEmailResponse as er, CreateClientConfig as es, replayDelivery as et, SendInput as f, ReplyToEmailResponse as fa, ListDomainsResponse as fi, DeleteEmailError as fn, TestResult as fo, Endpoint as fr, updateEndpoint as ft, createPrimitiveApiClient as g, RotateWebhookSecretError as ga, ListEmailsErrors as gi, DeleteEndpointData as gn, UpdateAccountErrors as go, FunctionDetail as gr, Account as gt, client as h, RotateWebhookSecretData as ha, ListEmailsError as hi, DeleteEmailResponses as hn, UpdateAccountError as ho, FunctionDeployStatus as hr, verifyDomain as ht, PrimitiveApiClient as i, ReplayEmailWebhooksError as ia, ListDeliveriesData as ii, CreateFunctionSecretResponses as in, TestEndpointResponse as io, EmailSearchFacetBucket as ir, ResponseStyle as is, searchEmails as it, deleteEndpoint as j, SendMailResult as ja, ListFunctionSecretsError as ji, DeleteFunctionSecretData as jn, UpdateEndpointResponses as jo, GetEmailResponses as jr, CliLogoutResponses as jt, deleteDomain as k, SendEmailResponses as ka, ListFiltersResponses as ki, DeleteFunctionResponse as kn, UpdateEndpointInput as ko, GetEmailErrors as kr, CliLogoutInput as kt, PrimitiveClientOptions as l, ReplyToEmailData as la, ListDomainsData as li, DeleteDomainResponse as ln, TestFunctionResponse as lo, EmailStatus as lr, testFunction as lt, SendThreadInput as m, ResourceId as ma, ListEmailsData as mi, DeleteEmailResponse as mn, UpdateAccountData as mo, Filter as mr, updateFunction as mt, DEFAULT_API_BASE_URL_2 as n, ReplayDeliveryResponses as na, GetWebhookSecretResponses as ni, CreateFunctionSecretInput as nn, TestEndpointError as no, EmailDetail as nr, RequestOptions$1 as ns, replyToEmail as nt, PrimitiveApiError as o, ReplayEmailWebhooksResponse as oa, ListDeliveriesErrors as oi, DeleteDomainData as on, TestFunctionData as oo, EmailSearchHighlights as or, setFunctionSecret as ot, SendResult as p, ReplyToEmailResponses as pa, ListDomainsResponses as pi, DeleteEmailErrors as pn, UnverifiedDomain as po, ErrorResponse as pr, updateFilter as pt, listEmails as q, StartCliLoginData as qa, PollCliLoginError as qi, DownloadAttachmentsError as qn, VerifyDomainErrors as qo, GetStorageStatsData as qr, CreateFunctionError as qt, ForwardInput as r, ReplayEmailWebhooksData as ra, Limit as ri, CreateFunctionSecretResponse as rn, TestEndpointErrors as ro, EmailDetailReply as rr, RequestResult as rs, rotateWebhookSecret as rt, PrimitiveApiErrorDetails as s, ReplayEmailWebhooksResponses as sa, ListDeliveriesResponse as si, DeleteDomainError as sn, TestFunctionError as so, EmailSearchMeta as sr, startCliLogin as st, DEFAULT_API_BASE_URL_1 as t, ReplayDeliveryResponse as ta, GetWebhookSecretResponse as ti, CreateFunctionSecretErrors as tn, TestEndpointData as to, DownloadRawEmailResponses as tr, Options$1 as ts, replayEmailWebhooks as tt, ReplyInput as u, ReplyToEmailError as ua, ListDomainsError as ui, DeleteDomainResponses as un, TestFunctionResponses as uo, EmailSummary as ur, updateAccount as ut, operations as v, RotateWebhookSecretResponse as va, ListEmailsResponses as vi, DeleteEndpointErrors as vn, UpdateAccountResponse as vo, FunctionSecretListItem as vr, AddDomainData as vt, cliLogout as w, SearchEmailsResponses as wa, ListEnvelope as wi, DeleteFilterResponse as wn, UpdateDomainResponse as wo, GetAccountErrors as wr, CliLoginPollResult as wt, verifyWebhookSignature as x, SearchEmailsError as xa, ListEndpointsErrors as xi, DeleteFilterData as xn, UpdateDomainError as xo, GateFix as xr, AddDomainInput as xt, PRIMITIVE_SIGNATURE_HEADER as y, RotateWebhookSecretResponses as ya, ListEndpointsData as yi, DeleteEndpointResponse as yn, UpdateAccountResponses as yo, FunctionSecretWriteResult as yr, AddDomainError as yt, getEmail as z, SentEmailStatus as za, ListFunctionsResponses as zi, DiscardEmailContentData as zn, UpdateFunctionError as zo, GetSendPermissionsErrors as zr, CreateEndpointResponses as zt };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { A as UnknownEvent, C as ParsedDataFailed, D as RawContentDownloadOnly, E as RawContent, M as WebhookAttachment, N as WebhookEvent, O as RawContentInline, S as ParsedDataComplete, T as ParsedStatus, _ as ForwardResultInline, a as DmarcPolicy, b as KnownWebhookEvent, c as EmailAnalysis, d as EventType, f as ForwardAnalysis, g as ForwardResultAttachmentSkipped, h as ForwardResultAttachmentAnalyzed, i as DkimSignature, j as ValidateEmailAuthResult, k as SpfResult, l as EmailAuth, m as ForwardResult, n as AuthVerdict, o as DmarcResult, p as ForwardOriginalSender, r as DkimResult, s as EmailAddress, t as AuthConfidence, u as EmailReceivedEvent, v as ForwardVerdict, w as ParsedError, x as ParsedData, y as ForwardVerification } from "./types-9vXGZjPd.js";
-import { a as buildReplySubject, c as parseHeaderAddress, i as buildForwardSubject, n as ReceivedEmailAddress, o as formatAddress, r as ReceivedEmailThread, s as normalizeReceivedEmail, t as ReceivedEmail } from "./received-email-DNjpq_Wt.js";
-import { _ as createPrimitiveClient, c as PrimitiveClient, f as SendInput, h as client, l as PrimitiveClientOptions, m as SendThreadInput, o as PrimitiveApiError, p as SendResult, r as ForwardInput, u as ReplyInput } from "./index-QTYQpSFt.js";
-import { A as VerifyOptions, B as PAYLOAD_ERRORS, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, G as VERIFICATION_ERRORS, H as RAW_EMAIL_ERRORS, I as generateDownloadToken, J as WebhookPayloadErrorCode, K as WebhookErrorCode, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, Q as WebhookVerificationErrorCode, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, U as RawEmailDecodeError, V as PrimitiveWebhookError, W as RawEmailDecodeErrorCode, X as WebhookValidationErrorCode, Y as WebhookValidationError, Z as WebhookVerificationError, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, q as WebhookPayloadError, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "./index-CDlwyxdp.js";
+import { _ as buildForwardSubject, a as RawEmailDecodeErrorCode, b as normalizeReceivedEmail, c as WebhookPayloadError, d as WebhookValidationErrorCode, f as WebhookVerificationError, g as ReceivedEmailThread, h as ReceivedEmailAddress, i as RawEmailDecodeError, l as WebhookPayloadErrorCode, m as ReceivedEmail, n as PrimitiveWebhookError, o as VERIFICATION_ERRORS, p as WebhookVerificationErrorCode, r as RAW_EMAIL_ERRORS, s as WebhookErrorCode, t as PAYLOAD_ERRORS, u as WebhookValidationError, v as buildReplySubject, x as parseHeaderAddress, y as formatAddress } from "./errors-C53fe686.js";
+import { _ as createPrimitiveClient, c as PrimitiveClient, f as SendInput, h as client, l as PrimitiveClientOptions, m as SendThreadInput, o as PrimitiveApiError, p as SendResult, r as ForwardInput, u as ReplyInput } from "./index-DdITDPea.js";
+import { A as VerifyOptions, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, I as generateDownloadToken, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "./index-Dbx9udpX.js";
 
 //#region src/index.d.ts
 declare const primitive: {

package/dist/index.js

@@ -1,6 +1,6 @@
-import { a as parseHeaderAddress, i as normalizeReceivedEmail, n as buildReplySubject, r as formatAddress, t as buildForwardSubject } from "./received-email-D6tKtWwW.js";
-import { a as PrimitiveClient, c as createPrimitiveClient, i as PrimitiveApiError, o as client } from "./api-BjzvA2Fy.js";
-import { A as PRIMITIVE_CONFIRMED_HEADER, B as RAW_EMAIL_ERRORS, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, G as WebhookVerificationError, H as VERIFICATION_ERRORS, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, R as PAYLOAD_ERRORS, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, U as WebhookPayloadError, V as RawEmailDecodeError, W as WebhookValidationError, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict, z as PrimitiveWebhookError } from "./webhook-rUjGV6Zu.js";
+import { a as VERIFICATION_ERRORS, c as WebhookVerificationError, d as formatAddress, f as normalizeReceivedEmail, i as RawEmailDecodeError, l as buildForwardSubject, n as PrimitiveWebhookError, o as WebhookPayloadError, p as parseHeaderAddress, r as RAW_EMAIL_ERRORS, s as WebhookValidationError, t as PAYLOAD_ERRORS, u as buildReplySubject } from "./errors-x91I_yEt.js";
+import { a as PrimitiveClient, c as createPrimitiveClient, i as PrimitiveApiError, o as client } from "./api-CoP5vKPK.js";
+import { A as PRIMITIVE_CONFIRMED_HEADER, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict } from "./webhook-DJkfUnFZ.js";
 //#region src/index.ts
 const primitive = {
 	client,

package/dist/openapi/openapi.generated.js

@@ -2569,10 +2569,30 @@ export const openapiDocument = {
             "post": {
                 "operationId": "testFunction",
                 "summary": "Send a test invocation",
-                "description": "Sends a real test email from a Primitive-controlled sender to a\nsynthetic local-part on one of the org's verified inbound\ndomains. The function fires through the normal MX delivery\npath, so reply / send-mail calls from inside the handler\nagainst the inbound's `email.id` work the same as in\nproduction. Returns immediately after the send is queued; the\ninvocation appears on the function's invocations list within a\nfew seconds.\n\nRequires that the function is currently `deployed`. Returns 422\nif the function is in `pending` or `failed` state, or if the\norg has no verified inbound domain to receive the test mail.\n",
+                "description": "Sends a real test email from a Primitive-controlled sender to a\nlocal-part on one of the org's verified inbound domains. By\ndefault the recipient is a synthetic\n`__primitive_function_test+<random>@<domain>` address that\nevery handler's catch-all routing receives identically; pass\n`local_part` to override and exercise routing logic that\nbranches on a specific recipient (the common pattern when one\nfunction handles multiple inboxes like `summarize@` and\n`action@`). The function fires through the normal MX delivery\npath, so reply / send-mail calls from inside the handler\nagainst the inbound's `email.id` work the same as in\nproduction. Returns immediately after the send is queued; the\ninvocation appears on the function's invocations list within a\nfew seconds.\n\nRequires that the function is currently `deployed`. Returns 422\nif the function is in `pending` or `failed` state, or if the\norg has no verified inbound domain to receive the test mail.\nReturns 400 if `local_part` is set to a value that does not\nmatch the local-part character set.\n",
                 "tags": [
                     "Functions"
                 ],
+                "requestBody": {
+                    "required": false,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "type": "object",
+                                "properties": {
+                                    "local_part": {
+                                        "type": "string",
+                                        "description": "Override the synthetic local-part. When set, the\ntest email is sent to `<local_part>@<picked-domain>`\ninstead of the default\n`__primitive_function_test+<random>@<picked-domain>`.\nMust start with an alphanumeric and contain only\nletters, digits, dots, plus signs, hyphens, or\nunderscores; 1-64 characters total.\n",
+                                        "minLength": 1,
+                                        "maxLength": 64,
+                                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$",
+                                        "example": "summarize"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
                 "responses": {
                     "200": {
                         "description": "Test send queued",

package/dist/openapi/operations.generated.js

@@ -3034,8 +3034,8 @@ export const operationManifest = [
         "binaryResponse": false,
         "bodyRequired": false,
         "command": "test-function",
-        "description": "Sends a real test email from a Primitive-controlled sender to a\nsynthetic local-part on one of the org's verified inbound\ndomains. The function fires through the normal MX delivery\npath, so reply / send-mail calls from inside the handler\nagainst the inbound's `email.id` work the same as in\nproduction. Returns immediately after the send is queued; the\ninvocation appears on the function's invocations list within a\nfew seconds.\n\nRequires that the function is currently `deployed`. Returns 422\nif the function is in `pending` or `failed` state, or if the\norg has no verified inbound domain to receive the test mail.\n",
-        "hasJsonBody": false,
+        "description": "Sends a real test email from a Primitive-controlled sender to a\nlocal-part on one of the org's verified inbound domains. By\ndefault the recipient is a synthetic\n`__primitive_function_test+<random>@<domain>` address that\nevery handler's catch-all routing receives identically; pass\n`local_part` to override and exercise routing logic that\nbranches on a specific recipient (the common pattern when one\nfunction handles multiple inboxes like `summarize@` and\n`action@`). The function fires through the normal MX delivery\npath, so reply / send-mail calls from inside the handler\nagainst the inbound's `email.id` work the same as in\nproduction. Returns immediately after the send is queued; the\ninvocation appears on the function's invocations list within a\nfew seconds.\n\nRequires that the function is currently `deployed`. Returns 422\nif the function is in `pending` or `failed` state, or if the\norg has no verified inbound domain to receive the test mail.\nReturns 400 if `local_part` is set to a value that does not\nmatch the local-part character set.\n",
+        "hasJsonBody": true,
         "method": "POST",
         "operationId": "testFunction",
         "path": "/functions/{id}/test",
@@ -3049,7 +3049,19 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
-        "requestSchema": null,
+        "requestSchema": {
+            "type": "object",
+            "properties": {
+                "local_part": {
+                    "type": "string",
+                    "description": "Override the synthetic local-part. When set, the\ntest email is sent to `<local_part>@<picked-domain>`\ninstead of the default\n`__primitive_function_test+<random>@<picked-domain>`.\nMust start with an alphanumeric and contain only\nletters, digits, dots, plus signs, hyphens, or\nunderscores; 1-64 characters total.\n",
+                    "minLength": 1,
+                    "maxLength": 64,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$",
+                    "example": "summarize"
+                }
+            }
+        },
         "responseSchema": {
             "type": "object",
             "description": "Metadata returned by POST /functions/{id}/test. The send is\nqueued; the actual invocation lands on the function's\ninvocations list a few seconds later as the inbound mail\ntraverses the MX path.\n",

package/dist/webhook/errors.js

@@ -0,0 +1,224 @@
+// -----------------------------------------------------------------------------
+// Error Definitions (Single Source of Truth)
+// -----------------------------------------------------------------------------
+/**
+ * Verification error definitions.
+ * Use these for documentation, dashboards, and i18n.
+ */
+export const VERIFICATION_ERRORS = {
+    INVALID_SIGNATURE_HEADER: {
+        message: "Missing or malformed Primitive-Signature header",
+        suggestion: "Check that you're reading the correct header (Primitive-Signature) and it's being passed correctly from your web framework.",
+    },
+    TIMESTAMP_OUT_OF_RANGE: {
+        message: "Timestamp is too old (possible replay attack)",
+        suggestion: "This could indicate a replay attack, network delay, or server clock drift. Check your server's time is synced.",
+    },
+    SIGNATURE_MISMATCH: {
+        message: "Signature doesn't match expected value",
+        suggestion: "Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON).",
+    },
+    MISSING_SECRET: {
+        message: "No webhook secret was provided",
+        suggestion: "Pass your webhook secret from the Primitive dashboard. Check that the environment variable is set.",
+    },
+};
+/**
+ * Payload parsing error definitions.
+ * Use these for documentation, dashboards, and i18n.
+ */
+export const PAYLOAD_ERRORS = {
+    PAYLOAD_NULL: {
+        message: "Webhook payload is null",
+        suggestion: "Ensure you're passing the parsed JSON body, not null. Check your framework's body parsing middleware.",
+    },
+    PAYLOAD_UNDEFINED: {
+        message: "Webhook payload is undefined",
+        suggestion: "The payload was not provided. Make sure you're passing the request body to the handler.",
+    },
+    PAYLOAD_WRONG_TYPE: {
+        message: "Webhook payload must be an object",
+        suggestion: "The payload should be a parsed JSON object. Check that you're not passing a string or other primitive.",
+    },
+    PAYLOAD_IS_ARRAY: {
+        message: "Webhook payload is an array, expected object",
+        suggestion: "Primitive webhooks are single event objects, not arrays. Check the payload structure.",
+    },
+    PAYLOAD_MISSING_EVENT: {
+        message: "Webhook payload missing 'event' field",
+        suggestion: "All webhook payloads must have an 'event' field. This may not be a valid Primitive webhook.",
+    },
+    PAYLOAD_UNKNOWN_EVENT: {
+        message: "Unknown webhook event type",
+        suggestion: "This event type is not recognized. You may need to update your SDK or handle unknown events gracefully.",
+    },
+    PAYLOAD_EMPTY_BODY: {
+        message: "Request body is empty",
+        suggestion: "The request body was empty. Ensure the webhook is sending data and your framework is parsing it correctly.",
+    },
+    JSON_PARSE_FAILED: {
+        message: "Failed to parse JSON body",
+        suggestion: "The request body is not valid JSON. Check the raw body content and Content-Type header.",
+    },
+    INVALID_ENCODING: {
+        message: "Invalid body encoding",
+        suggestion: "The request body encoding is not supported. Primitive webhooks use UTF-8 encoded JSON.",
+    },
+};
+/**
+ * Raw email decode error definitions.
+ * Use these for documentation, dashboards, and i18n.
+ */
+export const RAW_EMAIL_ERRORS = {
+    NOT_INCLUDED: {
+        message: "Raw email content not included inline",
+        suggestion: "Use the download URL at event.email.content.download.url to fetch the raw email.",
+    },
+    INVALID_BASE64: {
+        message: "Raw email content is not valid base64",
+        suggestion: "The raw email data is malformed. Fetch the raw email from the download URL or regenerate the webhook payload.",
+    },
+    HASH_MISMATCH: {
+        message: "SHA-256 hash verification failed",
+        suggestion: "The raw email data may be corrupted. Try downloading from the URL instead.",
+    },
+};
+/**
+ * Base class for all Primitive webhook errors.
+ *
+ * Catch this to handle any error from the SDK in a single catch block.
+ *
+ * @example
+ * ```typescript
+ * import { handleWebhook, PrimitiveWebhookError } from '@primitivedotdev/sdk';
+ *
+ * try {
+ *   const event = handleWebhook({ body, headers, secret });
+ * } catch (err) {
+ *   if (err instanceof PrimitiveWebhookError) {
+ *     console.error(`[${err.code}] ${err.message}`);
+ *     return res.status(400).json({ error: err.code });
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+export class PrimitiveWebhookError extends Error {
+    /**
+     * Formats the error for logging/display.
+     */
+    toString() {
+        return `${this.name} [${this.code}]: ${this.message}\n\nSuggestion: ${this.suggestion}`;
+    }
+    /**
+     * Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            suggestion: this.suggestion,
+        };
+    }
+}
+/**
+ * Error thrown when webhook signature verification fails.
+ *
+ * Use the `code` property to programmatically handle specific error cases.
+ */
+export class WebhookVerificationError extends PrimitiveWebhookError {
+    code;
+    suggestion;
+    constructor(code, message, suggestion) {
+        super(message ?? VERIFICATION_ERRORS[code].message);
+        this.name = "WebhookVerificationError";
+        this.code = code;
+        this.suggestion = suggestion ?? VERIFICATION_ERRORS[code].suggestion;
+    }
+}
+/**
+ * Error thrown when webhook payload parsing fails (lightweight parser).
+ *
+ * Use the `code` property for programmatic handling and monitoring.
+ * The `suggestion` property contains actionable guidance for fixing the issue.
+ */
+export class WebhookPayloadError extends PrimitiveWebhookError {
+    code;
+    suggestion;
+    /** Original error if this wraps another error (e.g., JSON.parse failure) */
+    cause;
+    constructor(code, message, suggestion, cause) {
+        super(message ?? PAYLOAD_ERRORS[code].message);
+        this.name = "WebhookPayloadError";
+        this.code = code;
+        this.suggestion = suggestion ?? PAYLOAD_ERRORS[code].suggestion;
+        this.cause = cause;
+    }
+}
+/**
+ * Error thrown when schema validation fails.
+ */
+export class WebhookValidationError extends PrimitiveWebhookError {
+    code = "SCHEMA_VALIDATION_FAILED";
+    suggestion;
+    /** The specific field path that failed (e.g., "email.headers.from") */
+    field;
+    /** Original schema validation errors for advanced debugging */
+    validationErrors;
+    /** Number of additional validation errors beyond the first */
+    additionalErrorCount;
+    constructor(field, message, suggestion, validationErrors) {
+        super(message);
+        this.name = "WebhookValidationError";
+        this.field = field;
+        this.suggestion = suggestion;
+        this.validationErrors = validationErrors;
+        this.additionalErrorCount = Math.max(0, validationErrors.length - 1);
+    }
+    /**
+     * Formats the error for logging/display.
+     * Includes error count and suggestion.
+     */
+    toString() {
+        let output = `${this.name} [${this.code}]: ${this.message}`;
+        if (this.additionalErrorCount > 0) {
+            output += ` (and ${this.additionalErrorCount} more validation error${this.additionalErrorCount > 1 ? "s" : ""})`;
+        }
+        output += `\n\nSuggestion: ${this.suggestion}`;
+        return output;
+    }
+    /**
+     * Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            field: this.field,
+            message: this.message,
+            suggestion: this.suggestion,
+            additionalErrorCount: this.additionalErrorCount,
+        };
+    }
+}
+// -----------------------------------------------------------------------------
+// Raw Email Decode Errors
+// -----------------------------------------------------------------------------
+/**
+ * Error thrown when raw email decoding or verification fails.
+ *
+ * Use the `code` property to determine the failure reason:
+ * - `NOT_INCLUDED`: Raw email not inline, must download from URL
+ * - `HASH_MISMATCH`: SHA-256 verification failed, content may be corrupted
+ */
+export class RawEmailDecodeError extends PrimitiveWebhookError {
+    code;
+    suggestion;
+    constructor(code, message) {
+        super(message ?? RAW_EMAIL_ERRORS[code].message);
+        this.name = "RawEmailDecodeError";
+        this.code = code;
+        this.suggestion = RAW_EMAIL_ERRORS[code].suggestion;
+    }
+}

package/dist/webhook/index.d.ts

@@ -1,4 +1,4 @@
 import { A as UnknownEvent, C as ParsedDataFailed, D as RawContentDownloadOnly, E as RawContent, M as WebhookAttachment, N as WebhookEvent, O as RawContentInline, S as ParsedDataComplete, T as ParsedStatus, _ as ForwardResultInline, a as DmarcPolicy, b as KnownWebhookEvent, c as EmailAnalysis, d as EventType, f as ForwardAnalysis, g as ForwardResultAttachmentSkipped, h as ForwardResultAttachmentAnalyzed, i as DkimSignature, j as ValidateEmailAuthResult, k as SpfResult, l as EmailAuth, m as ForwardResult, n as AuthVerdict, o as DmarcResult, p as ForwardOriginalSender, r as DkimResult, s as EmailAddress, t as AuthConfidence, u as EmailReceivedEvent, v as ForwardVerdict, w as ParsedError, x as ParsedData, y as ForwardVerification } from "../types-9vXGZjPd.js";
-import { a as buildReplySubject, c as parseHeaderAddress, i as buildForwardSubject, n as ReceivedEmailAddress, o as formatAddress, r as ReceivedEmailThread, s as normalizeReceivedEmail, t as ReceivedEmail } from "../received-email-DNjpq_Wt.js";
-import { A as VerifyOptions, B as PAYLOAD_ERRORS, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, G as VERIFICATION_ERRORS, H as RAW_EMAIL_ERRORS, I as generateDownloadToken, J as WebhookPayloadErrorCode, K as WebhookErrorCode, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, Q as WebhookVerificationErrorCode, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, U as RawEmailDecodeError, V as PrimitiveWebhookError, W as RawEmailDecodeErrorCode, X as WebhookValidationErrorCode, Y as WebhookValidationError, Z as WebhookVerificationError, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, q as WebhookPayloadError, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "../index-CDlwyxdp.js";
+import { _ as buildForwardSubject, a as RawEmailDecodeErrorCode, b as normalizeReceivedEmail, c as WebhookPayloadError, d as WebhookValidationErrorCode, f as WebhookVerificationError, g as ReceivedEmailThread, h as ReceivedEmailAddress, i as RawEmailDecodeError, l as WebhookPayloadErrorCode, m as ReceivedEmail, n as PrimitiveWebhookError, o as VERIFICATION_ERRORS, p as WebhookVerificationErrorCode, r as RAW_EMAIL_ERRORS, s as WebhookErrorCode, t as PAYLOAD_ERRORS, u as WebhookValidationError, v as buildReplySubject, x as parseHeaderAddress, y as formatAddress } from "../errors-C53fe686.js";
+import { A as VerifyOptions, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, I as generateDownloadToken, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "../index-Dbx9udpX.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, ReceiveRequestOptions, ReceivedEmail, ReceivedEmailAddress, ReceivedEmailThread, 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, buildForwardSubject, buildReplySubject, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, formatAddress, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, normalizeReceivedEmail, parseHeaderAddress, parseWebhookEvent, receive, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/webhook/index.js

@@ -1,3 +1,3 @@
-import { a as parseHeaderAddress, i as normalizeReceivedEmail, n as buildReplySubject, r as formatAddress, t as buildForwardSubject } from "../received-email-D6tKtWwW.js";
-import { A as PRIMITIVE_CONFIRMED_HEADER, B as RAW_EMAIL_ERRORS, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, G as WebhookVerificationError, H as VERIFICATION_ERRORS, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, R as PAYLOAD_ERRORS, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, U as WebhookPayloadError, V as RawEmailDecodeError, W as WebhookValidationError, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict, z as PrimitiveWebhookError } from "../webhook-rUjGV6Zu.js";
+import { a as VERIFICATION_ERRORS, c as WebhookVerificationError, d as formatAddress, f as normalizeReceivedEmail, i as RawEmailDecodeError, l as buildForwardSubject, n as PrimitiveWebhookError, o as WebhookPayloadError, p as parseHeaderAddress, r as RAW_EMAIL_ERRORS, s as WebhookValidationError, t as PAYLOAD_ERRORS, u as buildReplySubject } from "../errors-x91I_yEt.js";
+import { A as PRIMITIVE_CONFIRMED_HEADER, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict } from "../webhook-DJkfUnFZ.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, buildForwardSubject, buildReplySubject, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, formatAddress, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, normalizeReceivedEmail, parseHeaderAddress, parseWebhookEvent, receive, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };