@primitivedotdev/sdk 0.7.0 → 0.9.0

package/dist/openapi/operations.generated.js

@@ -16,6 +16,7 @@ export const operationManifest = [
         "path": "/account",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "getAccount",
         "summary": "Get account info",
         "tag": "Account",
@@ -32,6 +33,7 @@ export const operationManifest = [
         "path": "/account/storage",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "getStorageStats",
         "summary": "Get storage usage",
         "tag": "Account",
@@ -48,6 +50,7 @@ export const operationManifest = [
         "path": "/account/webhook-secret",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "getWebhookSecret",
         "summary": "Get webhook signing secret",
         "tag": "Account",
@@ -64,6 +67,7 @@ export const operationManifest = [
         "path": "/account/webhook-secret/rotate",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "rotateWebhookSecret",
         "summary": "Rotate webhook signing secret",
         "tag": "Account",
@@ -80,6 +84,26 @@ export const operationManifest = [
         "path": "/account",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "spam_threshold": {
+                    "type": [
+                        "number",
+                        "null"
+                    ],
+                    "minimum": 0,
+                    "maximum": 15,
+                    "description": "Global spam score threshold (0-15). Emails scoring above this are rejected. Set to null to disable."
+                },
+                "discard_content_on_webhook_confirmed": {
+                    "type": "boolean",
+                    "description": "Whether to discard email content after the webhook endpoint confirms receipt."
+                }
+            },
+            "minProperties": 1
+        },
         "sdkName": "updateAccount",
         "summary": "Update account settings",
         "tag": "Account",
@@ -96,6 +120,21 @@ export const operationManifest = [
         "path": "/domains",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "domain": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 253,
+                    "description": "The domain name to claim (e.g. \"example.com\")"
+                }
+            },
+            "required": [
+                "domain"
+            ]
+        },
         "sdkName": "addDomain",
         "summary": "Claim a new domain",
         "tag": "Domains",
@@ -120,6 +159,7 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "deleteDomain",
         "summary": "Delete a domain",
         "tag": "Domains",
@@ -136,6 +176,7 @@ export const operationManifest = [
         "path": "/domains",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "listDomains",
         "summary": "List all domains",
         "tag": "Domains",
@@ -160,6 +201,26 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "description": "Whether the domain accepts incoming emails"
+                },
+                "spam_threshold": {
+                    "type": [
+                        "number",
+                        "null"
+                    ],
+                    "minimum": 0,
+                    "maximum": 15,
+                    "description": "Per-domain spam threshold override (Pro plan required)"
+                }
+            },
+            "minProperties": 1
+        },
         "sdkName": "updateDomain",
         "summary": "Update domain settings",
         "tag": "Domains",
@@ -184,6 +245,7 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "verifyDomain",
         "summary": "Verify domain ownership",
         "tag": "Domains",
@@ -208,6 +270,7 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "deleteEmail",
         "summary": "Delete an email",
         "tag": "Emails",
@@ -240,6 +303,7 @@ export const operationManifest = [
                 "type": "string"
             }
         ],
+        "requestSchema": null,
         "sdkName": "downloadAttachments",
         "summary": "Download email attachments",
         "tag": "Emails",
@@ -272,6 +336,7 @@ export const operationManifest = [
                 "type": "string"
             }
         ],
+        "requestSchema": null,
         "sdkName": "downloadRawEmail",
         "summary": "Download raw email",
         "tag": "Emails",
@@ -296,6 +361,7 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "getEmail",
         "summary": "Get email details",
         "tag": "Emails",
@@ -367,6 +433,7 @@ export const operationManifest = [
                 "type": "string"
             }
         ],
+        "requestSchema": null,
         "sdkName": "listEmails",
         "summary": "List emails",
         "tag": "Emails",
@@ -391,6 +458,7 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "replayEmailWebhooks",
         "summary": "Replay email webhooks",
         "tag": "Emails",
@@ -407,6 +475,37 @@ export const operationManifest = [
         "path": "/endpoints",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The webhook URL to deliver events to"
+                },
+                "enabled": {
+                    "type": "boolean",
+                    "default": true,
+                    "description": "Whether the endpoint is active"
+                },
+                "domain_id": {
+                    "type": [
+                        "string",
+                        "null"
+                    ],
+                    "format": "uuid",
+                    "description": "Restrict to emails from a specific domain"
+                },
+                "rules": {
+                    "type": "object",
+                    "description": "Endpoint-specific filtering rules"
+                }
+            },
+            "required": [
+                "url"
+            ]
+        },
         "sdkName": "createEndpoint",
         "summary": "Create a webhook endpoint",
         "tag": "Endpoints",
@@ -431,6 +530,7 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "deleteEndpoint",
         "summary": "Delete a webhook endpoint",
         "tag": "Endpoints",
