@primitivedotdev/sdk 0.7.0 → 0.9.0

package/dist/chunk-pbuEa-1d.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/contract/index.d.ts

@@ -1,9 +1,7 @@
-import { EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, ParsedDataComplete, ParsedDataFailed, ParsedError, RawContentDownloadOnly, RawContentInline, WebhookAttachment } from "../types-CKFmgitP.js";
-import { SignResult, StandardWebhooksSignResult, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload } from "../index-DLmAI4UQ.js";
+import { C as ParsedDataFailed, D as RawContentDownloadOnly, M as WebhookAttachment, O as RawContentInline, S as ParsedDataComplete, c as EmailAnalysis, l as EmailAuth, s as EmailAddress, u as EmailReceivedEvent, w as ParsedError } from "../types-9vXGZjPd.js";
+import { C as signStandardWebhooksPayload, h as WEBHOOK_VERSION, j as signWebhookPayload, k as SignResult, x as StandardWebhooksSignResult } from "../index-CbEivn3S.js";
 
 //#region src/contract/contract.d.ts
-/** Maximum raw email size for inline inclusion (256 KB). */
-
 /** Maximum raw email size for inline inclusion (256 KB). */
 declare const RAW_EMAIL_INLINE_THRESHOLD = 262144;
 /** Parsed content input when parsing succeeded. */
