@primitivedotdev/sdk 0.13.0 → 0.15.0

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

@@ -0,0 +1,131 @@
+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";
+// `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
+// for piping but blows out the screen for a quick triage. The AGX
+// walkthrough flagged that an agent doing inbox triage had no compact
+// view to reach for; `latest` is that view.
+//
+// Output is a fixed-width text table: short-id, received timestamp,
+// from address, to address, and subject. Subject is truncated for
+// display only; the underlying JSON is unchanged. For machine-readable
+// output, callers should use `emails:list-emails` and pipe to jq.
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+// Truncation widths chosen so a row fits in ~140 columns total. Long
+// values wrap to "..." rather than blowing out terminal layout.
+const SUBJECT_DISPLAY_WIDTH = 50;
+const ADDRESS_DISPLAY_WIDTH = 32;
+const ID_DISPLAY_WIDTH = 8;
+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`
+// chars (3 of which are the ellipsis). Display-only; never mutates
+// the underlying value the caller passed in.
+//
+// Width-exact output matters here: formatRow relies on each column
+// being exactly its declared width so columns line up across rows.
+// An overflowing truncate would shift every later column to the
+// right whenever truncation fired (e.g. a row with both addresses
+// truncated would push SUBJECT 4 chars off).
+export function truncate(value, width) {
+    if (value.length <= width)
+        return value.padEnd(width);
+    return `${value.slice(0, width - 3)}...`;
+}
+// Compact ISO timestamp for display: `YYYY-MM-DD HH:MM:SS` in UTC.
+// The full ISO string with milliseconds and `T`/`Z` markers is too
+// dense to scan at a glance; this is the same shape git log uses.
+export function formatReceivedAt(value) {
+    if (!value)
+        return "-".padEnd(RECEIVED_DISPLAY_WIDTH);
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()))
+        return value.padEnd(RECEIVED_DISPLAY_WIDTH);
+    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);
+    const received = formatReceivedAt(email.received_at);
+    const from = truncate(email.sender ?? "", ADDRESS_DISPLAY_WIDTH);
+    const to = truncate(email.recipient ?? "", ADDRESS_DISPLAY_WIDTH);
+    const subject = (email.subject ?? "").replace(/\s+/g, " ");
+    const subjectCol = truncate(subject, SUBJECT_DISPLAY_WIDTH);
+    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) or pass \`--json\` here for the same raw shape without pagination/filters.
+
+  The default text table truncates each row's id to the first ${ID_DISPLAY_WIDTH} 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.
+
+  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.`;
+    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 --json | jq '.data[0].id'",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "base-url": Flags.string({
+            description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
+            env: "PRIMITIVE_API_URL",
+        }),
+        limit: Flags.integer({
+            description: `Number of rows to print (1-${MAX_LIMIT}, default ${DEFAULT_LIMIT}).`,
+            default: DEFAULT_LIMIT,
+            // oclif validates min/max at parse time and emits a consistent
+            // out-of-range error before run() is reached, so no manual
+            // bounds check is needed here.
+            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);
+        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;
+        }
+        // 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`;
+        process.stderr.write(`${header}\n`);
+        for (const row of rows) {
+            this.log(formatRow(row));
+        }
+    }
+}
+export default EmailsLatestCommand;

package/dist/oclif/commands/send.js

