@primitivedotdev/sdk 0.26.1 → 0.27.1

package/dist/parser/address-parser.js

@@ -1,129 +0,0 @@
-import addressparser from "nodemailer/lib/addressparser/index.js";
-import isEmail from "validator/lib/isEmail.js";
-// Per RFC 5322 §2.1.1, header lines are bounded at 998 octets. We measure
-// in UTF-8 bytes, not JS code units, so SMTPUTF8 (RFC 6531) headers with
-// multi-byte characters cannot bypass the cap by being short on chars but
-// long on bytes. Reject anything beyond as malformed without parsing: a
-// longer From field is either a header-injection probe or a corrupt feed.
-const MAX_HEADER_LENGTH = 998;
-// Options for validator's isEmail. The per-part length limits (64-octet
-// local-part, 255-octet domain), dot-atom rules, hostname-label rules,
-// and TLD requirement are all enforced inside isEmail. We choose:
-//   allow_ip_domain: true     -- accept user@[192.168.1.1] address-literals
-//   require_tld: true         -- reject user@localhost
-//   allow_display_name: false -- we already extracted the address with
-//                                addressparser, so isEmail only sees the
-//                                bare addr-spec
-//   allow_utf8_local_part: true -- accept SMTPUTF8 / EAI local-parts
-const IS_EMAIL_OPTIONS = {
-    allow_ip_domain: true,
-    require_tld: true,
-    allow_display_name: false,
-    allow_utf8_local_part: true,
-};
-/**
- * Strict parser for RFC 5322 From-style headers in security-bearing
- * contexts (allowlist gates, permission grants).
- *
- * Rejects, without falling back to a "best guess":
- *   - empty / whitespace-only input
- *   - inputs longer than RFC 5322's 998-octet line limit
- *   - multi-address From (RFC 5322 allows it but it is vanishingly
- *     rare and ambiguous as an identity)
- *   - group syntax ("Friends: a@b.com, c@d.com;")
- *   - any address that fails validator's isEmail check with our chosen
- *     options. That covers per-part length limits, dot-atom rules,
- *     hostname-label rules, TLD requirement, and other RFC 5321/5322
- *     conformance checks.
- *
- * Returns ONLY the validated address, with no display name. Strict
- * exists for gating decisions, where the address is the security-
- * bearing field. Display names from addressparser are not trustworthy
- * here: weird inputs like `Name <user@x.com> <attacker@y.com>` get
- * parsed as a single entry whose `name` silently includes the second
- * address. Surfacing that as a "parsed name" would invite downstream
- * misuse, so we drop it. If you need the name, call
- * {@link parseFromHeaderLoose} alongside (it returns null on failure
- * anyway, so you can still gate on strict's Result).
- *
- * Returns a typed Result so callers can map the failure reason to
- * stable error codes without inspecting message text.
- */
-export function parseFromHeader(header) {
-    if (header === null || header === undefined) {
-        return { ok: false, reason: "empty" };
-    }
-    const trimmed = header.trim();
-    if (trimmed.length === 0) {
-        return { ok: false, reason: "empty" };
-    }
-    if (Buffer.byteLength(trimmed, "utf8") > MAX_HEADER_LENGTH) {
-        return { ok: false, reason: "too_long" };
-    }
-    // Default (no flatten) so group entries surface as { name, group: [] }
-    // rather than being silently merged into the address list.
-    const parsed = addressparser(trimmed);
-    if (parsed.length > 1) {
-        return { ok: false, reason: "multiple_addresses" };
-    }
-    const entry = parsed[0];
-    // addressparser returns a single entry with empty `address` for raw
-    // garbage rather than an empty array, so an empty result is only
-    // possible for inputs that already failed our trim/empty check above.
-    // The defensive fall-through maps any future regression to
-    // invalid_address rather than crashing on parsed[0].
-    if (entry === undefined) {
-        return { ok: false, reason: "invalid_address" };
-    }
-    if ("group" in entry) {
-        return { ok: false, reason: "group_syntax" };
-    }
-    const address = entry.address;
-    if (address === undefined || !isEmail(address, IS_EMAIL_OPTIONS)) {
-        return { ok: false, reason: "invalid_address" };
-    }
-    return {
-        ok: true,
-        value: { address: address.toLowerCase() },
-    };
-}
-/**
- * Lenient parser for display-only call sites (inbox card "from",
- * log lines, debugging). Returns the first parseable address with its
- * display name, or null.
- *
- * Differences from {@link parseFromHeader}:
- *   - Multi-address From returns the first address instead of rejecting
- *   - Group syntax is flattened into its member addresses
- *   - Returns null instead of a typed reason on failure
- *   - Includes the parsed display name in the result
- *
- * Do not use for permission gates or any decision that grants access.
- * That is what {@link parseFromHeader} is for. Names returned here can
- * include addressparser's recovery output (trailing tokens, garbage
- * before the address); treat as opaque text for display.
- */
-export function parseFromHeaderLoose(header) {
-    if (header === null || header === undefined) {
-        return null;
-    }
-    const trimmed = header.trim();
-    if (trimmed.length === 0 ||
-        Buffer.byteLength(trimmed, "utf8") > MAX_HEADER_LENGTH) {
-        return null;
-    }
-    const parsed = addressparser(trimmed);
-    for (const entry of parsed) {
-        const candidates = "group" in entry && Array.isArray(entry.group) ? entry.group : [entry];
-        for (const candidate of candidates) {
-            const address = candidate.address;
-            if (address !== undefined && isEmail(address, IS_EMAIL_OPTIONS)) {
-                return {
-                    address: address.toLowerCase(),
-                    name: candidate.name && candidate.name.length > 0 ? candidate.name : null,
-                };
-            }
-        }
-    }
-    return null;
-}

