@primitivedotdev/sdk 0.21.0 → 0.22.0

package/dist/oclif/api-command.js

@@ -571,6 +571,25 @@ function collectValues(parameters, flags) {
     }
     return values;
 }
+// Discoverability hints for generated commands that have a
+// hand-rolled ergonomic shortcut. Keyed by the manifest's
+// `sdkName` (camelCase, matches the generated SDK function). The
+// hint is appended to the operation's --help description so an
+// agent reading `<command> --help` finds the shortcut without
+// having to enumerate the full command list. AGX walkthrough:
+// an agent reached for `functions:update-function` to redeploy
+// (which forces a JSON-stringified `code` body) when
+// `functions:redeploy --file <bundle>` was the intended path.
+//
+// Add an entry here whenever a hand-rolled shortcut shadows a
+// generated operation; the COMMANDS map in `index.ts` is the
+// authoritative list of shortcuts.
+export const OPERATION_HINTS = {
+    createFunction: "Tip: prefer `primitive functions:deploy --name <name> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
+    updateFunction: "Tip: prefer `primitive functions:redeploy --id <id> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
+    createFunctionSecret: "Tip: prefer `primitive functions:set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
+    setFunctionSecret: "Tip: prefer `primitive functions:set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
+};
 export function createOperationCommand(operation) {
     const { flags, bodyFieldFlagToProperty } = buildFlags(operation);
     // Append a "Body fields" summary to the description so agents
@@ -582,9 +601,13 @@ export function createOperationCommand(operation) {
     const schemaSummary = operation.hasJsonBody
         ? renderRequestSchemaSummary(operation.requestSchema)
         : null;
-    const fullDescription = schemaSummary
+    const hint = OPERATION_HINTS[operation.sdkName];
+    const descriptionWithSchema = schemaSummary
         ? `${baseDescription}\n\n${schemaSummary}`
         : baseDescription;
+    const fullDescription = hint
+        ? `${descriptionWithSchema}\n\n${hint}`
+        : descriptionWithSchema;
     class OperationCommand extends Command {
         static description = fullDescription;
         static flags = flags;

package/dist/oclif/commands/functions-set-secret.js

@@ -0,0 +1,213 @@
+import { Command, Flags } from "@oclif/core";
+import { getFunction, setFunctionSecret, updateFunction, } from "../../api/generated/sdk.gen.js";
+import { PrimitiveApiClient } from "../../api/index.js";
+import { extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+// Pure-ish orchestration of the set-secret + optional redeploy
+// flow. Pulled out as a named export so the unit test can drive
+// both the happy path and each error stage with a fake API
+// surface, without spinning up a real client or the oclif
+// command lifecycle.
+//
+// The redeploy step uses the function's CURRENT code (fetched via
+// getFunction) as the new bundle. This is the documented way to
+// "refresh secret bindings without changing the handler": the
+// server-side deploy reads the secrets table fresh on every call,
+// so re-deploying the same code picks up the secret we just wrote.
+export async function runSetSecret(api, params) {
+    const setResult = await api.setSecret({
+        id: params.id,
+        key: params.key,
+        value: params.value,
+    });
+    if (setResult.error) {
+        return {
+            kind: "error",
+            payload: extractErrorPayload(setResult.error),
+            stage: "set-secret",
+        };
+    }
+    const secret = setResult.data?.data;
+    if (!secret) {
+        // Server returned 2xx with no `data` body. Treat as an error
+        // so we don't fabricate a success payload; this should not
+        // happen in practice but the shape forces us to handle it.
+        return {
+            kind: "error",
+            payload: {
+                code: "client_error",
+                message: "Secret write returned no data",
+            },
+            stage: "set-secret",
+        };
+    }
+    if (!params.redeploy) {
+        return { kind: "ok", result: { secret } };
+    }
+    const fnResult = await api.getFunction({ id: params.id });
+    if (fnResult.error) {
+        return {
+            kind: "error",
+            payload: extractErrorPayload(fnResult.error),
+            stage: "get-function",
+        };
+    }
+    const fn = fnResult.data?.data;
+    if (!fn) {
+        return {
+            kind: "error",
+            payload: {
+                code: "client_error",
+                message: "Could not read current function code for redeploy",
+            },
+            stage: "get-function",
+        };
+    }
+    const updateResult = await api.updateFunction({
+        code: fn.code,
+        id: params.id,
+    });
+    if (updateResult.error) {
+        return {
+            kind: "error",
+            payload: extractErrorPayload(updateResult.error),
+            stage: "redeploy",
+        };
+    }
+    const redeployed = updateResult.data?.data;
+    if (!redeployed) {
+        return {
+            kind: "error",
+            payload: {
+                code: "client_error",
+                message: "Redeploy returned no data",
+            },
+            stage: "redeploy",
+        };
+    }
+    return { kind: "ok", result: { redeploy: redeployed, secret } };
+}
+class FunctionsSetSecretCommand extends Command {
+    static description = `Write a function secret and optionally redeploy so the new value lands in the running handler. Agent-grade shortcut for functions:set-function-secret + functions:redeploy.
+
+  Without --redeploy this is a plain secret upsert: the value is
+  encrypted at rest but is NOT visible to the running handler until
+  the next deploy. Pass --redeploy to re-run the deploy with the
+  function's current code in the same call, which refreshes the
+  binding set with the value you just wrote.
+
+  Keys must match \`^[A-Z_][A-Z0-9_]*$\` (uppercase letters, digits,
+  underscores; first character is a letter or underscore). System-
+  managed keys are reserved and rejected.`;
+    static summary = "Write a function secret (optionally redeploying to push it live)";
+    static examples = [
+        "<%= config.bin %> functions:set-secret --id <fn-id> --key API_TOKEN --value abc123",
+        "<%= config.bin %> functions:set-secret --id <fn-id> --key API_TOKEN --value abc123 --redeploy",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "api-base-url-1": Flags.string({
+            description: "Override the primary API base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "api-base-url-2": Flags.string({
+            description: "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_2",
+            hidden: true,
+        }),
+        id: Flags.string({
+            description: "Function id (UUID). The function must already exist.",
+            required: true,
+        }),
+        key: Flags.string({
+            description: "Secret key. Uppercase letters, digits, underscores; must start with a letter or underscore. System-managed keys are reserved.",
+            required: true,
+        }),
+        value: Flags.string({
+            description: "Secret value (up to 4096 UTF-8 bytes). Encrypted at rest.",
+            required: true,
+        }),
+        redeploy: Flags.boolean({
+            description: "Also redeploy the function with its current code so the new value lands in the running handler. Without this, the secret is written but not visible to the handler until the next deploy. Note: source maps are stored only on the runtime side and getFunction does not return them, so this redeploy drops any previously-uploaded source map. If preserving stack-trace symbolication matters, use `functions:redeploy --file <bundle.js> --source-map-file <bundle.js.map>` instead.",
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FunctionsSetSecretCommand);
+        await runWithTiming(flags.time, async () => {
+            const baseUrlOverridden = flags["api-base-url-1"] !== undefined ||
+                flags["api-base-url-2"] !== undefined;
+            const auth = resolveCliAuth({
+                apiKey: flags["api-key"],
+                apiBaseUrl1: flags["api-base-url-1"],
+                apiBaseUrl2: flags["api-base-url-2"],
+                configDir: this.config.configDir,
+            });
+            const apiClient = new PrimitiveApiClient({
+                apiKey: auth.apiKey,
+                apiBaseUrl1: auth.apiBaseUrl1,
+                apiBaseUrl2: auth.apiBaseUrl2,
+            });
+            const authFailureContext = {
+                auth,
+                baseUrlOverridden,
+                configDir: this.config.configDir,
+            };
+            // Adapter: thin wrappers around the generated SDK calls,
+            // routed through host 1 (apiClient.client). The secrets and
+            // function-detail endpoints are not on host 2.
+            const apiSurface = {
+                getFunction: (p) => getFunction({
+                    client: apiClient.client,
+                    path: { id: p.id },
+                    responseStyle: "fields",
+                }),
+                setSecret: (p) => setFunctionSecret({
+                    body: { value: p.value },
+                    client: apiClient.client,
+                    path: { id: p.id, key: p.key },
+                    responseStyle: "fields",
+                }),
+                updateFunction: (p) => updateFunction({
+                    body: { code: p.code },
+                    client: apiClient.client,
+                    path: { id: p.id },
+                    responseStyle: "fields",
+                }),
+            };
+            const outcome = await runSetSecret(apiSurface, {
+                id: flags.id,
+                key: flags.key,
+                redeploy: flags.redeploy === true,
+                value: flags.value,
+            });
+            if (outcome.kind === "error") {
+                // Stage-specific framing on stderr so callers can tell
+                // whether the secret landed before a failed redeploy. The
+                // JSON envelope still goes through writeErrorWithHints so
+                // any actionable hint (e.g. unauthorized) is surfaced.
+                if (outcome.stage === "get-function") {
+                    process.stderr.write("Secret was written, but reading current function code for redeploy failed; the secret is NOT yet live. Re-run with --redeploy, or call `primitive functions:redeploy --id <id> --file <bundle>` once you have the bundle.\n");
+                }
+                else if (outcome.stage === "redeploy") {
+                    process.stderr.write("Secret was written, but the redeploy step failed; the secret is NOT yet live. Inspect the function's deploy_error and re-run `primitive functions:redeploy --id <id> --file <bundle>` once the cause is fixed.\n");
+                }
+                writeErrorWithHints(outcome.payload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    ...authFailureContext,
+                    payload: outcome.payload,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            this.log(JSON.stringify(outcome.result, null, 2));
+        });
+    }
+}
+export default FunctionsSetSecretCommand;

package/dist/oclif/index.js

@@ -6,6 +6,7 @@ import EmailsWaitCommand from "./commands/emails-wait.js";
 import EmailsWatchCommand from "./commands/emails-watch.js";
 import FunctionsDeployCommand from "./commands/functions-deploy.js";
 import FunctionsRedeployCommand from "./commands/functions-redeploy.js";
+import FunctionsSetSecretCommand from "./commands/functions-set-secret.js";
 import LoginCommand from "./commands/login.js";
 import LogoutCommand from "./commands/logout.js";
 import SendCommand from "./commands/send.js";
@@ -147,5 +148,12 @@ export const COMMANDS = {
     // available for callers that want the full surface.
     "functions:deploy": FunctionsDeployCommand,
     "functions:redeploy": FunctionsRedeployCommand,
+    // `functions:set-secret` is the one-call shortcut for "write a
+    // secret AND (optionally) push it live." The raw
+    // functions:set-function-secret / functions:create-function-secret
+    // operations only do the secret upsert; making the new value
+    // visible to the running handler requires a separate redeploy,
+    // which this shortcut folds in via --redeploy.
+    "functions:set-secret": FunctionsSetSecretCommand,
     ...generatedCommands,
 };

package/oclif.manifest.json

@@ -859,6 +859,88 @@
       "summary": "Redeploy a function from a bundled handler file",
       "enableJsonFlag": false
     },
+    "functions:set-secret": {
+      "aliases": [],
+      "args": {},
+      "description": "Write a function secret and optionally redeploy so the new value lands in the running handler. Agent-grade shortcut for functions:set-function-secret + functions:redeploy.\n\n  Without --redeploy this is a plain secret upsert: the value is\n  encrypted at rest but is NOT visible to the running handler until\n  the next deploy. Pass --redeploy to re-run the deploy with the\n  function's current code in the same call, which refreshes the\n  binding set with the value you just wrote.\n\n  Keys must match `^[A-Z_][A-Z0-9_]*$` (uppercase letters, digits,\n  underscores; first character is a letter or underscore). System-\n  managed keys are reserved and rejected.",
+      "examples": [
+        "<%= config.bin %> functions:set-secret --id <fn-id> --key API_TOKEN --value abc123",
+        "<%= config.bin %> functions:set-secret --id <fn-id> --key API_TOKEN --value abc123 --redeploy"
+      ],
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-base-url-1": {
+          "description": "Override the primary API base URL. Internal testing only; not documented to customers.",
+          "env": "PRIMITIVE_API_BASE_URL_1",
+          "hidden": true,
+          "name": "api-base-url-1",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-base-url-2": {
+          "description": "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+          "env": "PRIMITIVE_API_BASE_URL_2",
+          "hidden": true,
+          "name": "api-base-url-2",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "id": {
+          "description": "Function id (UUID). The function must already exist.",
+          "name": "id",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "key": {
+          "description": "Secret key. Uppercase letters, digits, underscores; must start with a letter or underscore. System-managed keys are reserved.",
+          "name": "key",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "value": {
+          "description": "Secret value (up to 4096 UTF-8 bytes). Encrypted at rest.",
+          "name": "value",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "redeploy": {
+          "description": "Also redeploy the function with its current code so the new value lands in the running handler. Without this, the secret is written but not visible to the handler until the next deploy. Note: source maps are stored only on the runtime side and getFunction does not return them, so this redeploy drops any previously-uploaded source map. If preserving stack-trace symbolication matters, use `functions:redeploy --file <bundle.js> --source-map-file <bundle.js.map>` instead.",
+          "name": "redeploy",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "functions:set-secret",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Write a function secret (optionally redeploying to push it live)",
+      "enableJsonFlag": false
+    },
     "account:get-account": {
       "aliases": [],
       "args": {},
@@ -2918,7 +3000,7 @@
     "functions:create-function": {
       "aliases": [],
       "args": {},
-      "description": "Creates and deploys a new function. The handler must be a single\nESM module that exports a default async function receiving the\n`email.received` event (see the Webhook payload section for the\nfull schema). Code is bundled before being uploaded; ship a\nsingle self-contained file rather than relying on external\nimports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8 and is stored only on the\nedge runtime side; it is not persisted in Primitive's database.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the gateway URL returned here is for\nreference only and is not directly callable from outside.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`) already\nbound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
+      "description": "Creates and deploys a new function. The handler must be a single\nESM module that exports a default async function receiving the\n`email.received` event (see the Webhook payload section for the\nfull schema). Code is bundled before being uploaded; ship a\nsingle self-contained file rather than relying on external\nimports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8 and is stored only on the\nedge runtime side; it is not persisted in Primitive's database.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the gateway URL returned here is for\nreference only and is not directly callable from outside.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`) already\nbound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n\n\nTip: prefer `primitive functions:deploy --name <name> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -3001,7 +3083,7 @@
     "functions:create-function-secret": {
       "aliases": [],
       "args": {},
-      "description": "Idempotent insert-or-update keyed on `(function_id, key)`.\nReturns 201 the first time the key is set, 200 on subsequent\nupdates. Values are encrypted at rest and only become visible\nto the running handler on the next deploy (`PUT /functions/{id}`\nwith the existing code is sufficient to refresh bindings).\n\nKeys must match `^[A-Z_][A-Z0-9_]*$` (uppercase letters,\ndigits, underscores; first character is a letter or\nunderscore). Values are at most 4096 UTF-8 bytes. System-\nmanaged keys are reserved and rejected.\n",
+      "description": "Idempotent insert-or-update keyed on `(function_id, key)`.\nReturns 201 the first time the key is set, 200 on subsequent\nupdates. Values are encrypted at rest and only become visible\nto the running handler on the next deploy (`PUT /functions/{id}`\nwith the existing code is sufficient to refresh bindings).\n\nKeys must match `^[A-Z_][A-Z0-9_]*$` (uppercase letters,\ndigits, underscores; first character is a letter or\nunderscore). Values are at most 4096 UTF-8 bytes. System-\nmanaged keys are reserved and rejected.\n\n\nTip: prefer `primitive functions:set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -3365,7 +3447,7 @@
     "functions:set-function-secret": {
       "aliases": [],
       "args": {},
-      "description": "Path-keyed companion to `POST /functions/{id}/secrets`.\nIdempotent: returns 201 the first time the key is set, 200 on\nsubsequent updates. Same validation rules and same write-only\nguarantees as the POST verb; the new value lands in the running\nhandler on the next deploy.\n",
+      "description": "Path-keyed companion to `POST /functions/{id}/secrets`.\nIdempotent: returns 201 the first time the key is set, 200 on\nsubsequent updates. Same validation rules and same write-only\nguarantees as the POST verb; the new value lands in the running\nhandler on the next deploy.\n\n\nTip: prefer `primitive functions:set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -3506,7 +3588,7 @@
     "functions:update-function": {
       "aliases": [],
       "args": {},
-      "description": "Replaces the function's source code with the body's `code` and\ntriggers a redeploy. Same size limits as `POST /functions`.\nUse this verb to push secret writes into the running handler:\npassing the same `code` re-runs the deploy and refreshes the\nbinding set with the latest values from the secrets table.\n\nOn a 502 deploy failure, the previously-deployed code stays\nlive; the runtime never serves a half-built bundle. The\n`deploy_error` field on the returned record carries the error\nthat came back from the runtime so you can surface it to users\nwithout polling.\n",
+      "description": "Replaces the function's source code with the body's `code` and\ntriggers a redeploy. Same size limits as `POST /functions`.\nUse this verb to push secret writes into the running handler:\npassing the same `code` re-runs the deploy and refreshes the\nbinding set with the latest values from the secrets table.\n\nOn a 502 deploy failure, the previously-deployed code stays\nlive; the runtime never serves a half-built bundle. The\n`deploy_error` field on the returned record carries the error\nthat came back from the runtime so you can surface it to users\nwithout polling.\n\n\nTip: prefer `primitive functions:redeploy --id <id> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -4168,5 +4250,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.21.0"
+  "version": "0.22.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser modules",
   "type": "module",
   "module": "./dist/index.js",
@@ -84,7 +84,7 @@
         "description": "View and replay webhook delivery attempts"
       },
       "functions": {
-        "description": "Deploy JavaScript handlers that run on inbound mail. Use `primitive functions:deploy --name <name> --file <bundle.js>` for the file-input ergonomic, or `functions:create-function` / `functions:update-function` for the full body-string surface."
+        "description": "Deploy JavaScript handlers that run on inbound mail. Use `primitive functions:deploy --name <name> --file <bundle.js>` to create, `primitive functions:redeploy --id <id> --file <bundle.js>` to push a new bundle, and `primitive functions:set-secret --id <id> --key <KEY> --value <value> [--redeploy]` to write a secret (with optional one-call redeploy so the value lands in the running handler). The auto-generated functions:create-function / functions:update-function / functions:create-function-secret / functions:set-function-secret operations stay available for the full body-string surface."
       }
     },
     "topicSeparator": " "