@primitivedotdev/sdk 0.14.0 → 0.16.0

package/dist/oclif/commands/emails-latest.js

@@ -19,7 +19,15 @@ const MAX_LIMIT = 100;
 // values wrap to "..." rather than blowing out terminal layout.
 const SUBJECT_DISPLAY_WIDTH = 50;
 const ADDRESS_DISPLAY_WIDTH = 32;
-const ID_DISPLAY_WIDTH = 8;
+// Two ID widths: the short prefix is for human eyes (interactive
+// TTY), the full UUID is for piped output (a script reading the row
+// as a feed). The short prefix is useless when piped because every
+// other operation requires the full UUID, so the AGX walkthrough
+// kept producing a re-run with `--json` just to recover the id.
+// Auto-switching by `process.stdout.isTTY` makes the common piped
+// case a one-call workflow.
+const ID_DISPLAY_WIDTH_SHORT = 8;
+const ID_DISPLAY_WIDTH_FULL = 36;
 const RECEIVED_DISPLAY_WIDTH = 19;
 // Truncate to width with right-padding; values longer than width are
 // cut to width-3 with a "..." suffix so the output is exactly `width`
@@ -48,8 +56,22 @@ export function formatReceivedAt(value) {
     const pad = (n) => String(n).padStart(2, "0");
     return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
 }
