@primitivedotdev/sdk 0.13.0 → 0.14.0

package/dist/openapi/operations.generated.js

@@ -769,6 +769,98 @@ export const operationManifest = [
         "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": {},
@@ -1402,6 +1471,134 @@
       "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": {},
@@ -1711,5 +1908,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.13.0"
+  "version": "0.14.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.13.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"