@primitivedotdev/sdk 0.12.0 → 0.14.0

package/dist/openapi/operations.generated.js

@@ -371,7 +371,7 @@ export const operationManifest = [
         "binaryResponse": false,
         "bodyRequired": false,
         "command": "list-emails",
-        "description": "Returns a paginated list of received emails. Supports filtering by\ndomain, status, date range, and free-text search across subject,\nsender, and recipient fields.\n",
+        "description": "Returns a paginated list of INBOUND emails received at your\nverified domains. Outbound messages sent via /send-mail are not\nincluded; this endpoint is the inbox view, not a unified\nsend/receive history.\n\nSupports filtering by domain, status, date range, and free-text\nsearch across subject, sender, and recipient fields.\n",
         "hasJsonBody": false,
         "method": "GET",
         "operationId": "listEmails",
@@ -435,7 +435,7 @@ export const operationManifest = [
         ],
         "requestSchema": null,
         "sdkName": "listEmails",
-        "summary": "List emails",
+        "summary": "List inbound emails",
         "tag": "Emails",
         "tagCommand": "emails"
     },
@@ -752,6 +752,115 @@ export const operationManifest = [
         "tag": "Filters",
         "tagCommand": "filters"
     },
+    {
+        "binaryResponse": false,
+        "bodyRequired": false,
+        "command": "get-send-permissions",
+        "description": "Returns a flat list of rules describing every recipient the\ncaller may send to. Each rule has a `type`, a kind-specific\npayload, and a human-readable `description`. If any rule\nmatches the recipient, /send-mail will accept the send under\nthe recipient-scope check.\n\nThe endpoint is the answer to \"where can I send\" without\nexposing internal entitlement names. Agents that don't\nrecognize a `type` can still read the `description` prose\nand act on it.\n\nRule kinds, ordered broadest-first so an agent can stop\nscanning at the first match:\n\n  1. `any_recipient` (one entry, only when the org can send\n     anywhere): every other rule below it is redundant.\n  2. `managed_zone` (always emitted, one per Primitive-managed\n     zone): sends to any address at *.primitive.email or\n     *.email.works always succeed; no entitlement required.\n  3. `your_domain` (one per active verified outbound domain\n     owned by the org): sends to that domain are approved.\n  4. `address` (one per address that has authenticated\n     inbound mail to the org, capped at `meta.address_cap`):\n     sends to that exact address are approved.\n\nThe list is informational, not an authorization check.\n/send-mail remains the source of truth on whether an\nindividual send will succeed (it also enforces the\nfrom-address and the `send_mail` entitlement, which are\nnot recipient-scope concerns and are not represented here).\n",
+        "hasJsonBody": false,
+        "method": "GET",
+        "operationId": "getSendPermissions",
+        "path": "/send-permissions",
+        "pathParams": [],
+        "queryParams": [],
+        "requestSchema": null,
+        "sdkName": "getSendPermissions",
+        "summary": "List send-permission rules",
+        "tag": "Sending",
+        "tagCommand": "sending"
+    },
+    {
+        "binaryResponse": false,
+        "bodyRequired": false,
+        "command": "get-sent-email",
+        "description": "Returns the full sent-email record by id, including\n`body_text` and `body_html` (omitted from the listing\nendpoint to keep paginated responses small). Use this when\ndiagnosing a specific send, e.g. inspecting the receiver's\nSMTP response on a `bounced` row or pulling the gate\ndenial detail on a `gate_denied` row.\n",
+        "hasJsonBody": false,
+        "method": "GET",
+        "operationId": "getSentEmail",
+        "path": "/sent-emails/{id}",
+        "pathParams": [
+            {
+                "description": "Resource UUID",
+                "enum": null,
+                "name": "id",
+                "required": true,
+                "type": "string"
+            }
+        ],
+        "queryParams": [],
+        "requestSchema": null,
+        "sdkName": "getSentEmail",
+        "summary": "Get a sent email by id",
+        "tag": "Sending",
+        "tagCommand": "sending"
+    },
+    {
+        "binaryResponse": false,
+        "bodyRequired": false,
+        "command": "list-sent-emails",
+        "description": "Returns a paginated list of OUTBOUND emails the caller's\norg has sent via /send-mail (and /emails/{id}/reply, which\nforwards through /send-mail). Includes every recorded\nattempt, including gate-denied attempts that the agent\nnever called and rows still in `queued` state.\n\nFor inbound mail received at your verified domains, see\n/emails. There is no unified send/receive history endpoint;\nthe two surfaces are intentionally separate because the\nunderlying tables, statuses, and lifecycle differ.\n\nEmail bodies (`body_text`, `body_html`) are NOT included on\nlist rows so a 50-row page can't balloon into a multi-MB\nresponse when sends are near the 5MB body cap. Use\n/sent-emails/{id} to fetch a single row with bodies, or\ncross-reference by `client_idempotency_key` if the caller\nalready has the body locally.\n",
+        "hasJsonBody": false,
+        "method": "GET",
+        "operationId": "listSentEmails",
+        "path": "/sent-emails",
+        "pathParams": [],
+        "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 to rows in this status. Useful for polling\nqueued rows that haven't transitioned, auditing\ngate-denied attempts, or listing only successful\ndeliveries.\n",
+                "enum": null,
+                "name": "status",
+                "required": false,
+                "type": "string"
+            },
+            {
+                "description": "Filter to the row matching a specific server-issued\n`request_id`. The /send-mail response surfaces\n`request_id` on every send; this lookup lets the\ncaller find the historical row for a given live call\nwithout remembering its `id`.\n",
+                "enum": null,
+                "name": "request_id",
+                "required": false,
+                "type": "string"
+            },
+            {
+                "description": "Filter to rows with the given `client_idempotency_key`.\nMultiple rows can share a key (a retry that hit the\nidempotent-replay path returns the same row, but a\nretry with a DIFFERENT canonical payload under the\nsame key is rejected by /send-mail before the row is\nwritten, so duplicates are bounded).\n",
+                "enum": null,
+                "name": "idempotency_key",
+                "required": false,
+                "type": "string"
+            },
+            {
+                "description": "Inclusive lower bound on `created_at`.",
+                "enum": null,
+                "name": "date_from",
+                "required": false,
+                "type": "string"
+            },
+            {
+                "description": "Inclusive upper bound on `created_at`.",
+                "enum": null,
+                "name": "date_to",
+                "required": false,
+                "type": "string"
+            }
+        ],
+        "requestSchema": null,
+        "sdkName": "listSentEmails",
+        "summary": "List outbound sent emails",
+        "tag": "Sending",
+        "tagCommand": "sending"
+    },
     {
         "binaryResponse": false,
         "bodyRequired": true,

package/oclif.manifest.json

@@ -30,7 +30,7 @@
     "list-operations": {
       "aliases": [],
       "args": {},
-      "description": "List all generated API operations",
+      "description": "List all generated API operations as JSON. Useful for piping to `jq` to discover available commands, their request/response schemas, and per-field descriptions. For inspecting a single operation in detail, prefer `primitive describe <command>`.",
       "flags": {},
       "hasDynamicHelp": false,
       "hiddenAliases": [],
@@ -39,7 +39,32 @@
       "pluginName": "@primitivedotdev/sdk",
       "pluginType": "core",
       "strict": true,
-      "summary": "List all generated API operations",
+      "summary": "List all generated API operations (JSON)",
+      "enableJsonFlag": false
+    },
+    "describe": {
+      "aliases": [],
+      "args": {
+        "command": {
+          "description": "Command id to describe, in `<topic>:<command>` form (e.g. `emails:get-email`). Run `primitive list-operations | jq -r '.[] | \"\\(.tagCommand):\\(.command)\"'` to enumerate.",
+          "name": "command",
+          "required": true
+        }
+      },
+      "description": "Print the full operation manifest entry for a single API command, including the path, request schema, response schema, and per-field descriptions sourced from the OpenAPI spec.\n\n  Useful for clarifying response field meanings (e.g. on inbound EmailDetail, which of `sender`, `from_email`, `from_header`, and `smtp_mail_from` to read), confirming required body fields, or checking a path's parameter shape before composing a request.",
+      "examples": [
+        "<%= config.bin %> describe emails:get-email",
+        "<%= config.bin %> describe sending:send-email"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "describe",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Describe a single API operation in detail",
       "enableJsonFlag": false
     },
     "send": {
@@ -172,6 +197,50 @@
       "summary": "Print the authenticated account (credentials smoke test)",
       "enableJsonFlag": false
     },
+    "emails:latest": {
+      "aliases": [],
+      "args": {},
+      "description": "Print the N most recent inbound emails as a one-line-per-row text table. Designed for quick triage and visual scanning. For programmatic access, use `primitive emails:list-emails` (full JSON envelope, cursor pagination, filters).\n\n  The displayed id is the first 8 characters of the email's UUID; pass the full UUID (from `emails:list-emails` or `emails:get-email`) to operations that need it.",
+      "examples": [
+        "<%= config.bin %> emails:latest",
+        "<%= config.bin %> emails:latest --limit 25"
+      ],
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base-url": {
+          "description": "API base URL (defaults to PRIMITIVE_API_URL or production)",
+          "env": "PRIMITIVE_API_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "description": "Number of rows to print (1-100, default 10).",
+          "name": "limit",
+          "default": 10,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "emails:latest",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Show the most recent inbound emails as a compact table",
+      "enableJsonFlag": false
+    },
     "account:get-account": {
       "aliases": [],
       "args": {},
@@ -342,7 +411,7 @@
           "type": "boolean"
         },
         "spam-threshold": {
-          "description": "Global spam score threshold (0-15). Emails scoring above this are rejected. S...",
+          "description": "Global spam score threshold (0-15). Emails scoring above this are rejected. Set to null to disable.",
           "name": "spam-threshold",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -784,7 +853,7 @@
     "emails:list-emails": {
       "aliases": [],
       "args": {},
-      "description": "Returns a paginated list of received emails. Supports filtering by\ndomain, status, date range, and free-text search across subject,\nsender, and recipient fields.\n",
+      "description": "Returns a paginated list of INBOUND emails received at your\nverified domains. Outbound messages sent via /send-mail are not\nincluded; this endpoint is the inbox view, not a unified\nsend/receive history.\n\nSupports filtering by domain, status, date range, and free-text\nsearch across subject, sender, and recipient fields.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -872,7 +941,7 @@
       "pluginName": "@primitivedotdev/sdk",
       "pluginType": "core",
       "strict": true,
-      "summary": "List emails",
+      "summary": "List inbound emails",
       "enableJsonFlag": false
     },
     "emails:replay-email-webhooks": {
@@ -1370,6 +1439,166 @@
       "summary": "Update a filter rule",
       "enableJsonFlag": false
     },
+    "sending:get-send-permissions": {
+      "aliases": [],
+      "args": {},
+      "description": "Returns a flat list of rules describing every recipient the\ncaller may send to. Each rule has a `type`, a kind-specific\npayload, and a human-readable `description`. If any rule\nmatches the recipient, /send-mail will accept the send under\nthe recipient-scope check.\n\nThe endpoint is the answer to \"where can I send\" without\nexposing internal entitlement names. Agents that don't\nrecognize a `type` can still read the `description` prose\nand act on it.\n\nRule kinds, ordered broadest-first so an agent can stop\nscanning at the first match:\n\n  1. `any_recipient` (one entry, only when the org can send\n     anywhere): every other rule below it is redundant.\n  2. `managed_zone` (always emitted, one per Primitive-managed\n     zone): sends to any address at *.primitive.email or\n     *.email.works always succeed; no entitlement required.\n  3. `your_domain` (one per active verified outbound domain\n     owned by the org): sends to that domain are approved.\n  4. `address` (one per address that has authenticated\n     inbound mail to the org, capped at `meta.address_cap`):\n     sends to that exact address are approved.\n\nThe list is informational, not an authorization check.\n/send-mail remains the source of truth on whether an\nindividual send will succeed (it also enforces the\nfrom-address and the `send_mail` entitlement, which are\nnot recipient-scope concerns and are not represented here).\n",
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base-url": {
+          "description": "API base URL (defaults to PRIMITIVE_API_URL or production)",
+          "env": "PRIMITIVE_API_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "sending:get-send-permissions",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "List send-permission rules",
+      "enableJsonFlag": false
+    },
+    "sending:get-sent-email": {
+      "aliases": [],
+      "args": {},
+      "description": "Returns the full sent-email record by id, including\n`body_text` and `body_html` (omitted from the listing\nendpoint to keep paginated responses small). Use this when\ndiagnosing a specific send, e.g. inspecting the receiver's\nSMTP response on a `bounced` row or pulling the gate\ndenial detail on a `gate_denied` row.\n",
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base-url": {
+          "description": "API base URL (defaults to PRIMITIVE_API_URL or production)",
+          "env": "PRIMITIVE_API_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "id": {
+          "description": "Resource UUID",
+          "name": "id",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "sending:get-sent-email",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Get a sent email by id",
+      "enableJsonFlag": false
+    },
+    "sending:list-sent-emails": {
+      "aliases": [],
+      "args": {},
+      "description": "Returns a paginated list of OUTBOUND emails the caller's\norg has sent via /send-mail (and /emails/{id}/reply, which\nforwards through /send-mail). Includes every recorded\nattempt, including gate-denied attempts that the agent\nnever called and rows still in `queued` state.\n\nFor inbound mail received at your verified domains, see\n/emails. There is no unified send/receive history endpoint;\nthe two surfaces are intentionally separate because the\nunderlying tables, statuses, and lifecycle differ.\n\nEmail bodies (`body_text`, `body_html`) are NOT included on\nlist rows so a 50-row page can't balloon into a multi-MB\nresponse when sends are near the 5MB body cap. Use\n/sent-emails/{id} to fetch a single row with bodies, or\ncross-reference by `client_idempotency_key` if the caller\nalready has the body locally.\n",
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base-url": {
+          "description": "API base URL (defaults to PRIMITIVE_API_URL or production)",
+          "env": "PRIMITIVE_API_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "cursor": {
+          "description": "Pagination cursor from a previous response's `meta.cursor` field.\nFormat: `{ISO-datetime}|{id}`\n",
+          "name": "cursor",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "description": "Number of results per page",
+          "name": "limit",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "status": {
+          "description": "Filter to rows in this status. Useful for polling\nqueued rows that haven't transitioned, auditing\ngate-denied attempts, or listing only successful\ndeliveries.\n",
+          "name": "status",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "request-id": {
+          "description": "Filter to the row matching a specific server-issued\n`request_id`. The /send-mail response surfaces\n`request_id` on every send; this lookup lets the\ncaller find the historical row for a given live call\nwithout remembering its `id`.\n",
+          "name": "request-id",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "idempotency-key": {
+          "description": "Filter to rows with the given `client_idempotency_key`.\nMultiple rows can share a key (a retry that hit the\nidempotent-replay path returns the same row, but a\nretry with a DIFFERENT canonical payload under the\nsame key is rejected by /send-mail before the row is\nwritten, so duplicates are bounded).\n",
+          "name": "idempotency-key",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "date-from": {
+          "description": "Inclusive lower bound on `created_at`.",
+          "name": "date-from",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "date-to": {
+          "description": "Inclusive upper bound on `created_at`.",
+          "name": "date-to",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "sending:list-sent-emails",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "List outbound sent emails",
+      "enableJsonFlag": false
+    },
     "sending:reply-to-email": {
       "aliases": [],
       "args": {},
@@ -1421,21 +1650,21 @@
           "type": "option"
         },
         "body-text": {
-          "description": "Plain-text reply body. At least one of body_text or body_html is required. Th...",
+          "description": "Plain-text reply 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 (same cap as send-mail).",
           "name": "body-text",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "from": {
-          "description": "Optional override for the reply's From header. Defaults to",
+          "description": "Optional override for the reply's From header. Defaults to the inbound's recipient. Use to add a display name (`\"Acme Support\" <agent@company.com>`) or to reply from a different verified outbound address (e.g. multi-team routing where support@ triages to billing@). The from-domain must be a verified outbound domain for your org, same as send-mail.",
           "name": "from",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "wait": {
-          "description": "When true, wait for the first downstream SMTP delivery outcome before returni...",
+          "description": "When true, wait for the first downstream SMTP delivery outcome before returning, mirroring the send-mail `wait` semantics.",
           "name": "wait",
           "allowNo": false,
           "type": "boolean"
@@ -1487,7 +1716,7 @@
           "type": "option"
         },
         "from": {
-          "description": "RFC 5322 From header. The sender domain must be a verified outbound domain fo...",
+          "description": "RFC 5322 From header. The sender domain must be a verified outbound domain for your organization.",
           "name": "from",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1501,21 +1730,21 @@
           "type": "option"
         },
         "to": {
-          "description": "Recipient address. Recipient eligibility depends on your account's outbound e...",
+          "description": "Recipient address. Recipient eligibility depends on your account's outbound entitlements.",
           "name": "to",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-html": {
-          "description": "HTML message body. At least one of body_text or body_html is required. The co...",
+          "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.",
           "name": "body-html",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-text": {
-          "description": "Plain-text message body. At least one of body_text or body_html is required. ...",
+          "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.",
           "name": "body-text",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1535,7 +1764,7 @@
           "type": "boolean"
         },
         "wait-timeout-ms": {
-          "description": "Maximum time to wait for a delivery outcome when wait is true. Defaults to 30...",
+          "description": "Maximum time to wait for a delivery outcome when wait is true. Defaults to 30000.",
           "name": "wait-timeout-ms",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1679,5 +1908,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.12.0"
+  "version": "0.14.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Official Primitive Node.js SDK — webhook, api, openapi, contract, and parser modules",
   "type": "module",
   "module": "./dist/index.js",
@@ -66,10 +66,10 @@
         "description": "Claim, verify, and manage email domains"
       },
       "emails": {
-        "description": "List, inspect, and manage received emails"
+        "description": "List, inspect, and manage received emails. Use `primitive emails:latest` for a one-line-per-email summary of recent inbound mail."
       },
       "sending": {
-        "description": "Send outbound emails through the Primitive API"
+        "description": "Send outbound emails. For replies to inbound mail, use `sending:reply-to-email --id <inbound-id>` (threading and Re: subject derived server-side); for fresh sends, use `sending:send-email` or the `primitive send` shortcut."
       },
       "endpoints": {
         "description": "Manage webhook endpoints that receive email events"