-export function formatRow(email) {
-    const id = truncate(email.id.slice(0, ID_DISPLAY_WIDTH), ID_DISPLAY_WIDTH);
+// Decide whether to print the full UUID or the short 8-char prefix
+// based on whether stdout is a TTY. Piped/redirected stdout (the
+// caller is consuming the rows programmatically) gets full UUIDs;
+// interactive terminals get the compact prefix. Pulled out as a
+// helper so tests can drive the rendering branch without touching
+// process.stdout.
+export function pickIdWidth(isTty) {
+    return isTty ? ID_DISPLAY_WIDTH_SHORT : ID_DISPLAY_WIDTH_FULL;
+}
+export function formatRow(email, idWidth) {
+    // idWidth is one of ID_DISPLAY_WIDTH_SHORT or ID_DISPLAY_WIDTH_FULL.
+    // For SHORT, slice the UUID to the prefix length and pad. For FULL,
+    // pad to the full UUID width (UUIDs are already 36 chars, so this
+    // is effectively just an alignment guarantee for any malformed
+    // shorter id).
+    const id = truncate(email.id.slice(0, idWidth), idWidth);
     const received = formatReceivedAt(email.received_at);
     const from = truncate(email.sender ?? "", ADDRESS_DISPLAY_WIDTH);
     const to = truncate(email.recipient ?? "", ADDRESS_DISPLAY_WIDTH);
@@ -58,13 +80,17 @@ export function formatRow(email) {
     return `${id}  ${received}  ${from}  ${to}  ${subjectCol}`;
 }
 class EmailsLatestCommand extends Command {
-    static 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).
+    static 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.
+
+  ID display is TTY-aware. When STDOUT is a terminal, the table truncates each row's id to the first ${ID_DISPLAY_WIDTH_SHORT} characters for readability. When STDOUT is piped or redirected (the row stream is being consumed by another command), the full UUID is printed so the id can be fed straight back into \`emails:get-email\`, \`emails:delete-email\`, etc. without a separate \`--json\` round-trip.
 
-  The displayed id is the first ${ID_DISPLAY_WIDTH} characters of the email's UUID; pass the full UUID (from \`emails:list-emails\` or \`emails:get-email\`) to operations that need it.`;
+  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 and is equivalent to running \`emails:list-emails --limit N\` for the same N.`;
     static summary = "Show the most recent inbound emails as a compact table";
     static examples = [
         "<%= config.bin %> emails:latest",
         "<%= config.bin %> emails:latest --limit 25",
+        "<%= config.bin %> emails:latest | head -1 | awk '{print $1}'  # full UUID since piped",
+        "<%= config.bin %> emails:latest --json | jq '.data[0].id'",
     ];
     static flags = {
         "api-key": Flags.string({
@@ -84,6 +110,9 @@ class EmailsLatestCommand extends Command {
             min: 1,
             max: MAX_LIMIT,
         }),
+        json: Flags.boolean({
+            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.",
+        }),
     };
     async run() {
         const { flags } = await this.parse(EmailsLatestCommand);
@@ -102,16 +131,24 @@ class EmailsLatestCommand extends Command {
             return;
         }
         const envelope = result.data;
+        if (flags.json) {
+            // Raw envelope on stdout. Mirrors the shape `emails:list-emails`
+            // emits so callers can swap one for the other when they want
+            // table vs json without remembering different command names.
+            this.log(JSON.stringify(envelope ?? null, null, 2));
+            return;
+        }
         const rows = envelope?.data ?? [];
         if (rows.length === 0) {
             process.stderr.write("No inbound emails yet. Send an email to one of your verified domains to populate this list.\n");
             return;
         }
+        const idWidth = pickIdWidth(Boolean(process.stdout.isTTY));
         // Header on stderr so the table itself stays grep-friendly.
-        const header = `${"ID".padEnd(ID_DISPLAY_WIDTH)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
+        const header = `${"ID".padEnd(idWidth)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
         process.stderr.write(`${header}\n`);
         for (const row of rows) {
-            this.log(formatRow(row));
+            this.log(formatRow(row, idWidth));
         }
     }
 }

package/dist/oclif/commands/send.js

@@ -103,6 +103,7 @@ class SendCommand extends Command {
         "<%= 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 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",
     ];
     static flags = {
         "api-key": Flags.string({

package/dist/oclif/index.js

@@ -50,7 +50,16 @@ class DescribeCommand extends Command {
     };
     static 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.
 
-  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.`;
+  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:
+
+      # Which of EmailDetail's sender-shaped fields is canonical?
+      primitive describe emails:get-email | jq '.responseSchema.properties | keys'
+      primitive describe emails:get-email | jq -r '.responseSchema.properties.from_email.description'
+
+      # What does each value of SentEmailStatus mean?
+      primitive describe sending:get-sent-email | jq -r '.responseSchema.properties.status.description'
+
+  \`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.`;
     static summary = "Describe a single API operation in detail";
     static examples = [
         "<%= config.bin %> describe emails:get-email",

package/dist/openapi/index.d.ts

@@ -37,6 +37,12 @@ type PrimitiveOperationManifest = {
    * true. `$ref`s into the OpenAPI components are inlined.
    */
   requestSchema: Record<string, unknown> | null;
+  /**
+   * Resolved JSON Schema for the 200/201 response body's `data`
+   * envelope contents. Same shape as `requestSchema`: `$ref`s
+   * inlined. Null on operations without a 200/201 JSON response.
+   */
+  responseSchema: Record<string, unknown> | null;
   sdkName: string;
   summary: string | null;
   tag: string;

package/dist/openapi/openapi.generated.js

@@ -557,15 +557,9 @@ export const openapiDocument = {
                         "name": "status",
                         "in": "query",
                         "schema": {
-                            "type": "string",
-                            "enum": [
-                                "pending",
-                                "accepted",
-                                "completed",
-                                "rejected"
-                            ]
+                            "$ref": "#/components/schemas/EmailStatus"
                         },
-                        "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": "search",
@@ -638,7 +632,8 @@ export const openapiDocument = {
             ],
             "get": {
                 "operationId": "getEmail",
-                "summary": "Get email details",
+                "summary": "Get inbound email by 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",
                 "tags": [
                     "Emails"
                 ],
@@ -983,6 +978,66 @@ export const openapiDocument = {
                 }
             }
         },
+        "/emails/{id}/discard-content": {
+            "parameters": [
+                {
+                    "$ref": "#/components/parameters/ResourceId"
+                }
+            ],
+            "post": {
+                "operationId": "discardEmailContent",
+                "summary": "Discard email content",
+                "description": "Permanently deletes the email's raw bytes, parsed body (text + HTML),\nand attachments while preserving metadata (sender, recipient,\nsubject, timestamps, hashes, attachment manifest) for audit logs.\nIdempotent: a second call returns success with\n`already_discarded: true` and does no work.\n\n**Gated** on the customer's discard-content opt-in (managed in the\ndashboard at Settings > Webhooks). When the toggle is off, this\nendpoint returns `403` with code `discard_not_enabled` and a\nmessage pointing the human at the dashboard. There is intentionally\nno API to flip this toggle — opting in to a destructive,\nnon-reversible operation must be a deliberate human click in the\nUI.\n",
+                "tags": [
+                    "Emails"
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Discard result",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/DiscardContentResult"
+                                                }
+                                            },
+                                            "required": [
+                                                "data"
+                                            ]
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "403": {
+                        "$ref": "#/components/responses/Forbidden"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    },
+                    "429": {
+                        "$ref": "#/components/responses/RateLimited"
+                    },
+                    "500": {
+                        "$ref": "#/components/responses/InternalError"
+                    }
+                }
+            }
+        },
         "/endpoints": {
             "get": {
                 "operationId": "listEndpoints",
@@ -2101,6 +2156,7 @@ export const openapiDocument = {
                                     "outbound_capacity_exhausted",
                                     "outbound_response_malformed",
                                     "outbound_relay_failed",
+                                    "discard_not_enabled",
                                     "inbound_not_repliable"
                                 ]
                             },
@@ -2614,13 +2670,7 @@ export const openapiDocument = {
                         "format": "uuid"
                     },
                     "status": {
-                        "type": "string",
-                        "enum": [
-                            "pending",
-                            "accepted",
-                            "completed",
-                            "rejected"
-                        ]
+                        "$ref": "#/components/schemas/EmailStatus"
                     },
                     "sender": {
                         "type": "string",
@@ -2659,18 +2709,7 @@ export const openapiDocument = {
                         ]
                     },
                     "webhook_status": {
-                        "type": [
-                            "string",
-                            "null"
-                        ],
-                        "enum": [
-                            "pending",
-                            "in_flight",
-                            "fired",
-                            "failed",
-                            "exhausted",
-                            null
-                        ]
+                        "$ref": "#/components/schemas/EmailWebhookStatus"
                     },
                     "webhook_attempt_count": {
                         "type": "integer"
@@ -2742,13 +2781,7 @@ export const openapiDocument = {
                         "description": "HTML body parsed from the inbound MIME, matching the `email.parsed.body_html` field on the webhook payload. Null when the message had no HTML part or parsing failed."
                     },
                     "status": {
-                        "type": "string",
-                        "enum": [
-                            "pending",
-                            "accepted",
-                            "completed",
-                            "rejected"
-                        ]
+                        "$ref": "#/components/schemas/EmailStatus"
                     },
                     "domain": {
                         "type": "string"
@@ -2786,18 +2819,7 @@ export const openapiDocument = {
                         ]
                     },
                     "webhook_status": {
-                        "type": [
-                            "string",
-                            "null"
-                        ],
-                        "enum": [
-                            "pending",
-                            "in_flight",
-                            "fired",
-                            "failed",
-                            "exhausted",
-                            null
-                        ]
+                        "$ref": "#/components/schemas/EmailWebhookStatus"
                     },
                     "webhook_attempt_count": {
                         "type": "integer"
@@ -3009,6 +3031,31 @@ export const openapiDocument = {
                     "subject"
                 ]
             },
+            "EmailStatus": {
+                "type": "string",
+                "description": "Lifecycle status of an INBOUND email (a row in the `emails`\ntable). Distinct from `SentEmailStatus`, which describes\nthe OUTBOUND lifecycle (the `sent_emails` table) and uses\na different vocabulary because the lifecycles differ.\nPossible values:\n\n  - `pending`: the row was inserted at ingestion (mx_main)\n    and has not yet completed the spam / filter / auth\n    pipeline. Body and parsed fields are present; webhook\n    delivery is not yet scheduled. Most rows transition out\n    of `pending` within seconds.\n  - `accepted`: the inbound passed the policy gates and is\n    queued for webhook delivery. The `webhook_status` field\n    tracks the separate webhook-delivery lifecycle from\n    this point.\n  - `completed`: terminal success. Webhook delivery\n    attempted and acknowledged by every active endpoint, OR\n    no endpoints are configured, so the row is durably\n    archived.\n  - `rejected`: terminal failure at ingestion (spam, blocked\n    sender, filter rule, malformed). The body and metadata\n    are stored for auditing but no webhook fires and the\n    row is not repliable.\n\nSee also `webhook_status` (separate enum tracking the\nwebhook-delivery state machine) and `SentEmailStatus` (the\noutbound vocabulary).\n",
+                "enum": [
+                    "pending",
+                    "accepted",
+                    "completed",
+                    "rejected"
+                ]
+            },
+            "EmailWebhookStatus": {
+                "type": [
+                    "string",
+                    "null"
+                ],
+                "description": "Webhook-delivery state for an inbound email. Tracks a\nSEPARATE lifecycle from the email's `status` field; the\nsame row carries both. Possible values:\n\n  - `pending`: ingestion is past `pending` (the email itself\n    is `accepted`) but the webhook fan-out has not yet\n    started for this row.\n  - `in_flight`: at least one delivery attempt is in flight.\n  - `fired`: terminal success. Every active endpoint\n    acknowledged the delivery (or accepted it after retries).\n  - `failed`: terminal partial-failure. At least one endpoint\n    exhausted its retry budget; some endpoints may still\n    have succeeded.\n  - `exhausted`: terminal failure. Every endpoint exhausted\n    its retry budget without success.\n  - `null`: no endpoints configured, so no webhook lifecycle\n    applies.\n\nNote that the value `pending` here does NOT mean the email\nis `pending`; it means the email is past ingestion but\nwebhook delivery has not yet begun. Two overlapping uses\nof the word `pending` for distinct lifecycle phases.\n",
+                "enum": [
+                    "pending",
+                    "in_flight",
+                    "fired",
+                    "failed",
+                    "exhausted",
+                    null
+                ]
+            },
             "SentEmailStatus": {
                 "type": "string",
                 "description": "Lifecycle status of a sent_emails row. Possible values:\n\n  - `queued`: pre-call INSERT; the outbound agent has not\n    yet replied.\n  - `submitted_to_agent`: agent accepted; `queue_id` is set.\n  - `agent_failed`: agent rejected; `error_code` and\n    `error_message` carry the reason.\n  - `gate_denied`: a recipient-scope gate denied the send;\n    the agent was never called. The `gates` array carries\n    the denial detail. /send-mail returns 403 in this case\n    so callers see the denial synchronously; /sent-emails\n    additionally records the row for historical lookup,\n    which is when this status appears in a listing.\n  - `unknown`: terminal indeterminate; the on-box log\n    poller couldn't classify the receiver's response.\n  - `delivered` / `bounced` / `deferred` / `wait_timeout`:\n    terminal delivery outcomes (see DeliveryStatus).\n",
@@ -3026,6 +3073,7 @@ export const openapiDocument = {
             },
             "DeliveryStatus": {
                 "type": "string",
+                "description": "Narrower enum covering only the four terminal delivery\noutcomes returned to a synchronous `wait: true` send.\n\nOn the SendMailResult shape, `delivery_status` is always\nequal to `status` whenever both are present (i.e. on\nterminal-state replays and live wait=true responses).\nThe two fields exist so callers that want to type-narrow\non \"this is a delivery outcome\" can pattern-match against\nthe four-value enum without handling the broader\nSentEmailStatus value set (which also covers `queued`,\n`submitted_to_agent`, `agent_failed`, `gate_denied`,\n`unknown`).\n\nOn async-mode and pre-terminal responses, `delivery_status`\nis absent and only `status` is populated. Use `status` if\nyou want a single field that's always present.\n",
                 "enum": [
                     "delivered",
                     "bounced",
@@ -3288,7 +3336,7 @@ export const openapiDocument = {
                             "string",
                             "null"
                         ],
-                        "description": "Message identifier assigned by Primitive's outbound relay, when available."
+                        "description": "Message identifier assigned by Primitive's OUTBOUND relay\n(the box that signs your mail and submits it to the\nreceiving MTA). NOT the receiver's queue id.\n\nThe receiver may also report its own queue id in\n`smtp_response_text` (e.g. `\"250 2.0.0 Ok: queued as\n99D111927CDA\"` from a Postfix receiver). Those two ids\nrefer to different mail systems and are NOT comparable.\nTreat `queue_id` as Primitive-internal and the\nreceiver's id as remote-system-internal.\n\nNull on rows that never reached the relay (queued,\ngate_denied, agent_failed before signing).\n"
                     },
                     "accepted": {
                         "type": "array",
@@ -3870,6 +3918,23 @@ export const openapiDocument = {
                     "delivered",
                     "failed"
                 ]
+            },
+            "DiscardContentResult": {
+                "type": "object",
+                "properties": {
+                    "discarded": {
+                        "type": "boolean",
+                        "description": "Always `true` on a 2xx response. The content is either now\ndiscarded as a result of this call, or was already discarded\nbefore this call ran.\n"
+                    },
+                    "already_discarded": {
+                        "type": "boolean",
+                        "description": "`true` if the email's content was already discarded before\nthis call ran (no work was done). `false` if this call was\nthe one that performed the discard.\n"
+                    }
+                },
+                "required": [
+                    "discarded",
+                    "already_discarded"
+                ]
             }
         }
     }