@@ -447,6 +547,7 @@ export const operationManifest = [
         "path": "/endpoints",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "listEndpoints",
         "summary": "List webhook endpoints",
         "tag": "Endpoints",
@@ -471,6 +572,7 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "testEndpoint",
         "summary": "Send a test webhook",
         "tag": "Endpoints",
@@ -495,6 +597,31 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "New webhook URL (triggers endpoint rotation)"
+                },
+                "enabled": {
+                    "type": "boolean"
+                },
+                "domain_id": {
+                    "type": [
+                        "string",
+                        "null"
+                    ],
+                    "format": "uuid"
+                },
+                "rules": {
+                    "type": "object"
+                }
+            },
+            "minProperties": 1
+        },
         "sdkName": "updateEndpoint",
         "summary": "Update a webhook endpoint",
         "tag": "Endpoints",
@@ -511,6 +638,37 @@ export const operationManifest = [
         "path": "/filters",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "whitelist",
+                        "blocklist"
+                    ]
+                },
+                "pattern": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 500,
+                    "description": "Email address or pattern to filter"
+                },
+                "domain_id": {
+                    "type": [
+                        "string",
+                        "null"
+                    ],
+                    "format": "uuid",
+                    "description": "Restrict filter to a specific domain (Pro plan required)"
+                }
+            },
+            "required": [
+                "type",
+                "pattern"
+            ]
+        },
         "sdkName": "createFilter",
         "summary": "Create a filter rule",
         "tag": "Filters",
@@ -535,6 +693,7 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "deleteFilter",
         "summary": "Delete a filter rule",
         "tag": "Filters",
@@ -551,6 +710,7 @@ export const operationManifest = [
         "path": "/filters",
         "pathParams": [],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "listFilters",
         "summary": "List filter rules",
         "tag": "Filters",
@@ -575,11 +735,104 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "enabled": {
+                    "type": "boolean"
+                }
+            },
+            "required": [
+                "enabled"
+            ]
+        },
         "sdkName": "updateFilter",
         "summary": "Update a filter rule",
         "tag": "Filters",
         "tagCommand": "filters"
     },
+    {
+        "binaryResponse": false,
+        "bodyRequired": true,
+        "command": "send-email",
+        "description": "Sends an outbound email through Primitive's outbound relay. By default\nthe request returns once the relay accepts the message for delivery.\nSet `wait: true` to wait for the first downstream SMTP delivery outcome.\n",
+        "hasJsonBody": true,
+        "method": "POST",
+        "operationId": "sendEmail",
+        "path": "/send-mail",
+        "pathParams": [],
+        "queryParams": [],
+        "requestSchema": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "from": {
+                    "type": "string",
+                    "minLength": 3,
+                    "maxLength": 998,
+                    "description": "RFC 5322 From header. The sender domain must be a verified outbound domain for your organization."
+                },
+                "to": {
+                    "type": "string",
+                    "minLength": 3,
+                    "maxLength": 320,
+                    "description": "Recipient address. Recipient eligibility depends on your account's outbound entitlements."
+                },
+                "subject": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 998,
+                    "description": "Subject line for the outbound message"
+                },
+                "body_text": {
+                    "type": "string",
+                    "description": "Plain-text message body. At least one of body_text or body_html is required. The combined UTF-8 byte length of body_text and body_html must be at most 262144 bytes."
+                },
+                "body_html": {
+                    "type": "string",
+                    "description": "HTML message body. At least one of body_text or body_html is required. The combined UTF-8 byte length of body_text and body_html must be at most 262144 bytes."
+                },
+                "in_reply_to": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 998,
+                    "pattern": "^[^\\x00-\\x1F\\x7F]+$",
+                    "description": "Message-ID of the direct parent email when sending a threaded reply."
+                },
+                "references": {
+                    "type": "array",
+                    "maxItems": 100,
+                    "description": "Full ordered message-id chain for the thread.",
+                    "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 998,
+                        "pattern": "^[^\\x00-\\x1F\\x7F]+$"
+                    }
+                },
+                "wait": {
+                    "type": "boolean",
+                    "description": "When true, wait for the first downstream SMTP delivery outcome before returning."
+                },
+                "wait_timeout_ms": {
+                    "type": "integer",
+                    "minimum": 1000,
+                    "maximum": 30000,
+                    "description": "Maximum time to wait for a delivery outcome when wait is true. Defaults to 30000."
+                }
+            },
+            "required": [
+                "from",
+                "to",
+                "subject"
+            ]
+        },
+        "sdkName": "sendEmail",
+        "summary": "Send outbound email",
+        "tag": "Sending",
+        "tagCommand": "sending"
+    },
     {
         "binaryResponse": false,
         "bodyRequired": false,
@@ -639,6 +892,7 @@ export const operationManifest = [
                 "type": "string"
             }
         ],
