@primitivedotdev/sdk 0.16.0 → 0.18.0

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

@@ -1,7 +1,7 @@
 import { Command, Flags } from "@oclif/core";
 import { listEmails } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, writeErrorWithHints } from "../api-command.js";
+import { extractErrorPayload, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 // `primitive emails:latest` is the agent-grade shortcut for "show me
 // the most recent inbound emails as something I can read at a glance."
 // `emails:list-emails` returns the full JSON envelope which is great
@@ -113,43 +113,48 @@ class EmailsLatestCommand extends Command {
         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.",
         }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
     };
     async run() {
         const { flags } = await this.parse(EmailsLatestCommand);
-        const apiClient = new PrimitiveApiClient({
-            apiKey: flags["api-key"],
-            baseUrl: flags["base-url"],
-        });
-        const result = await listEmails({
-            client: apiClient.client,
-            query: { limit: flags.limit },
-            responseStyle: "fields",
+        await runWithTiming(flags.time, async () => {
+            const apiClient = new PrimitiveApiClient({
+                apiKey: flags["api-key"],
+                baseUrl: flags["base-url"],
+            });
+            const result = await listEmails({
+                client: apiClient.client,
+                query: { limit: flags.limit },
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                writeErrorWithHints(extractErrorPayload(result.error));
+                process.exitCode = 1;
+                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(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, idWidth));
+            }
         });
-        if (result.error) {
-            writeErrorWithHints(extractErrorPayload(result.error));
-            process.exitCode = 1;
-            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(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, idWidth));
-        }
     }
 }
 export default EmailsLatestCommand;

package/dist/oclif/commands/send.js