package/dist/types.generated.js

@@ -1,7 +0,0 @@
-/**
- * Types for Primitive webhook payloads.
- *
- * AUTO-GENERATED - DO NOT EDIT
- * Run `pnpm generate:types` to regenerate.
- */
-export {};

package/dist/types.js

@@ -1,53 +0,0 @@
-/**
- * Primitive webhook event types derived from the canonical JSON schema.
- *
- * @packageDocumentation
- */
-export const EventType = {
-    EmailReceived: "email.received",
-};
-export const ParsedStatus = {
-    Complete: "complete",
-    Failed: "failed",
-};
-export const ForwardVerdict = {
-    Legit: "legit",
-    Unknown: "unknown",
-};
-export const SpfResult = {
-    Pass: "pass",
-    Fail: "fail",
-    Softfail: "softfail",
-    Neutral: "neutral",
-    None: "none",
-    Temperror: "temperror",
-    Permerror: "permerror",
-};
-export const DmarcResult = {
-    Pass: "pass",
-    Fail: "fail",
-    None: "none",
-    Temperror: "temperror",
-    Permerror: "permerror",
-};
-export const DmarcPolicy = {
-    Reject: "reject",
-    Quarantine: "quarantine",
-    None: "none",
-};
-export const DkimResult = {
-    Pass: "pass",
-    Fail: "fail",
-    Temperror: "temperror",
-    Permerror: "permerror",
-};
-export const AuthConfidence = {
-    High: "high",
-    Medium: "medium",
-    Low: "low",
-};
-export const AuthVerdict = {
-    Legit: "legit",
-    Suspicious: "suspicious",
-    Unknown: "unknown",
-};

package/dist/webhook/errors.js

@@ -1,224 +0,0 @@
-// -----------------------------------------------------------------------------
-// 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/received-email.js

@@ -1,82 +0,0 @@
-import { parseFromHeaderLoose } from "../parser/address-parser.js";
-const REPLY_PREFIX_RE = /^re\s*:/i;
-const FORWARD_PREFIX_RE = /^(fwd?|fw)\s*:/i;
-export function normalizeReceivedEmail(event) {
-    const receivedBy = event.email.smtp.rcpt_to[0];
-    if (!receivedBy) {
-        throw new Error("email.smtp.rcpt_to must contain at least one recipient");
-    }
-    const sender = parseHeaderAddress(event.email.headers.from) ?? {
-        address: event.email.smtp.mail_from.trim().toLowerCase(),
-        name: null,
-    };
-    const replyTarget = firstStructuredAddress(event.email.parsed.reply_to) ?? sender;
-    const subject = event.email.headers.subject ?? null;
-    const references = event.email.parsed.references ?? [];
-    const messageId = event.email.headers.message_id ?? null;
-    return {
-        id: event.email.id,
-        eventId: event.id,
-        receivedAt: event.email.received_at,
-        sender,
-        replyTarget,
-        receivedBy,
-        receivedByAll: [...event.email.smtp.rcpt_to],
-        subject,
-        replySubject: buildReplySubject(subject),
-        forwardSubject: buildForwardSubject(subject),
-        text: event.email.parsed.body_text ?? null,
-        thread: {
-            messageId,
-            inReplyTo: event.email.parsed.in_reply_to ?? [],
-            references,
-        },
-        attachments: event.email.parsed.attachments ?? [],
-        auth: event.email.auth,
-        analysis: event.email.analysis,
-        raw: event,
-    };
-}
-export function buildReplySubject(subject) {
-    const trimmed = subject?.trim() ?? "";
-    if (trimmed.length === 0) {
-        return "Re:";
-    }
-    return REPLY_PREFIX_RE.test(trimmed) ? trimmed : `Re: ${trimmed}`;
-}
-export function buildForwardSubject(subject) {
-    const trimmed = subject?.trim() ?? "";
-    if (trimmed.length === 0) {
-        return "Fwd:";
-    }
-    return FORWARD_PREFIX_RE.test(trimmed) ? trimmed : `Fwd: ${trimmed}`;
-}
-export function formatAddress(address) {
-    return address.name
-        ? `${address.name} <${address.address}>`
-        : address.address;
-}
-function firstStructuredAddress(addresses) {
-    const address = addresses?.[0];
-    if (!address) {
-        return null;
-    }
-    return {
-        address: address.address.trim().toLowerCase(),
-        name: address.name ?? null,
-    };
-}
-// Lenient about quirky headers (unquoted commas in display names, missing
-// closing angle brackets) but strict about the resulting address: it must
-// validate as an email, otherwise the normalizer falls back to the SMTP
-// envelope sender. Exported so cross-SDK fixtures can exercise it directly.
-export function parseHeaderAddress(value) {
-    const parsed = parseFromHeaderLoose(value);
-    if (!parsed) {
-        return null;
-    }
-    return {
-        address: parsed.address,
-        name: parsed.name?.trim() || null,
-    };
-}