@primitivedotdev/sdk 0.3.0 → 0.4.0

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

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

package/dist/api/index.d.ts

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

package/dist/oclif/api-command.js

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

package/dist/openapi/index.d.ts

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

package/dist/openapi/openapi.generated.js

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

package/dist/openapi/operations.generated.js

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

package/oclif.manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Official Primitive Node.js SDK — webhook, api, openapi, contract, and parser modules",
   "type": "module",
   "module": "./dist/index.js",