@@ -142,8 +140,7 @@ declare function generateEventId(endpoint_id: string, email_id: string): string;
  * ```
  */
 declare function buildEmailReceivedEvent(input: EmailReceivedEventInput, options?: {
-  /** Override the attempted-at timestamp, typically for tests. */
-  attempted_at?: string;
+  /** Override the attempted-at timestamp, typically for tests. */attempted_at?: string;
 }): EmailReceivedEvent;
 /**
  * Input for building an `EmailReceivedEvent` directly from parser output.
@@ -221,5 +218,6 @@ interface BuildEventFromParsedDataOptions {
  * @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 };
+declare function buildEventFromParsedData(params: BuildEventFromParsedDataOptions): EmailReceivedEvent;
+//#endregion
+export { BuildEventFromParsedDataOptions, type EmailAddress, type EmailAnalysis, type EmailAuth, type EmailReceivedEvent, EmailReceivedEventInput, type ParsedDataComplete, type ParsedDataFailed, type ParsedError, ParsedInput, ParsedInputComplete, ParsedInputFailed, RAW_EMAIL_INLINE_THRESHOLD, type RawContentDownloadOnly, type RawContentInline, type SignResult, type StandardWebhooksSignResult, WEBHOOK_VERSION, type WebhookAttachment, buildEmailReceivedEvent, buildEventFromParsedData, generateEventId, signStandardWebhooksPayload, signWebhookPayload };

package/dist/contract/index.js

@@ -1,7 +1,25 @@
-import { WEBHOOK_VERSION, signStandardWebhooksPayload, signWebhookPayload, validateEmailReceivedEvent } from "../webhook-COe5N_Uj.js";
+import { E as signStandardWebhooksPayload, L as validateEmailReceivedEvent, M as signWebhookPayload, d as WEBHOOK_VERSION } from "../webhook-zkN4wUTs.js";
 import { createHash } from "node:crypto";
-
 //#region src/contract/contract.ts
+/**
+* Primitive Contract
+*
+* This module exposes the exact functions used by Primitive servers to construct
+* webhook payloads. It serves two purposes:
+*
+* 1. **Build-time type safety**: Primitive producer code can import these types
+*    and functions so schema changes surface as TypeScript errors instead of
+*    runtime contract drift.
+*
+* 2. **Debugging transparency**: If you receive a malformed payload, you can
+*    compare it against these exact types and builder functions to identify
+*    which side broke the contract.
+*
+* This package is also useful for building test fixtures that match real
+* payloads exactly.
+*
+* @module @primitivedotdev/sdk/contract
+*/
 /** Maximum raw email size for inline inclusion (256 KB). */
 const RAW_EMAIL_INLINE_THRESHOLD = 262144;
 /**
@@ -40,8 +58,7 @@ function validateTimestamp(timestamp, fieldName) {
 */
 function generateEventId(endpoint_id, email_id) {
 	const hashInput = `email.received:${WEBHOOK_VERSION}:${endpoint_id}:${email_id}`;
-	const hash = createHash("sha256").update(hashInput).digest("hex");
-	return `evt_${hash}`;
+	return `evt_${createHash("sha256").update(hashInput).digest("hex")}`;
 }
 /**
 * Build an `EmailReceivedEvent` from producer-side input.
@@ -92,13 +109,12 @@ function generateEventId(endpoint_id, email_id) {
 */
 function buildEmailReceivedEvent(input, options) {
 	const event_id = generateEventId(input.endpoint_id, input.email_id);
-	const attempted_at = options?.attempted_at ? validateTimestamp(options.attempted_at, "attempted_at") : new Date().toISOString();
+	const attempted_at = options?.attempted_at ? validateTimestamp(options.attempted_at, "attempted_at") : (/* @__PURE__ */ new Date()).toISOString();
 	const raw_size_bytes = input.raw_bytes.length;
 	if (input.raw_size_bytes !== raw_size_bytes) throw new Error(`[@primitivedotdev/sdk/contract] Invalid raw_size_bytes: ${input.raw_size_bytes}. Expected ${raw_size_bytes} based on raw_bytes length`);
 	const raw_sha256 = createHash("sha256").update(input.raw_bytes).digest("hex");
 	if (input.raw_sha256 !== raw_sha256) throw new Error(`[@primitivedotdev/sdk/contract] Invalid raw_sha256: "${input.raw_sha256}". Expected ${raw_sha256} based on raw_bytes`);
-	const shouldInline = raw_size_bytes <= RAW_EMAIL_INLINE_THRESHOLD;
-	const rawContent = shouldInline ? {
+	const rawContent = raw_size_bytes <= 262144 ? {
 		included: true,
 		encoding: "base64",
 		max_inline_bytes: RAW_EMAIL_INLINE_THRESHOLD,
@@ -156,7 +172,7 @@ function buildEmailReceivedEvent(input, options) {
 		attachments: [],
 		attachments_download_url: null
 	};
-	const event = {
+	return validateEmailReceivedEvent({
 		id: event_id,
 		event: "email.received",
 		version: WEBHOOK_VERSION,
@@ -191,8 +207,7 @@ function buildEmailReceivedEvent(input, options) {
 			analysis: input.analysis,
 			auth: input.auth
 		}
-	};
-	return validateEmailReceivedEvent(event);
+	});
 }
 /**
 * Build an `EmailReceivedEvent` from parsed email data plus delivery metadata.
@@ -239,7 +254,7 @@ function buildEventFromParsedData(params) {
 		references: parsed.references,
 		attachments: parsed.attachments
 	};
-	const input = {
+	return buildEmailReceivedEvent({
 		email_id: params.emailId,
 		endpoint_id: params.endpointId,
 		message_id: params.messageId,
@@ -261,9 +276,7 @@ function buildEventFromParsedData(params) {
 		parsed: parsedInput,
 		auth: params.auth,
 		analysis: params.analysis
-	};
-	return buildEmailReceivedEvent(input, params.buildOptions);
+	}, params.buildOptions);
 }
-
 //#endregion
-export { RAW_EMAIL_INLINE_THRESHOLD, WEBHOOK_VERSION, buildEmailReceivedEvent, buildEventFromParsedData, generateEventId, signStandardWebhooksPayload, signWebhookPayload };
+export { RAW_EMAIL_INLINE_THRESHOLD, WEBHOOK_VERSION, buildEmailReceivedEvent, buildEventFromParsedData, generateEventId, signStandardWebhooksPayload, signWebhookPayload };

package/dist/{index-DLmAI4UQ.d.ts → index-CbEivn3S.d.ts}

@@ -1,11 +1,8 @@
-import { EmailAuth, EmailReceivedEvent, ValidateEmailAuthResult, WebhookEvent } from "./types-CKFmgitP.js";
+import { N as WebhookEvent, j as ValidateEmailAuthResult, l as EmailAuth, u as EmailReceivedEvent } from "./types-9vXGZjPd.js";
+import { t as ReceivedEmail } from "./received-email-DNjpq_Wt.js";
 import { ErrorObject } from "ajv";
 
 //#region src/webhook/errors.d.ts
-/**
-* Verification error definitions.
-* Use these for documentation, dashboards, and i18n.
-*/
 /**
  * Verification error definitions.
  * Use these for documentation, dashboards, and i18n.
@@ -210,7 +207,8 @@ declare class RawEmailDecodeError extends PrimitiveWebhookError {
   readonly code: RawEmailDecodeErrorCode;
   readonly suggestion: string;
   constructor(code: RawEmailDecodeErrorCode, message?: string);
-} //#endregion
+}
+//#endregion
 //#region src/validation.d.ts
 interface ValidationSuccess<T> {
   success: true;
@@ -223,7 +221,6 @@ interface ValidationFailure {
 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
 /**
@@ -312,7 +309,6 @@ type VerifyDownloadTokenResult = {
  * @returns Whether the token is valid, plus a reason on failure.
  */
 declare function verifyDownloadToken(params: VerifyDownloadTokenOptions): VerifyDownloadTokenResult;
-
 //#endregion
 //#region src/webhook/signing.d.ts
 /**
@@ -405,7 +401,6 @@ declare function signWebhookPayload(rawBody: string | Buffer, secret: string | B
  * ```
  */
 declare function verifyWebhookSignature(opts: VerifyOptions): true;
