@primitivedotdev/sdk 0.10.0 → 0.12.0

package/dist/oclif/api-command.js

@@ -7,80 +7,126 @@ function flagName(parameterName) {
 function flagDescription(parameter) {
     return parameter.description ?? parameter.name;
 }
-/**
- * Render a one-shot description of a JSON Schema's top-level
- * properties so an agent reading `<command> --help` can build a
- * valid `--body` payload without probing the server. Pulled from
- * the resolved request schema embedded on the manifest.
- *
- * Format prioritizes scanability over completeness: required
- * fields first, each line is `<name> <type> [- description]`
- * truncated to a reasonable width. Callers who need the full
- * schema can run `primitive list-operations | jq` and read
- * `requestSchema` directly.
- */
-function renderRequestSchemaSummary(schema) {
+function extractBodyFields(schema) {
     if (!schema || typeof schema !== "object")
-        return null;
+        return [];
     const properties = schema.properties;
     if (!properties || typeof properties !== "object")
-        return null;
+        return [];
     const requiredArr = Array.isArray(schema.required)
         ? schema.required.filter((k) => typeof k === "string")
         : [];
     const required = new Set(requiredArr);
-    const entries = Object.entries(properties)
-        .map(([name, raw]) => {
+    const fields = [];
+    for (const [name, raw] of Object.entries(properties)) {
         const propSchema = raw && typeof raw === "object" ? raw : {};
-        let type = "any";
         const t = propSchema.type;
+        let displayType = "any";
+        let kind = "complex";
         if (typeof t === "string") {
-            type = t;
-            if (type === "array") {
+            displayType = t;
+            if (t === "string")
+                kind = "string";
+            else if (t === "integer" || t === "number")
+                kind = "integer";
+            else if (t === "boolean")
+                kind = "boolean";
+            else if (t === "array") {
                 const items = propSchema.items;
                 if (items && typeof items === "object") {
                     const itemType = items.type;
                     if (typeof itemType === "string") {
-                        type = `array<${itemType}>`;
+                        displayType = `array<${itemType}>`;
                     }
                 }
+                kind = "complex";
+            }
+            else {
+                kind = "complex";
             }
         }
         else if (Array.isArray(t)) {
-            // Nullable shorthand the codegen normalizes to e.g. ["string","null"].
+            // Nullable shorthand the codegen normalizes to e.g.
+            // ["string","null"]. If exactly one non-null member, surface
+            // it as that scalar with a trailing `?`.
             const nonNull = t.filter((s) => s !== "null");
-            type = nonNull.length === 1 ? `${nonNull[0]}?` : nonNull.join("|");
+            if (nonNull.length === 1) {
+                const single = nonNull[0];
+                displayType = `${single}?`;
+                if (single === "string")
+                    kind = "string";
+                else if (single === "integer" || single === "number")
+                    kind = "integer";
+                else if (single === "boolean")
+                    kind = "boolean";
+                else
+                    kind = "complex";
+            }
+            else {
+                displayType = nonNull.join("|");
+                kind = "complex";
+            }
         }
         const description = typeof propSchema.description === "string"
             ? propSchema.description.split("\n")[0].trim()
             : "";
-        return {
+        const enumRaw = propSchema.enum;
+        const enumValues = kind === "string" && Array.isArray(enumRaw)
+            ? enumRaw.filter((e) => typeof e === "string")
+            : undefined;
+        fields.push({
             name,
-            type,
             description,
             required: required.has(name),
-        };
-    })
-        .sort((a, b) => {
+            displayType,
+            kind,
+            ...(enumValues && enumValues.length > 0 ? { enumValues } : {}),
+        });
+    }
+    return fields.sort((a, b) => {
         if (a.required !== b.required)
             return a.required ? -1 : 1;
         return a.name.localeCompare(b.name);
     });
-    if (entries.length === 0)
+}
+/**
+ * Render a "Body fields" summary for the per-command help.
+ *
+ * Most scalar fields are exposed as individual `--flag` flags,
+ * which oclif auto-renders in the FLAGS section above. To avoid
+ * duplicating that, the summary here only documents fields that
+ * MUST go through `--raw-body` (complex types: arrays, objects,
+ * mixed-non-nullable). When an operation has only scalars, the
+ * summary is omitted entirely and oclif's FLAGS section is the
+ * full story.
+ *
+ * For operations with mixed scalar and complex fields, we also
+ * include a short header pointing the agent at the flag form so
+ * the natural reading is "use the flags above; --raw-body for
+ * the leftovers below."
+ */
+function renderRequestSchemaSummary(schema) {
+    const fields = extractBodyFields(schema);
+    if (fields.length === 0)
+        return null;
+    const complex = fields.filter((f) => f.kind === "complex");
+    if (complex.length === 0)
         return null;
-    const nameWidth = Math.min(24, Math.max(...entries.map((e) => e.name.length)));
-    const lines = ["Body fields (JSON --body):"];
+    const nameWidth = Math.min(24, Math.max(...complex.map((f) => f.name.length)));
     const descMax = 78;
-    for (const e of entries) {
-        const flag = e.required ? " *" : "  ";
-        const padName = e.name.padEnd(nameWidth);
-        const trimmedDesc = e.description.length > descMax
-            ? `${e.description.slice(0, descMax - 3)}...`
-            : e.description;
+    const lines = [
+        "Body fields requiring --raw-body JSON (these are not exposed as flags):",
+    ];
+    for (const f of complex) {
+        const marker = f.required ? " *" : "  ";
+        const padName = f.name.padEnd(nameWidth);
+        const trimmedDesc = f.description.length > descMax
+            ? `${f.description.slice(0, descMax - 3)}...`
+            : f.description;
         const desc = trimmedDesc ? `  ${trimmedDesc}` : "";
-        lines.push(`${flag} ${padName}  ${e.type}${desc}`);
+        lines.push(`${marker} ${padName}  ${f.displayType}${desc}`);
     }
-    lines.push("(* = required)");
+    lines.push("(* = required. Scalar body fields are exposed as individual --flag-name flags; see FLAGS above.)");
     return lines.join("\n");
 }
 export function flagForParameter(parameter) {
@@ -134,9 +180,9 @@ function parseJson(source, flagLabel) {
 }
 export function readJsonBody(flags) {
     const bodyFile = flags["body-file"];
-    const body = flags.body;
-    if (bodyFile && body) {
-        throw cliError("Use either --body or --body-file, not both");
+    const rawBody = flags["raw-body"];
+    if (bodyFile && rawBody) {
+        throw cliError("Use either --raw-body or --body-file, not both");
     }
     if (typeof bodyFile === "string") {
         let contents;
@@ -149,8 +195,8 @@ export function readJsonBody(flags) {
         }
         return parseJson(contents, `--body-file ${bodyFile}`);
     }
-    if (typeof body === "string") {
-        return parseJson(body, "--body");
+    if (typeof rawBody === "string") {
+        return parseJson(rawBody, "--raw-body");
     }
     return undefined;
 }
@@ -196,6 +242,56 @@ export function formatErrorPayload(payload) {
     }
     return JSON.stringify(payload, null, 2);
 }
+// Reserved flag names the body-field expander must never overwrite.
+// `--raw-body` and `--body-file` are the JSON escape hatches.
+// `--api-key`, `--base-url`, `--output` are infra. Path and query
+// params get added before body fields and take precedence.
+//
+// Note: `--body` is intentionally NOT reserved here. The naive
+// agent expectation (per AGX walkthrough) is that --body means
+// "the message body content," which collides with the JSON
+// escape-hatch meaning we used pre-0.12. The escape hatch is now
+// `--raw-body`; --body is free to be claimed by per-field flag
+// expansion as the kebab-cased version of a `body` schema field
+// (e.g. on a future `body: { ... }` schema). For send-mail today,
+// the body-text field is `body_text` -> `--body-text`, and there
+// is no top-level `body` field, so --body remains unclaimed at
+// the generated-command level. The agent shortcut `primitive
+// send` defines its own --body for the message text.
+const RESERVED_FLAG_NAMES = new Set([
+    "api-key",
+    "base-url",
+    "raw-body",
+    "body-file",
+    "output",
+]);
+function bodyFieldFlag(field) {
+    // Flag descriptions cap at 80 chars so oclif's --help output
+    // stays readable; the schema's full description is also visible
+    // via `primitive list-operations | jq`.
+    const descMax = 80;
+    const trimmedDesc = field.description.length > descMax
+        ? `${field.description.slice(0, descMax - 3)}...`
+        : field.description;
+    // Field-flag UX choice: do NOT mark scalar body fields as
+    // required at the oclif level even when the JSON Schema marks
+    // them required. Reason: a caller can satisfy the requirement
+    // either via the individual flag OR via --body / --body-file.
+    // Marking the flag required would force the individual-flag
+    // form. The runtime body merger validates the final assembled
+    // body against the same server-side schema either way.
+    const common = {
+        description: trimmedDesc || field.name,
+    };
+    if (field.kind === "boolean")
+        return Flags.boolean(common);
+    if (field.kind === "integer")
+        return Flags.integer(common);
+    if (field.enumValues) {
+        return Flags.string({ ...common, options: field.enumValues });
+    }
+    return Flags.string(common);
+}
 function buildFlags(operation) {
     const flags = {
         "api-key": Flags.string({
@@ -210,18 +306,67 @@ function buildFlags(operation) {
     for (const parameter of [...operation.pathParams, ...operation.queryParams]) {
         flags[flagName(parameter.name)] = flagForParameter(parameter);
     }
+    const bodyFieldFlagToProperty = new Map();
     if (operation.hasJsonBody) {
-        flags.body = Flags.string({ description: "JSON request body" });
+        flags["raw-body"] = Flags.string({
+            description: "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+        });
         flags["body-file"] = Flags.string({
-            description: "Path to a JSON file used as the request body",
+            description: "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
         });
+        // Expand top-level scalar body fields into individual flags so
+        // `primitive sending:send-email --to alice@x --from support@x
+        // --body-text "hi"` works without constructing JSON. Driven by
+        // the requestSchema embedded on the manifest. Skip flags that
+        // collide with reserved names or with path/query params already
+        // added above; those collisions fall back to --body.
+        //
+        // Collisions are tracked in the returned map so the run()
+        // handler doesn't misread a path/query param's value as a
+        // body-field override. (A naive "look up parsedFlags[name]"
+        // pass would happily pick up the path param's value and
+        // silently write it into the body.)
+        const bodyFields = extractBodyFields(operation.requestSchema);
+        for (const field of bodyFields) {
+            if (field.kind === "complex")
+                continue;
+            const name = flagName(field.name);
+            if (RESERVED_FLAG_NAMES.has(name))
+                continue;
+            if (flags[name] !== undefined)
+                continue;
+            flags[name] = bodyFieldFlag(field);
+            bodyFieldFlagToProperty.set(name, field.name);
+        }
     }
     if (operation.binaryResponse) {
         flags.output = Flags.string({
             description: "Write binary response bytes to a file",
         });
     }
-    return flags;
+    return { flags, bodyFieldFlagToProperty };
+}
+// Pull body field values out of the parsed CLI flags. Returns
+// only fields the user actually supplied (omits undefined). Used
+// to override / extend the JSON --body when both forms are
+// present (per-field flags take precedence on key conflicts).
+//
+// The `bodyFieldFlagToProperty` allowlist comes from buildFlags and
+// records ONLY the flags actually registered as body-field flags.
+// Without it, this function would naively read parsedFlags by
+// kebab-cased field name and pick up values from a colliding path
+// or query param flag, silently writing them into the body under
+// the body-field key. The allowlist keeps the merge honest: only
+// flags this CLI generator owns end up in the body.
+function collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty) {
+    const result = {};
+    for (const [flag, property] of bodyFieldFlagToProperty) {
+        const value = parsedFlags[flag];
+        if (value === undefined)
+            continue;
+        result[property] = value;
+    }
+    return result;
 }
 function collectValues(parameters, flags) {
     const values = {};
@@ -234,7 +379,7 @@ function collectValues(parameters, flags) {
     return values;
 }
 export function createOperationCommand(operation) {
-    const flags = buildFlags(operation);
+    const { flags, bodyFieldFlagToProperty } = buildFlags(operation);
     // Append a "Body fields" summary to the description so agents
     // running `<command> --help` learn the JSON shape immediately.
     // Without this, `--help` only said "JSON request body" and agents
@@ -262,11 +407,48 @@ export function createOperationCommand(operation) {
                     ? parsedFlags["base-url"]
                     : undefined,
             });
-            const body = operation.hasJsonBody
-                ? readJsonBody(parsedFlags)
-                : undefined;
+            // Two body sources, merged: explicit JSON via --body /
+            // --body-file (the base) plus per-field flags (the
+            // overrides). Per-field flag values take precedence on key
+            // conflicts so a caller can pass a base payload via --body
+            // and override one field on the command line.
+            let body;
+            if (operation.hasJsonBody) {
+                const explicit = readJsonBody(parsedFlags);
+                const overrides = collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty);
+                if (Object.keys(overrides).length > 0) {
+                    if (explicit === undefined) {
+                        body = overrides;
+                    }
+                    else if (explicit !== null &&
+                        typeof explicit === "object" &&
+                        !Array.isArray(explicit)) {
+                        body = { ...explicit, ...overrides };
+                    }
+                    else {
+                        // Caller passed --raw-body as null, an array, or a
+                        // primitive AND also passed per-field flags. We can't
+                        // merge per-field overrides into a non-object body
+                        // shape, and silently dropping either source would
+                        // leave the caller's actual intent unclear. Refuse
+                        // loudly so the next attempt is unambiguous.
+                        const explicitKind = explicit === null
+                            ? "null"
+                            : Array.isArray(explicit)
+                                ? "array"
+                                : typeof explicit;
+                        const overrideFlags = Object.keys(overrides)
+                            .map((p) => `--${flagName(p)}`)
+                            .join(", ");
+                        throw new Errors.CLIError(`--raw-body must be a JSON object when also passing per-field flags (got ${explicitKind}); supplied per-field flags: ${overrideFlags}. Either drop --raw-body and rely on the per-field flags, or move every field into the JSON --raw-body and drop the flags.`);
+                    }
+                }
+                else {
+                    body = explicit;
+                }
+            }
             if (operation.bodyRequired && body === undefined) {
-                throw new Errors.CLIError(`Operation ${operation.operationId} requires --body or --body-file`);
+                throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --raw-body / --body-file.`);
             }
             const operationFn = operations[operation.sdkName];
             const result = await operationFn({
@@ -299,8 +481,34 @@ export function createOperationCommand(operation) {
             if (cursor) {
                 process.stderr.write(`next cursor: ${cursor}\n`);
             }
+            // Empty-result hint. When a list-style operation returns
+            // an empty array, emit an operation-specific note to
+            // stderr so a naive caller can distinguish "nothing here"
+            // from "something isn't set up." Stdout still gets the
+            // raw `[]` so machine-readable output is unchanged. The
+            // AGX walkthrough flagged this: `list-deliveries` returning
+            // `[]` left the agent unsure whether they had an empty
+            // delivery log or no endpoints configured at all.
+            if (Array.isArray(envelope?.data) && envelope.data.length === 0) {
+                const hint = EMPTY_RESULT_HINTS[operation.sdkName];
+                if (hint)
+                    process.stderr.write(`${hint}\n`);
+            }
             this.log(JSON.stringify(envelope?.data ?? null, null, 2));
         }
     }
     return OperationCommand;
 }
+// Empty-state hints for list-style operations whose empty result
+// would otherwise leave the caller wondering "is this empty
+// because there's nothing to list, or because something earlier
+// in the setup chain isn't done?" Keys are the manifest's
+// `sdkName` for the operation. Operations without an entry fall
+// back to no hint (silent empty array, same as before).
+const EMPTY_RESULT_HINTS = {
+    listDeliveries: "(no results) Often means no webhook endpoints are configured to receive deliveries. Run `primitive endpoints:list-endpoints` to check.",
+    listEndpoints: "(no results) No webhook endpoints configured. Add one with `primitive endpoints:create-endpoint --url <your-url>`.",
+    listEmails: "(no results) No inbound emails received yet on this account.",
+    listDomains: "(no results) No domains on this account. Add one with `primitive domains:add-domain --domain <yourdomain.example>`.",
+    listFilters: "(no results) No filter rules configured.",
+};

package/dist/oclif/commands/send.js

@@ -0,0 +1,159 @@
+import { Command, Errors, Flags } from "@oclif/core";
+import { listDomains, sendEmail } from "../../api/generated/sdk.gen.js";
+import { PrimitiveApiClient } from "../../api/index.js";
+import { extractErrorPayload, formatErrorPayload } 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
+// express through manifest-driven flag generation alone:
+//
+//   1. `--from` defaults to `agent@<first-verified-domain>` when
+//      omitted. Most agents don't know which domains their org has
+//      verified for outbound; making them list-domains first to
+//      derive a from-address is exactly the kind of email-ops cruft
+//      this command exists to hide. Customers with multiple
+//      domains, or who want a different local-part, pass --from
+//      explicitly.
+//   2. `--subject` defaults to the first non-empty line of the body
+//      (capped). Empty subjects get spam-scored, so we always emit
+//      something. Callers who want full control pass --subject.
+//
+// `--body` here is the message body (text). The full `send-email`
+// operation distinguishes `body_text` and `body_html`; this
+// shortcut keeps it simple by exposing `--body` for text and
+// `--html` for the HTML alternative. Users who need both can pass
+// both flags or fall back to `sending:send-email` for the full
+// flag list.
+//
+// Compared to `swaks` (which agents likely have in their training
+// data): this is `swaks`-shaped on purpose so an agent
+// 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;
+function deriveSubject(body) {
+    for (const line of body.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        return trimmed.length > SUBJECT_MAX_LENGTH
+            ? `${trimmed.slice(0, SUBJECT_MAX_LENGTH - 3)}...`
+            : trimmed;
+    }
+    return "Message";
+}
+function isVerifiedDomain(domain) {
+    return domain.is_active === true;
+}
+async function pickDefaultFromAddress(apiClient) {
+    const result = await listDomains({
+        client: apiClient.client,
+        responseStyle: "fields",
+    });
+    if (result.error) {
+        const errorPayload = extractErrorPayload(result.error);
+        throw new Errors.CLIError(`Could not look up your verified domains to default --from. Pass --from explicitly. Underlying error: ${formatErrorPayload(errorPayload)}`);
+    }
+    const envelope = result.data;
+    const first = envelope?.data?.find(isVerifiedDomain);
+    if (!first) {
+        throw new Errors.CLIError("No active verified outbound domain found on this account; pass --from explicitly. To set up outbound, claim a domain via `primitive domains:add-domain` and verify it.");
+    }
+    // Local-part: "agent". Any local-part is accepted on managed
+    // *.primitive.email subdomains, so this works out of the box for
+    // the auto-issued domain pool. For customers with BYO domains
+    // and their own MX, "agent@" may or may not be a routable
+    // mailbox; if you have a specific address you want to use, pass
+    // --from explicitly.
+    return `agent@${first.domain}`;
+}
+class SendCommand extends Command {
+    static description = `Send an outbound email. Agent-grade shortcut for sending:send-email with sensible defaults.
+
+  --from defaults to agent@<your-first-verified-outbound-domain> when omitted.
+  --subject defaults to the first line of the body when omitted.
+
+  For the full flag set (custom message-id threading on the wire,
+  references arrays, etc.), use \`primitive sending:send-email\`.`;
+    static summary = "Send an email (simplified, agent-friendly)";
+    static examples = [
+        "<%= 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",
+    ];
+    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",
+        }),
+        to: Flags.string({
+            description: "Recipient address (e.g. alice@example.com).",
+            required: true,
+        }),
+        from: Flags.string({
+            description: "Sender address. Defaults to agent@<your-first-verified-outbound-domain>.",
+        }),
+        subject: Flags.string({
+            description: "Subject line. Defaults to the first line of --body / --html when omitted.",
+        }),
+        body: Flags.string({
+            description: "Plain-text message body. Either --body or --html (or both) is required.",
+        }),
+        html: Flags.string({
+            description: "HTML message body. Either --body or --html (or both) is required.",
+        }),
+        "in-reply-to": Flags.string({
+            description: "Message-Id of the parent email when threading a reply on the wire. For replying to an inbound message you received, prefer `primitive sending:reply-to-email --id <inbound-id>`.",
+        }),
+        wait: Flags.boolean({
+            description: "Block until the receiving MTA returns an outcome. Without --wait, the call returns once Primitive has accepted the message for delivery.",
+        }),
+        "wait-timeout-ms": Flags.integer({
+            description: "Maximum time to wait when --wait is set. Defaults to 30000ms.",
+        }),
+    };
+    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",
+        });
+        if (result.error) {
+            const errorPayload = extractErrorPayload(result.error);
+            process.stderr.write(`${formatErrorPayload(errorPayload)}\n`);
+            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

@@ -0,0 +1,68 @@
+import { Command, Errors, Flags } from "@oclif/core";
+import { getAccount } from "../../api/generated/sdk.gen.js";
+import { PrimitiveApiClient } from "../../api/index.js";
+import { extractErrorPayload, formatErrorPayload } 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
+// pointed at the org I expect" short of trying any other call and
+// reading a 401. That ambiguity bit two consecutive walkthroughs.
+//
+// Implementation: thin wrapper over /api/v1/account that prints
+// the account email, plan, id, and onboarding status. Any auth
+// problem surfaces as the standard error envelope, same as the
+// generated commands.
+class WhoamiCommand extends Command {
+    static description = `Print the account currently authenticated by the API key. Useful as a credentials smoke test: confirms the key is live and shows which account it belongs to.`;
+    static summary = "Print the authenticated account (credentials smoke test)";
+    static examples = [
+        "<%= config.bin %> whoami",
+        "<%= config.bin %> whoami --api-key prim_...",
+    ];
+    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",
+        }),
+    };
+    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",
+        });
+        if (result.error) {
+            const errorPayload = extractErrorPayload(result.error);
+            process.stderr.write(`${formatErrorPayload(errorPayload)}\n`);
+            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/oclif/index.js

@@ -1,6 +1,8 @@
 import { Args, Command } from "@oclif/core";
 import { operationManifest, } from "../openapi/index.js";
 import { createOperationCommand } from "./api-command.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";
@@ -38,5 +40,15 @@ const generatedCommands = Object.fromEntries(operationManifest.map((operation) =
 export const COMMANDS = {
     completion: CompletionCommand,
     "list-operations": ListOperationsCommand,
+    // `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
+    // who want every flag.
+    send: SendCommand,
+    // `whoami` is the credentials smoke test. Prints the account the
+    // current API key authenticates as. AGX walkthroughs kept
+    // wanting this before risking a real call against a possibly-
+    // bad key.
+    whoami: WhoamiCommand,
     ...generatedCommands,
 };

package/oclif.manifest.json

@@ -42,6 +42,136 @@
       "summary": "List all generated API operations",
       "enableJsonFlag": false
     },
+    "send": {
+      "aliases": [],
+      "args": {},
+      "description": "Send an outbound email. Agent-grade shortcut for sending:send-email with sensible defaults.\n\n  --from defaults to agent@<your-first-verified-outbound-domain> when omitted.\n  --subject defaults to the first line of the body when omitted.\n\n  For the full flag set (custom message-id threading on the wire,\n  references arrays, etc.), use `primitive sending:send-email`.",
+      "examples": [
+        "<%= 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"
+      ],
+      "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"
+        },
+        "to": {
+          "description": "Recipient address (e.g. alice@example.com).",
+          "name": "to",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "from": {
+          "description": "Sender address. Defaults to agent@<your-first-verified-outbound-domain>.",
+          "name": "from",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "subject": {
+          "description": "Subject line. Defaults to the first line of --body / --html when omitted.",
+          "name": "subject",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "body": {
+          "description": "Plain-text message body. Either --body or --html (or both) is required.",
+          "name": "body",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "html": {
+          "description": "HTML message body. Either --body or --html (or both) is required.",
+          "name": "html",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "in-reply-to": {
+          "description": "Message-Id of the parent email when threading a reply on the wire. For replying to an inbound message you received, prefer `primitive sending:reply-to-email --id <inbound-id>`.",
+          "name": "in-reply-to",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "Block until the receiving MTA returns an outcome. Without --wait, the call returns once Primitive has accepted the message for delivery.",
+          "name": "wait",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "wait-timeout-ms": {
+          "description": "Maximum time to wait when --wait is set. Defaults to 30000ms.",
+          "name": "wait-timeout-ms",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "send",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Send an email (simplified, agent-friendly)",
+      "enableJsonFlag": false
+    },
+    "whoami": {
+      "aliases": [],
+      "args": {},
+      "description": "Print the account currently authenticated by the API key. Useful as a credentials smoke test: confirms the key is live and shows which account it belongs to.",
+      "examples": [
+        "<%= config.bin %> whoami",
+        "<%= config.bin %> whoami --api-key prim_..."
+      ],
+      "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"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "whoami",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Print the authenticated account (credentials smoke test)",
+      "enableJsonFlag": false
+    },
     "account:get-account": {
       "aliases": [],
       "args": {},
@@ -173,7 +303,7 @@
     "account:update-account": {
       "aliases": [],
       "args": {},
-      "description": "PATCH /account\n\nBody fields (JSON --body):\n   discard_content_on_webhook_confirmed  boolean  Whether to discard email content after the webhook endpoint confirms receipt.\n   spam_threshold            number?  Global spam score threshold (0-15). Emails scoring above this are rejected....\n(* = required)",
+      "description": "PATCH /account",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -191,19 +321,32 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "JSON request body",
-          "name": "body",
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a JSON file used as the request body",
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "discard-content-on-webhook-confirmed": {
+          "description": "Whether to discard email content after the webhook endpoint confirms receipt.",
+          "name": "discard-content-on-webhook-confirmed",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "spam-threshold": {
+          "description": "Global spam score threshold (0-15). Emails scoring above this are rejected. S...",
+          "name": "spam-threshold",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -219,7 +362,7 @@
     "domains:add-domain": {
       "aliases": [],
       "args": {},
-      "description": "Creates an unverified domain claim. You will receive a\n`verification_token` to add as a DNS TXT record before\ncalling the verify endpoint.\n\n\nBody fields (JSON --body):\n * domain  string  The domain name to claim (e.g. \"example.com\")\n(* = required)",
+      "description": "Creates an unverified domain claim. You will receive a\n`verification_token` to add as a DNS TXT record before\ncalling the verify endpoint.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -237,19 +380,26 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "JSON request body",
-          "name": "body",
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a JSON file used as the request body",
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "domain": {
+          "description": "The domain name to claim (e.g. \"example.com\")",
+          "name": "domain",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -337,7 +487,7 @@
     "domains:update-domain": {
       "aliases": [],
       "args": {},
-      "description": "Update a verified domain's settings. Only verified domains can be\nupdated. Per-domain spam thresholds require a Pro plan.\n\n\nBody fields (JSON --body):\n   is_active       boolean  Whether the domain accepts incoming emails\n   spam_threshold  number?  Per-domain spam threshold override (Pro plan required)\n(* = required)",
+      "description": "Update a verified domain's settings. Only verified domains can be\nupdated. Per-domain spam thresholds require a Pro plan.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -363,19 +513,32 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "JSON request body",
-          "name": "body",
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a JSON file used as the request body",
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "is-active": {
+          "description": "Whether the domain accepts incoming emails",
+          "name": "is-active",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "spam-threshold": {
+          "description": "Per-domain spam threshold override (Pro plan required)",
+          "name": "spam-threshold",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -755,7 +918,7 @@
     "endpoints:create-endpoint": {
       "aliases": [],
       "args": {},
-      "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\n\nBody fields (JSON --body):\n * url        string  The webhook URL to deliver events to\n   domain_id  string?  Restrict to emails from a specific domain\n   enabled    boolean  Whether the endpoint is active\n   rules      object  Endpoint-specific filtering rules\n(* = required)",
+      "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\n\nBody fields requiring --raw-body JSON (these are not exposed as flags):\n   rules  object  Endpoint-specific filtering rules\n(* = required. Scalar body fields are exposed as individual --flag-name flags; see FLAGS above.)",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -773,19 +936,39 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "JSON request body",
-          "name": "body",
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a JSON file used as the request body",
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "url": {
+          "description": "The webhook URL to deliver events to",
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "domain-id": {
+          "description": "Restrict to emails from a specific domain",
+          "name": "domain-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "enabled": {
+          "description": "Whether the endpoint is active",
+          "name": "enabled",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -913,7 +1096,7 @@
     "endpoints:update-endpoint": {
       "aliases": [],
       "args": {},
-      "description": "Updates an active webhook endpoint. If the URL is changed, the old\nendpoint is deactivated and a new one is created (or an existing\ndeactivated endpoint with the new URL is reactivated).\n\n\nBody fields (JSON --body):\n   domain_id  string?\n   enabled    boolean\n   rules      object\n   url        string  New webhook URL (triggers endpoint rotation)\n(* = required)",
+      "description": "Updates an active webhook endpoint. If the URL is changed, the old\nendpoint is deactivated and a new one is created (or an existing\ndeactivated endpoint with the new URL is reactivated).\n\n\nBody fields requiring --raw-body JSON (these are not exposed as flags):\n   rules  object\n(* = required. Scalar body fields are exposed as individual --flag-name flags; see FLAGS above.)",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -939,19 +1122,39 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "JSON request body",
-          "name": "body",
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a JSON file used as the request body",
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "domain-id": {
+          "description": "domain_id",
+          "name": "domain-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "enabled": {
+          "description": "enabled",
+          "name": "enabled",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "url": {
+          "description": "New webhook URL (triggers endpoint rotation)",
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -967,7 +1170,7 @@
     "filters:create-filter": {
       "aliases": [],
       "args": {},
-      "description": "Creates a new whitelist or blocklist filter. Per-domain filters\nrequire a Pro plan. Patterns are stored as lowercase.\n\n\nBody fields (JSON --body):\n * pattern    string  Email address or pattern to filter\n * type       string\n   domain_id  string?  Restrict filter to a specific domain (Pro plan required)\n(* = required)",
+      "description": "Creates a new whitelist or blocklist filter. Per-domain filters\nrequire a Pro plan. Patterns are stored as lowercase.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -985,19 +1188,44 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "JSON request body",
-          "name": "body",
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a JSON file used as the request body",
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "pattern": {
+          "description": "Email address or pattern to filter",
+          "name": "pattern",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "type": {
+          "description": "type",
+          "name": "type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "whitelist",
+            "blocklist"
+          ],
+          "type": "option"
+        },
+        "domain-id": {
+          "description": "Restrict filter to a specific domain (Pro plan required)",
+          "name": "domain-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -1085,7 +1313,7 @@
     "filters:update-filter": {
       "aliases": [],
       "args": {},
-      "description": "Toggle a filter's enabled state.\n\nBody fields (JSON --body):\n * enabled  boolean\n(* = required)",
+      "description": "Toggle a filter's enabled state.",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -1111,19 +1339,25 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "JSON request body",
-          "name": "body",
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a JSON file used as the request body",
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "enabled": {
+          "description": "enabled",
+          "name": "enabled",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -1139,7 +1373,7 @@
     "sending:reply-to-email": {
       "aliases": [],
       "args": {},
-      "description": "Sends an outbound reply to the inbound email identified by `id`.\nThreading headers (`In-Reply-To`, `References`), recipient\nderivation (Reply-To, then From, then bare sender), and the\n`Re:` subject prefix are all derived server-side from the\nstored inbound row. The request body carries only the message\nbody and optional `wait` flag; passing any header or recipient\noverride is rejected by the schema (`additionalProperties:\nfalse`).\n\nForwards through the same gates as `/send-mail`: the response\nstatus, error envelope, and `idempotent_replay` flag mirror\nthe send-mail contract verbatim.\n\n\nBody fields (JSON --body):\n   body_html  string  HTML reply body. At least one of body_text or body_html is required.\n   body_text  string  Plain-text reply body. At least one of body_text or body_html is required. ...\n   from       string  Optional override for the reply's From header. Defaults to\n   wait       boolean  When true, wait for the first downstream SMTP delivery outcome before retur...\n(* = required)",
+      "description": "Sends an outbound reply to the inbound email identified by `id`.\nThreading headers (`In-Reply-To`, `References`), recipient\nderivation (Reply-To, then From, then bare sender), and the\n`Re:` subject prefix are all derived server-side from the\nstored inbound row. The request body carries only the message\nbody and optional `wait` flag; passing any header or recipient\noverride is rejected by the schema (`additionalProperties:\nfalse`).\n\nForwards through the same gates as `/send-mail`: the response\nstatus, error envelope, and `idempotent_replay` flag mirror\nthe send-mail contract verbatim.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -1165,19 +1399,46 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "JSON request body",
-          "name": "body",
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a JSON file used as the request body",
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "body-html": {
+          "description": "HTML reply body. At least one of body_text or body_html is required.",
+          "name": "body-html",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "body-text": {
+          "description": "Plain-text reply body. At least one of body_text or body_html is required. Th...",
+          "name": "body-text",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "from": {
+          "description": "Optional override for the reply's From header. Defaults to",
+          "name": "from",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "When true, wait for the first downstream SMTP delivery outcome before returni...",
+          "name": "wait",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -1193,7 +1454,7 @@
     "sending:send-email": {
       "aliases": [],
       "args": {},
-      "description": "Sends an outbound email through Primitive's outbound relay. By default\nthe request returns once the relay accepts the message for delivery.\nSet `wait: true` to wait for the first downstream SMTP delivery outcome.\n\n\nBody fields (JSON --body):\n * from             string  RFC 5322 From header. The sender domain must be a verified outbound domain ...\n * subject          string  Subject line for the outbound message\n * to               string  Recipient address. Recipient eligibility depends on your account's outbound...\n   body_html        string  HTML message body. At least one of body_text or body_html is required. The ...\n   body_text        string  Plain-text message body. At least one of body_text or body_html is required...\n   in_reply_to      string  Message-ID of the direct parent email when sending a threaded reply.\n   references       array<string>  Full ordered message-id chain for the thread.\n   wait             boolean  When true, wait for the first downstream SMTP delivery outcome before retur...\n   wait_timeout_ms  integer  Maximum time to wait for a delivery outcome when wait is true. Defaults to ...\n(* = required)",
+      "description": "Sends an outbound email through Primitive's outbound relay. By default\nthe request returns once the relay accepts the message for delivery.\nSet `wait: true` to wait for the first downstream SMTP delivery outcome.\n\n\nBody fields requiring --raw-body JSON (these are not exposed as flags):\n   references  array<string>  Full ordered message-id chain for the thread.\n(* = required. Scalar body fields are exposed as individual --flag-name flags; see FLAGS above.)",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -1211,19 +1472,74 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "JSON request body",
-          "name": "body",
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a JSON file used as the request body",
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "from": {
+          "description": "RFC 5322 From header. The sender domain must be a verified outbound domain fo...",
+          "name": "from",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "subject": {
+          "description": "Subject line for the outbound message",
+          "name": "subject",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "to": {
+          "description": "Recipient address. Recipient eligibility depends on your account's outbound e...",
+          "name": "to",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "body-html": {
+          "description": "HTML message body. At least one of body_text or body_html is required. The co...",
+          "name": "body-html",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "body-text": {
+          "description": "Plain-text message body. At least one of body_text or body_html is required. ...",
+          "name": "body-text",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "in-reply-to": {
+          "description": "Message-ID of the direct parent email when sending a threaded reply.",
+          "name": "in-reply-to",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "When true, wait for the first downstream SMTP delivery outcome before returning.",
+          "name": "wait",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "wait-timeout-ms": {
+          "description": "Maximum time to wait for a delivery outcome when wait is true. Defaults to 30...",
+          "name": "wait-timeout-ms",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -1363,5 +1679,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.10.0"
+  "version": "0.12.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Official Primitive Node.js SDK — webhook, api, openapi, contract, and parser modules",
   "type": "module",
   "module": "./dist/index.js",