@primitivedotdev/sdk 0.11.0 → 0.12.0

package/dist/oclif/api-command.js

@@ -95,15 +95,15 @@ function extractBodyFields(schema) {
  * 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 `--body` (complex types: arrays, objects,
+ * 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; --body for the
- * leftovers below."
+ * the natural reading is "use the flags above; --raw-body for
+ * the leftovers below."
  */
 function renderRequestSchemaSummary(schema) {
     const fields = extractBodyFields(schema);
@@ -115,7 +115,7 @@ function renderRequestSchemaSummary(schema) {
     const nameWidth = Math.min(24, Math.max(...complex.map((f) => f.name.length)));
     const descMax = 78;
     const lines = [
-        "Body fields requiring --body JSON (these are not exposed as flags):",
+        "Body fields requiring --raw-body JSON (these are not exposed as flags):",
     ];
     for (const f of complex) {
         const marker = f.required ? " *" : "  ";
@@ -180,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;
@@ -195,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;
 }
@@ -243,13 +243,25 @@ export function formatErrorPayload(payload) {
     return JSON.stringify(payload, null, 2);
 }
 // Reserved flag names the body-field expander must never overwrite.
-// `--body` and `--body-file` are the JSON escape hatches.
+// `--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",
-    "body",
+    "raw-body",
     "body-file",
     "output",
 ]);
@@ -296,11 +308,11 @@ function buildFlags(operation) {
     }
     const bodyFieldFlagToProperty = new Map();
     if (operation.hasJsonBody) {
-        flags.body = Flags.string({
-            description: "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
+        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. Same role as --body for callers passing a saved payload.",
+            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
@@ -414,7 +426,7 @@ export function createOperationCommand(operation) {
                         body = { ...explicit, ...overrides };
                     }
                     else {
-                        // Caller passed --body as null, an array, or a
+                        // 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
@@ -428,7 +440,7 @@ export function createOperationCommand(operation) {
                         const overrideFlags = Object.keys(overrides)
                             .map((p) => `--${flagName(p)}`)
                             .join(", ");
-                        throw new Errors.CLIError(`--body must be a JSON object when also passing per-field flags (got ${explicitKind}); supplied per-field flags: ${overrideFlags}. Either drop --body and rely on the per-field flags, or move every field into the JSON --body and drop the flags.`);
+                        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 {
@@ -436,7 +448,7 @@ export function createOperationCommand(operation) {
                 }
             }
             if (operation.bodyRequired && body === undefined) {
-                throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --body / --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({
@@ -469,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/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

@@ -2,6 +2,7 @@ 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";
@@ -44,5 +45,10 @@ export const COMMANDS = {
     // 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

@@ -136,6 +136,42 @@
       "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": {},
@@ -285,15 +321,15 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
-          "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. Same role as --body for callers passing a saved payload.",
+          "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,
@@ -344,15 +380,15 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
-          "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. Same role as --body for callers passing a saved payload.",
+          "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,
@@ -477,15 +513,15 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
-          "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. Same role as --body for callers passing a saved payload.",
+          "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,
@@ -882,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 requiring --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.)",
+      "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)",
@@ -900,15 +936,15 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
-          "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. Same role as --body for callers passing a saved payload.",
+          "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,
@@ -1060,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 requiring --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.)",
+      "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)",
@@ -1086,15 +1122,15 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
-          "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. Same role as --body for callers passing a saved payload.",
+          "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,
@@ -1152,15 +1188,15 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
-          "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. Same role as --body for callers passing a saved payload.",
+          "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,
@@ -1303,15 +1339,15 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
-          "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. Same role as --body for callers passing a saved payload.",
+          "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,
@@ -1363,15 +1399,15 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
-          "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. Same role as --body for callers passing a saved payload.",
+          "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,
@@ -1418,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 requiring --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.)",
+      "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)",
@@ -1436,15 +1472,15 @@
           "multiple": false,
           "type": "option"
         },
-        "body": {
-          "description": "Full request body as JSON. Prefer per-field flags (e.g. --to, --from, --body-text) when available; --body is the escape hatch for nested or complex fields.",
-          "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. Same role as --body for callers passing a saved payload.",
+          "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,
@@ -1643,5 +1679,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.11.0"
+  "version": "0.12.0"
 }

package/package.json

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