-
 //#endregion
 //#region src/webhook/standard-webhooks.d.ts
 /**
@@ -457,15 +452,6 @@ interface StandardWebhooksVerifyOptions {
   /** Override current time for testing (unix seconds) */
   nowSeconds?: number;
 }
-/**
- * Prepare a Standard Webhooks secret for HMAC computation.
- *
- * Strips the "whsec_" prefix if present, then base64-decodes the remainder
- * to produce the raw HMAC key bytes.
- *
- * @internal
- */
-
 /**
  * Sign a webhook payload using the Standard Webhooks format.
  *
@@ -481,7 +467,6 @@ declare function signStandardWebhooksPayload(rawBody: string | Buffer, secret: s
  * Throws `WebhookVerificationError` on failure with a specific error code.
  */
 declare function verifyStandardWebhooksSignature(opts: StandardWebhooksVerifyOptions): true;
-
 //#endregion
 //#region src/schema.generated.d.ts
 /**
@@ -1273,7 +1258,8 @@ declare const emailReceivedEventJsonSchema: {
       readonly description: "DKIM signature verification result for a single signature.";
     };
   };
-}; //#endregion
+};
+//#endregion
 //#region src/webhook/auth.d.ts
 /**
  * Validate email authentication and compute a verdict.
@@ -1335,7 +1321,6 @@ declare const emailReceivedEventJsonSchema: {
  * ```
  */
 declare function validateEmailAuth(auth: EmailAuth): ValidateEmailAuthResult;
-
 //#endregion
 //#region src/webhook/version.d.ts
 /**
@@ -1351,15 +1336,8 @@ declare function validateEmailAuth(auth: EmailAuth): ValidateEmailAuthResult;
  * need to handle version-specific behavior.
  */
 declare const WEBHOOK_VERSION = "2025-12-14";
-
 //#endregion
 //#region src/webhook/index.d.ts
-/**
- * Valid webhook version format (YYYY-MM-DD date string).
- * The SDK accepts any valid date-formatted version, not just the current one,
- * for forward and backward compatibility.
- */
-
 /**
  * Parse a webhook payload, returning typed events for known types
  * and UnknownEvent for future event types.
@@ -1484,6 +1462,12 @@ interface HandleWebhookOptions {
  * ```
  */
 declare function handleWebhook(options: HandleWebhookOptions): EmailReceivedEvent;
+interface ReceiveRequestOptions {
+  secret: string;
+  toleranceSeconds?: number;
+}
+declare function receive(options: HandleWebhookOptions): ReceivedEmail;
+declare function receive(request: Request, options: ReceiveRequestOptions): Promise<ReceivedEmail>;
 /**
  * Returns headers for the optional "content discard" feature.
  *
@@ -1639,6 +1623,5 @@ declare function decodeRawEmail(event: EmailReceivedEvent, options?: DecodeRawEm
  * ```
  */
 declare function verifyRawEmailDownload(downloaded: Buffer | ArrayBuffer | Uint8Array, event: EmailReceivedEvent): Buffer;
-
 //#endregion
-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 };
+export { VerifyOptions as A, PAYLOAD_ERRORS as B, signStandardWebhooksPayload as C, PRIMITIVE_CONFIRMED_HEADER as D, LEGACY_SIGNATURE_HEADER as E, VerifyDownloadTokenResult as F, VERIFICATION_ERRORS as G, RAW_EMAIL_ERRORS as H, generateDownloadToken as I, WebhookPayloadErrorCode as J, WebhookErrorCode as K, verifyDownloadToken as L, verifyWebhookSignature as M, GenerateDownloadTokenOptions as N, PRIMITIVE_SIGNATURE_HEADER as O, VerifyDownloadTokenOptions as P, WebhookVerificationErrorCode as Q, safeValidateEmailReceivedEvent as R, StandardWebhooksVerifyOptions as S, LEGACY_CONFIRMED_HEADER as T, RawEmailDecodeError as U, PrimitiveWebhookError as V, RawEmailDecodeErrorCode as W, WebhookValidationErrorCode as X, WebhookValidationError as Y, WebhookVerificationError as Z, emailReceivedEventJsonSchema as _, confirmedHeaders as a, STANDARD_WEBHOOK_TIMESTAMP_HEADER as b, handleWebhook as c, isRawIncluded as d, parseWebhookEvent as f, validateEmailAuth as g, WEBHOOK_VERSION as h, WebhookHeaders as i, signWebhookPayload as j, SignResult as k, isDownloadExpired as l, verifyRawEmailDownload as m, HandleWebhookOptions as n, decodeRawEmail as o, receive as p, WebhookPayloadError as q, ReceiveRequestOptions as r, getDownloadTimeRemaining as s, DecodeRawEmailOptions as t, isEmailReceivedEvent as u, STANDARD_WEBHOOK_ID_HEADER as v, verifyStandardWebhooksSignature as w, StandardWebhooksSignResult as x, STANDARD_WEBHOOK_SIGNATURE_HEADER as y, validateEmailReceivedEvent as z };