@primitivedotdev/sdk 0.13.0 → 0.15.0

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  The manifest entry's `responseSchema` carries the inlined JSON Schema for the operation's 200/201 `data` envelope contents (`$ref`s resolved). Use it to look up what specific response fields mean. Examples:\n\n      # Which of EmailDetail's sender-shaped fields is canonical?\n      primitive describe emails:get-email | jq '.responseSchema.properties | keys'\n      primitive describe emails:get-email | jq -r '.responseSchema.properties.from_email.description'\n\n      # What does each value of SentEmailStatus mean?\n      primitive describe sending:get-sent-email | jq -r '.responseSchema.properties.status.description'\n\n  `requestSchema` is the same shape for the request body when one exists. For a single field across many operations at once, use `primitive list-operations | jq` instead.",
+      "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": {
@@ -50,7 +75,8 @@
         "<%= config.bin %> send --to alice@example.com --body 'Hi Alice!'",
         "<%= config.bin %> send --to alice@example.com --from support@yourcompany.com --subject 'Quick question' --body 'Are you free Thursday?'",
         "<%= config.bin %> send --to alice@example.com --html '<p>Hello!</p>'",
-        "<%= config.bin %> send --to alice@example.com --body 'Confirmed' --wait"
+        "<%= config.bin %> send --to alice@example.com --body 'Confirmed' --wait",
+        "<%= config.bin %> send --to inbox@your-managed-domain.primitive.email --body 'self-loop smoke test' --wait  # any *.primitive.email address routes back to the sending account; useful for proving outbound + inbound work end-to-end"
       ],
       "flags": {
         "api-key": {
@@ -172,6 +198,57 @@
       "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) or pass `--json` here for the same raw shape without pagination/filters.\n\n  The default text table truncates each row's id to the first 8 characters for readability. Operations that take an id (`emails:get-email`, `emails:delete-email`, etc.) require the full UUID, so pass `--json` or use `emails:list-emails` when you need to feed an id back into another command.\n\n  Output streams: the column header line is written to STDERR so the row data on STDOUT stays grep/awk-friendly. `--json` writes everything (including the envelope) to STDOUT.",
+      "examples": [
+        "<%= config.bin %> emails:latest",
+        "<%= config.bin %> emails:latest --limit 25",
+        "<%= config.bin %> emails:latest --json | jq '.data[0].id'"
+      ],
+      "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"
+        },
+        "json": {
+          "description": "Print the raw response envelope (with full UUIDs and meta) as JSON on STDOUT instead of the text table. Useful for piping into `jq`, capturing ids for follow-up commands, or scripting.",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "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": {},
@@ -744,7 +821,7 @@
     "emails:get-email": {
       "aliases": [],
       "args": {},
-      "description": "GET /emails/{id}",
+      "description": "Returns the full record for an inbound email received at one\nof your verified domains, including the parsed text and HTML\nbodies, threading metadata, SMTP envelope detail, webhook\ndelivery state, and a `replies` array for any outbound sends\nrecorded as replies to this inbound.\n\nFor listing inbound emails (with cursor pagination, status\nand date filters, and free-text search), use\n`/emails`. Outbound (sent) email records are NOT returned\nhere; use `/sent-emails/{id}` for those.\n\nThe response carries four sender-shaped fields whose\nmeanings overlap. `from_email` is the canonical \"who sent\nthis\" field for most use cases (parsed bare address from\nthe `From:` header, with a `sender` fallback). `from_header`\nis the raw header including any display name. `sender` and\n`smtp_mail_from` both carry the SMTP envelope MAIL FROM\n(return-path) and are equal by construction; `sender` is\nthe older field name retained for compatibility. See\n`primitive describe emails:get-email | jq '.responseSchema.properties'`\nfor per-field detail.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -778,7 +855,7 @@
       "pluginName": "@primitivedotdev/sdk",
       "pluginType": "core",
       "strict": true,
-      "summary": "Get email details",
+      "summary": "Get inbound email by id",
       "enableJsonFlag": false
     },
     "emails:list-emails": {
@@ -827,17 +904,11 @@
           "type": "option"
         },
         "status": {
-          "description": "Filter by email status",
+          "description": "Filter inbound rows by lifecycle status. See `EmailStatus`\nfor what each value means. Note that the webhook delivery\nstate is a SEPARATE lifecycle on the same row; filter by\n`webhook_status` semantics is not currently supported on\nthis endpoint.\n",
           "name": "status",
           "required": false,
           "hasDynamicHelp": false,
           "multiple": false,
-          "options": [
-            "pending",
-            "accepted",
-            "completed",
-            "rejected"
-          ],
           "type": "option"
         },
         "search": {
@@ -1402,6 +1473,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 +1910,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.13.0"
+  "version": "0.15.0"
 }

package/package.json

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