@@ -1,7 +1,7 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { listDomains, sendEmail } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorCode, extractErrorPayload, formatErrorPayload, writeErrorWithHints, } from "../api-command.js";
+import { extractErrorCode, extractErrorPayload, formatErrorPayload, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 // `primitive send` is the agent-grade shortcut for the most common
 // case: send a fresh outbound email. It wraps `sending:send-email`
 // with two ergonomic defaults that the underlying operation can't
@@ -139,43 +139,48 @@ class SendCommand extends Command {
         "wait-timeout-ms": Flags.integer({
             description: "Maximum time to wait when --wait is set. Defaults to 30000ms.",
         }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
     };
     async run() {
         const { flags } = await this.parse(SendCommand);
         if (!flags.body && !flags.html) {
             throw new Errors.CLIError("Either --body or --html (or both) is required.");
         }
-        const apiClient = new PrimitiveApiClient({
-            apiKey: flags["api-key"],
-            baseUrl: flags["base-url"],
-        });
-        const from = flags.from ?? (await pickDefaultFromAddress(apiClient));
-        const subject = flags.subject ?? (flags.body ? deriveSubject(flags.body) : "Message");
-        const result = await sendEmail({
-            body: {
-                from,
-                to: flags.to,
-                subject,
-                ...(flags.body !== undefined ? { body_text: flags.body } : {}),
-                ...(flags.html !== undefined ? { body_html: flags.html } : {}),
-                ...(flags["in-reply-to"] !== undefined
-                    ? { in_reply_to: flags["in-reply-to"] }
-                    : {}),
-                ...(flags.wait !== undefined ? { wait: flags.wait } : {}),
-                ...(flags["wait-timeout-ms"] !== undefined
-                    ? { wait_timeout_ms: flags["wait-timeout-ms"] }
-                    : {}),
-            },
-            client: apiClient.client,
-            responseStyle: "fields",
+        await runWithTiming(flags.time, async () => {
+            const apiClient = new PrimitiveApiClient({
+                apiKey: flags["api-key"],
+                baseUrl: flags["base-url"],
+            });
+            const from = flags.from ?? (await pickDefaultFromAddress(apiClient));
+            const subject = flags.subject ?? (flags.body ? deriveSubject(flags.body) : "Message");
+            const result = await sendEmail({
+                body: {
+                    from,
+                    to: flags.to,
+                    subject,
+                    ...(flags.body !== undefined ? { body_text: flags.body } : {}),
+                    ...(flags.html !== undefined ? { body_html: flags.html } : {}),
+                    ...(flags["in-reply-to"] !== undefined
+                        ? { in_reply_to: flags["in-reply-to"] }
+                        : {}),
+                    ...(flags.wait !== undefined ? { wait: flags.wait } : {}),
+                    ...(flags["wait-timeout-ms"] !== undefined
+                        ? { wait_timeout_ms: flags["wait-timeout-ms"] }
+                        : {}),
+                },
+                client: apiClient.client,
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                writeErrorWithHints(extractErrorPayload(result.error));
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = result.data;
+            this.log(JSON.stringify(envelope?.data ?? null, null, 2));
         });
-        if (result.error) {
-            writeErrorWithHints(extractErrorPayload(result.error));
-            process.exitCode = 1;
-            return;
-        }
-        const envelope = result.data;
-        this.log(JSON.stringify(envelope?.data ?? null, null, 2));
     }
 }
 export default SendCommand;

package/dist/oclif/commands/whoami.js

@@ -1,7 +1,7 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { getAccount } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, writeErrorWithHints } from "../api-command.js";
+import { extractErrorPayload, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 // `primitive whoami` is the credentials smoke-test the AGX
 // walkthrough kept asking for. Before this command, a user with a
 // suspect API key had no fast way to verify "is my key live and
@@ -28,40 +28,45 @@ class WhoamiCommand extends Command {
             description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
             env: "PRIMITIVE_API_URL",
         }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
     };
     async run() {
         const { flags } = await this.parse(WhoamiCommand);
-        const apiClient = new PrimitiveApiClient({
-            apiKey: flags["api-key"],
-            baseUrl: flags["base-url"],
-        });
-        const result = await getAccount({
-            client: apiClient.client,
-            responseStyle: "fields",
+        await runWithTiming(flags.time, async () => {
+            const apiClient = new PrimitiveApiClient({
+                apiKey: flags["api-key"],
+                baseUrl: flags["base-url"],
+            });
+            const result = await getAccount({
+                client: apiClient.client,
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                writeErrorWithHints(extractErrorPayload(result.error));
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = result.data;
+            const account = envelope?.data;
+            if (!account) {
+                process.stderr.write("Server returned an empty account body; this should not happen for a valid key.\n");
+                throw new Errors.CLIError("unexpected empty response");
+            }
+            // Concise human-readable summary on stderr; the full account
+            // JSON goes to stdout so a script can pipe it.
+            const onboarding = account.onboarding_completed === true
+                ? "complete"
+                : account.onboarding_step
+                    ? `in progress (step: ${account.onboarding_step})`
+                    : "incomplete";
+            process.stderr.write(`Authenticated as ${account.email}\n`);
+            process.stderr.write(`  Account id: ${account.id}\n`);
+            process.stderr.write(`  Plan:       ${account.plan}\n`);
+            process.stderr.write(`  Onboarding: ${onboarding}\n`);
+            this.log(JSON.stringify(account, null, 2));
         });
-        if (result.error) {
-            writeErrorWithHints(extractErrorPayload(result.error));
-            process.exitCode = 1;
-            return;
-        }
-        const envelope = result.data;
-        const account = envelope?.data;
-        if (!account) {
-            process.stderr.write("Server returned an empty account body; this should not happen for a valid key.\n");
-            throw new Errors.CLIError("unexpected empty response");
-        }
-        // Concise human-readable summary on stderr; the full account
-        // JSON goes to stdout so a script can pipe it.
-        const onboarding = account.onboarding_completed === true
-            ? "complete"
-            : account.onboarding_step
-                ? `in progress (step: ${account.onboarding_step})`
-                : "incomplete";
-        process.stderr.write(`Authenticated as ${account.email}\n`);
-        process.stderr.write(`  Account id: ${account.id}\n`);
-        process.stderr.write(`  Plan:       ${account.plan}\n`);
-        process.stderr.write(`  Onboarding: ${onboarding}\n`);
-        this.log(JSON.stringify(account, null, 2));
     }
 }
 export default WhoamiCommand;

package/dist/openapi/openapi.generated.js

@@ -9,7 +9,7 @@ export const openapiDocument = {
     "info": {
         "title": "Primitive API",
         "version": "1.0.0",
-        "description": "The Primitive API lets you manage domains, emails, webhook endpoints,\nfilters, and account settings programmatically.\n\n## Authentication\n\nAll endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer prim_<your_api_key>\n```\n\nAPI keys are org-scoped. Create and manage them in your dashboard\nunder Settings > API Keys.\n\n## Rate Limiting\n\nThe API enforces a sliding window rate limit of **120 requests per\n60 seconds** per organization. When exceeded, the API returns `429`\nwith a `Retry-After` header indicating how many seconds to wait.\n\n## Pagination\n\nList endpoints use cursor-based pagination. Responses include a\n`meta` object with `total`, `limit`, and `cursor` fields. Pass the\n`cursor` value as a query parameter to fetch the next page. When\n`cursor` is `null`, there are no more results.\n\n## Response Format\n\nAll responses use a consistent envelope:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": { \"total\": 42, \"limit\": 50, \"cursor\": \"...\" }\n}\n```\n\nErrors follow the same pattern:\n\n```json\n{\n  \"success\": false,\n  \"error\": { \"code\": \"not_found\", \"message\": \"Email not found\" }\n}\n```\n",
+        "description": "The Primitive API lets you manage domains, emails, webhook endpoints,\nfilters, and account settings programmatically.\n\n## Authentication\n\nAll endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer prim_<your_api_key>\n```\n\nAPI keys are org-scoped. Create and manage them in your dashboard\nunder Settings > API Keys.\n\n## Rate Limiting\n\nThe API enforces a sliding window rate limit of **120 requests per\n60 seconds** per organization. When exceeded, the API returns `429`\nwith a `Retry-After` header indicating how many seconds to wait.\n\n## Pagination\n\nList endpoints use cursor-based pagination. Responses include a\n`meta` object with `total`, `limit`, and `cursor` fields. Pass the\n`cursor` value as a query parameter to fetch the next page. When\n`cursor` is `null`, there are no more results.\n\n## Response Format\n\nAll responses use a consistent envelope:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": { \"total\": 42, \"limit\": 50, \"cursor\": \"...\" }\n}\n```\n\nErrors follow the same pattern:\n\n```json\n{\n  \"success\": false,\n  \"error\": { \"code\": \"not_found\", \"message\": \"Email not found\" }\n}\n```\n\n## Webhook signing\n\nOutbound webhook deliveries (configured via the `endpoints` API)\nare signed so receivers can verify they came from Primitive and\nhave not been tampered with in transit. The signing scheme is\ndeliberately simple so it can be reimplemented in any language\nin a few lines. The Node SDK's `verifyWebhookSignature` helper\nis the reference implementation; the wire details below let you\nwrite a verifier in Python, Go, Ruby, etc. without reading our\nsource.\n\n**Header**: `Primitive-Signature: t=<unix-seconds>,v1=<hex>`\n\nA legacy `MyMX-Signature` header is also sent on every delivery\nwith the same value, retained for back-compatibility with\nintegrations written before the rename. New code should read\n`Primitive-Signature`.\n\n**Signed string**: `${timestamp}.${rawBody}` where `timestamp`\nis the Unix-seconds integer from the `t=` parameter and\n`rawBody` is the exact bytes of the HTTP request body BEFORE\nany JSON decoding. Verify against the raw body, not a\nre-serialized parse, or you will silently mismatch on\ninsignificant whitespace.\n\n**Signature**: HMAC-SHA256 of the signed string, hex-encoded\n(lowercase). Use the account's webhook secret as the HMAC key,\nas a UTF-8 byte sequence.\n\n**Secret**: returned by `GET /account/webhook-secret`. The\nstring looks base64-shaped (e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`)\nbut is NOT base64; use it AS-IS as a UTF-8 string for the HMAC\nkey. Base64-decoding before HMAC will silently produce\nmismatched signatures.\n\n**Tolerance**: by convention, reject deliveries whose `t=`\ntimestamp is more than 5 minutes off your wall-clock to defend\nagainst replay attacks. The Node SDK's helper enforces this by\ndefault.\n\n**Verification recipe** (any language):\n\n```\n1. Read the raw HTTP body (do not parse).\n2. Read `Primitive-Signature: t=<ts>,v1=<sig>`.\n3. Reject if abs(now - ts) > 300 seconds.\n4. expected = HMAC_SHA256_hex(secret_utf8, f\"{ts}.{rawBody}\")\n5. Constant-time compare expected to sig. Reject if not equal.\n```\n\nFor Node, use `verifyWebhookSignature` from\n`@primitivedotdev/sdk/webhook` (or the higher-level\n`handleWebhook` helper if you want a one-liner). For other\nlanguages, the recipe above is everything you need.\n\nTest deliveries: `POST /endpoints/{id}/test` triggers a fake\ndelivery to your endpoint URL, signed with your real account\nsecret, so you can confirm verification end-to-end without\nneeding real inbound mail. The test response carries the exact\n`signature` header value sent on the wire so you can compare\nstrings directly.\n",
         "contact": {
             "name": "Primitive",
             "url": "https://primitive.dev"
@@ -193,7 +193,7 @@ export const openapiDocument = {
             "get": {
                 "operationId": "getWebhookSecret",
                 "summary": "Get webhook signing secret",
-                "description": "Returns the webhook signing secret for your account. If no secret\nexists yet, one is generated automatically on first access.\n",
+                "description": "Returns the webhook signing secret for your account. If no\nsecret exists yet, one is generated automatically on first\naccess.\n\nSigning is account-scoped, not per-endpoint. Every webhook\ndelivery from any of your registered endpoints is signed\nwith this single secret. Rotate via\n`POST /account/webhook-secret/rotate`.\n\n**Secret format**: the returned string looks base64-shaped\n(e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`) but is NOT base64.\nUse it AS-IS as a UTF-8 string when computing HMAC over a\ndelivery body. Base64-decoding before HMAC will silently\nproduce mismatched signatures.\n\nSee the API-level \"Webhook signing\" section for the full\nwire format (header name, signed string shape, hash algo,\ntolerance) including a language-agnostic verification\nrecipe.\n",
                 "tags": [
                     "Account"
                 ],
@@ -533,7 +533,7 @@ export const openapiDocument = {
             "get": {
                 "operationId": "listEmails",
                 "summary": "List inbound emails",
-                "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",
+                "description": "Returns a paginated list of INBOUND emails received at your\nverified domains. Outbound messages sent via /send-mail are\nnot included; this endpoint is the inbox view, not a\nunified send/receive history.\n\nSupports filtering by domain, status, date range, and\nfree-text search across subject, sender, and recipient\nfields.\n\nFor a compact text-table summary of the most recent N\ninbounds (no filters, no cursor pagination), the CLI ships\n`primitive emails:latest` as a one-line-per-email shortcut.\nIt's TTY-aware so id columns are full UUIDs when piped, and\na `--json` flag returns the same envelope this endpoint\ndoes. Use whichever fits the call site.\n",
                 "tags": [
                     "Emails"
                 ],
@@ -1080,7 +1080,7 @@ export const openapiDocument = {
             "post": {
                 "operationId": "createEndpoint",
                 "summary": "Create a webhook endpoint",
-                "description": "Creates a new webhook endpoint. If a deactivated endpoint with the\nsame URL and domain exists, it is reactivated instead.\nSubject to plan limits on the number of active endpoints.\n",
+                "description": "Creates a new webhook endpoint. If a deactivated endpoint\nwith the same URL and domain exists, it is reactivated\ninstead. Subject to plan limits on the number of active\nendpoints.\n\n**Signing is account-scoped, not per-endpoint.** This call\ndoes not return any signing material; every endpoint on the\naccount uses the same webhook secret, fetched via\n`GET /account/webhook-secret`. See the API-level \"Webhook\nsigning\" section for the full wire format (header name,\nsigned string, hash algo, secret format, tolerance) and a\nlanguage-agnostic verification recipe.\n\nAfter creating the endpoint, fire a test delivery against\nit via `POST /endpoints/{id}/test` to confirm your verifier\naccepts the signature.\n",
                 "tags": [
                     "Endpoints"
                 ],

package/dist/openapi/operations.generated.js

@@ -152,7 +152,7 @@ export const operationManifest = [
         "binaryResponse": false,
         "bodyRequired": false,
         "command": "get-webhook-secret",
-        "description": "Returns the webhook signing secret for your account. If no secret\nexists yet, one is generated automatically on first access.\n",
+        "description": "Returns the webhook signing secret for your account. If no\nsecret exists yet, one is generated automatically on first\naccess.\n\nSigning is account-scoped, not per-endpoint. Every webhook\ndelivery from any of your registered endpoints is signed\nwith this single secret. Rotate via\n`POST /account/webhook-secret/rotate`.\n\n**Secret format**: the returned string looks base64-shaped\n(e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`) but is NOT base64.\nUse it AS-IS as a UTF-8 string when computing HMAC over a\ndelivery body. Base64-decoding before HMAC will silently\nproduce mismatched signatures.\n\nSee the API-level \"Webhook signing\" section for the full\nwire format (header name, signed string shape, hash algo,\ntolerance) including a language-agnostic verification\nrecipe.\n",
         "hasJsonBody": false,
         "method": "GET",
         "operationId": "getWebhookSecret",
@@ -1071,7 +1071,7 @@ export const operationManifest = [
         "binaryResponse": false,
         "bodyRequired": false,
         "command": "list-emails",
-        "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",
+        "description": "Returns a paginated list of INBOUND emails received at your\nverified domains. Outbound messages sent via /send-mail are\nnot included; this endpoint is the inbox view, not a\nunified send/receive history.\n\nSupports filtering by domain, status, date range, and\nfree-text search across subject, sender, and recipient\nfields.\n\nFor a compact text-table summary of the most recent N\ninbounds (no filters, no cursor pagination), the CLI ships\n`primitive emails:latest` as a one-line-per-email shortcut.\nIt's TTY-aware so id columns are full UUIDs when piped, and\na `--json` flag returns the same envelope this endpoint\ndoes. Use whichever fits the call site.\n",
         "hasJsonBody": false,
         "method": "GET",
         "operationId": "listEmails",
@@ -1286,7 +1286,7 @@ export const operationManifest = [
         "binaryResponse": false,
         "bodyRequired": true,
         "command": "create-endpoint",
-        "description": "Creates a new webhook endpoint. If a deactivated endpoint with the\nsame URL and domain exists, it is reactivated instead.\nSubject to plan limits on the number of active endpoints.\n",
+        "description": "Creates a new webhook endpoint. If a deactivated endpoint\nwith the same URL and domain exists, it is reactivated\ninstead. Subject to plan limits on the number of active\nendpoints.\n\n**Signing is account-scoped, not per-endpoint.** This call\ndoes not return any signing material; every endpoint on the\naccount uses the same webhook secret, fetched via\n`GET /account/webhook-secret`. See the API-level \"Webhook\nsigning\" section for the full wire format (header name,\nsigned string, hash algo, secret format, tolerance) and a\nlanguage-agnostic verification recipe.\n\nAfter creating the endpoint, fire a test delivery against\nit via `POST /endpoints/{id}/test` to confirm your verifier\naccepts the signature.\n",
         "hasJsonBody": true,
         "method": "POST",
         "operationId": "createEndpoint",