@@ -30,7 +30,15 @@ import { extractErrorCode, extractErrorPayload, formatErrorPayload, writeErrorWi
 // pattern-matching from there lands in the happy path. We just
 // don't need swaks's `--server` / `--auth-*` flags because the
 // HTTPS API key is the auth and the server is implicit.
-const SUBJECT_MAX_LENGTH = 70;
+// 200 chars is a generous cap that almost never trips on natural
+// first-line subjects (a sentence is typically <120 chars). The
+// previous 70-char limit was tight enough that legitimate one-line
+// bodies routinely produced ellipsis-truncated subjects in inbox
+// listings, e.g. `"this is the simplest possible send: agent typed
+// two flags and hit\\n e..."` from the AGX walkthrough. Real spam
+// scoring engines don't penalize subjects under ~200 chars, so 200
+// is both more useful and still well under the practical wire limit.
+const SUBJECT_MAX_LENGTH = 200;
 function deriveSubject(body) {
     for (const line of body.split("\n")) {
         const trimmed = line.trim();
@@ -95,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

@@ -1,16 +1,82 @@
-import { Args, Command } from "@oclif/core";
+import { Args, Command, Errors } from "@oclif/core";
 import { operationManifest, } from "../openapi/index.js";
 import { createOperationCommand } from "./api-command.js";
+import EmailsLatestCommand from "./commands/emails-latest.js";
 import SendCommand from "./commands/send.js";
 import WhoamiCommand from "./commands/whoami.js";
 import { renderFishCompletion } from "./fish-completion.js";
 class ListOperationsCommand extends Command {
-    static description = "List all generated API operations";
-    static summary = "List all generated API operations";
+    static 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>`.";
+    static summary = "List all generated API operations (JSON)";
     async run() {
         this.log(JSON.stringify(operationManifest, null, 2));
     }
 }
+// Looks up an operation manifest entry by its `<topic>:<command>` id
+// (e.g. `emails:get-email`). On miss, returns up to 5 closest
+// candidates by substring match so the caller can render a
+// "did you mean" hint. Pure function: no oclif config dependency,
+// so it's also unit-testable in isolation.
+export function lookupOperation(id) {
+    const trimmed = id.trim();
+    const sep = trimmed.indexOf(":");
+    const tag = sep === -1 ? "" : trimmed.slice(0, sep);
+    const cmd = sep === -1 ? trimmed : trimmed.slice(sep + 1);
+    const match = operationManifest.find((op) => op.command === cmd && op.tagCommand === tag) ?? null;
+    if (match)
+        return { match, candidates: [] };
+    const candidates = operationManifest
+        .filter((op) => op.command.includes(cmd) || op.tagCommand.includes(tag))
+        .slice(0, 5)
+        .map((op) => op.tagCommand ? `${op.tagCommand}:${op.command}` : op.command);
+    return { match: null, candidates };
+}
+// `primitive describe <command>` is the operation-detail inspector
+// the AGX walkthrough kept wanting. The information is already in
+// the operation manifest emitted by `list-operations`, but agents
+// don't intuitively reach for `list-operations | jq '.[] | select(...)'`
+// when they want to know "what does the from_email field on this
+// response actually mean." A direct command is more discoverable.
+//
+// Lookup is by the colon-joined command id (e.g. `emails:get-email`,
+// `sending:send-email`, `account:get-account`). For top-level
+// generated commands (without a topic), pass the bare command id.
+class DescribeCommand extends Command {
+    static args = {
+        command: Args.string({
+            description: "Command id to describe, in `<topic>:<command>` form (e.g. `emails:get-email`). Run `primitive list-operations | jq -r '.[] | \"\\(.tagCommand):\\(.command)\"'` to enumerate.",
+            required: true,
+        }),
+    };
+    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.
+
+  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",
+        "<%= config.bin %> describe sending:send-email",
+    ];
+    async run() {
+        const { args } = await this.parse(DescribeCommand);
+        const { match, candidates } = lookupOperation(args.command);
+        if (!match) {
+            const hint = candidates.length > 0
+                ? `Did you mean: ${candidates.join(", ")}?`
+                : "Run `primitive list-operations` to enumerate.";
+            throw new Errors.CLIError(`Unknown operation \`${args.command.trim()}\`. ${hint}`, { exit: 1 });
+        }
+        this.log(JSON.stringify(match, null, 2));
+    }
+}
 class CompletionCommand extends Command {
     static args = {
         shell: Args.string({
@@ -40,6 +106,11 @@ const generatedCommands = Object.fromEntries(operationManifest.map((operation) =
 export const COMMANDS = {
     completion: CompletionCommand,
     "list-operations": ListOperationsCommand,
+    // `describe` prints a single operation's full manifest entry
+    // (path, request schema, response schema, per-field descriptions).
+    // The same data is in `list-operations` but agents don't reach for
+    // `list-operations | jq` when they want to clarify a field meaning.
+    describe: DescribeCommand,
     // `send` is the agent-grade shortcut for sending:send-email with
     // sensible defaults (auto from-address, auto subject). The full
     // operation stays available under sending:send-email for callers
@@ -50,5 +121,9 @@ export const COMMANDS = {
     // wanting this before risking a real call against a possibly-
     // bad key.
     whoami: WhoamiCommand,
+    // `emails:latest` is the inbox-triage shortcut: the most recent N
+    // inbound emails as a compact text table. emails:list-emails stays
+    // available for the full JSON envelope + cursor pagination.
+    "emails:latest": EmailsLatestCommand,
     ...generatedCommands,
 };

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;