+        "requestSchema": null,
         "sdkName": "listDeliveries",
         "summary": "List webhook deliveries",
         "tag": "Webhook Deliveries",
@@ -663,6 +917,7 @@ export const operationManifest = [
             }
         ],
         "queryParams": [],
+        "requestSchema": null,
         "sdkName": "replayDelivery",
         "summary": "Replay a webhook delivery",
         "tag": "Webhook Deliveries",

package/dist/parser/address-parser.js

@@ -0,0 +1,129 @@
+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/parser/index.d.ts

@@ -1,17 +1,6 @@
-import { EmailAddress, ParsedDataComplete, WebhookAttachment } from "../types-CKFmgitP.js";
+import { M as WebhookAttachment, S as ParsedDataComplete, s as EmailAddress } from "../types-9vXGZjPd.js";
 
 //#region src/parser/address-parser.d.ts
-/**
-* A validated RFC 5322 address. Returned by the strict parser, which
-* deliberately does not expose a display name.
-*
-* `address` is normalized to lowercase. Both the local-part and the
-* domain are lowercased: RFC 5321 §2.4 permits case-sensitive local-
-* parts, but every consumer mailbox in practice treats them as
-* case-insensitive, and a case-sensitive grant key would split
-* `Bob@x.com` from `bob@x.com` into separate rows and defeat the
-* primary-key index on lookup.
-*/
 /**
  * A validated RFC 5322 address. Returned by the strict parser, which
  * deliberately does not expose a display name.
@@ -99,7 +88,8 @@ declare function parseFromHeader(header: string | null | undefined): ParseFromHe
  * include addressparser's recovery output (trailing tokens, garbage
  * before the address); treat as opaque text for display.
  */
-declare function parseFromHeaderLoose(header: string | null | undefined): ParsedAddress | null; //#endregion
+declare function parseFromHeaderLoose(header: string | null | undefined): ParsedAddress | null;
+//#endregion
 //#region src/parser/attachment-parser.d.ts
 interface ParsedAttachment {
   id: string;
@@ -162,7 +152,6 @@ declare function sha256Hex(buffer: Buffer): string;
  * Prevents path traversal, removes control characters, enforces length limits.
  */
 declare function sanitizeFilename(filename: string | null, partIndex: number): string;
-
 //#endregion
 //#region src/parser/attachment-bundler.d.ts
 /**
@@ -216,7 +205,6 @@ declare function extractAttachmentMetadata(attachments: ParsedAttachment[]): Att
  * @returns Storage key in format: attachments/{email_id}_{hash8}.tar.gz
  */
 declare function getAttachmentsStorageKey(emailId: string, sha256: string): string;
-
 //#endregion
 //#region src/parser/email-parser.d.ts
 interface ParsedEmail {
@@ -234,7 +222,6 @@ interface ParsedEmail {
  * Uses mailparser library for robust email parsing
  */
 declare function parseEmail(emlRaw: string): Promise<ParsedEmail>;
-
 //#endregion
 //#region src/parser/mapping.d.ts
 /**
@@ -283,10 +270,8 @@ declare function toCanonicalHeaders(parsed: ParsedEmailWithAttachments): {
   to: string;
   date: string | null;
 };
-
 //#endregion
 //#region src/parser/sanitize-html.d.ts
 declare function sanitizeHtml(html: string): string;
-
 //#endregion
-export { AttachmentMetadata, BundleResult, ParseFromHeaderFailureReason, ParseFromHeaderResult, ParsedAddress, ParsedAttachment, ParsedEmail, ParsedEmailWithAttachments, ValidatedAddress, attachmentMetadataToWebhookAttachments, bundleAttachments, extractAttachmentMetadata, getAttachmentsStorageKey, normalizeContentType, parseEmail, parseEmailWithAttachments, parseFromHeader, parseFromHeaderLoose, sanitizeFilename, sanitizeHtml, sha256Hex, toCanonicalHeaders, toParsedDataComplete, toWebhookAttachments };
+export { type AttachmentMetadata, type BundleResult, type ParseFromHeaderFailureReason, type ParseFromHeaderResult, type ParsedAddress, type ParsedAttachment, type ParsedEmail, type ParsedEmailWithAttachments, type ValidatedAddress, attachmentMetadataToWebhookAttachments, bundleAttachments, extractAttachmentMetadata, getAttachmentsStorageKey, normalizeContentType, parseEmail, parseEmailWithAttachments, parseFromHeader, parseFromHeaderLoose, sanitizeFilename, sanitizeHtml, sha256Hex, toCanonicalHeaders, toParsedDataComplete, toWebhookAttachments };