@primitivedotdev/sdk 0.21.0 → 0.23.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-init.js

@@ -0,0 +1,256 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { Args, Command, Errors, Flags } from "@oclif/core";
+// `primitive functions:init <name>` stamps a deployable Function project
+// into ./<name>/ so a new author can go from zero to a deployed handler
+// in two commands: `npm install && npm run build` then
+// `primitive functions:deploy --name <name> --file ./dist/handler.js`.
+//
+// The scaffolded handler imports `createPrimitiveClient` from
+// `@primitivedotdev/sdk/api`, NOT from the package root. The root export
+// pulls in webhook helpers that depend on `node:crypto`, which breaks
+// Workers-style bundles. The `/api` subpath is the runtime-client
+// surface and is the documented import for in-handler use.
+// The SDK version range that ships in the scaffolded package.json's
+// dependencies. Pinned to the current shipped minor with a caret so
+// patch releases of the SDK pick up automatically. Update alongside
+// any major version bump of the SDK.
+const SDK_VERSION_RANGE = "^0.22.0";
+// esbuild version range. Pinned to the latest stable major used
+// elsewhere in the Primitive codebase for bundling Workers-style
+// handlers. Caret range so patch fixes flow in automatically.
+const ESBUILD_VERSION_RANGE = "^0.27.0";
+// Validate a directory name passed as the positional argument.
+// Matches a conservative slug shape: lowercase letters, digits,
+// hyphens, underscores. Rejecting weirder names up front prevents
+// surprises when the same string lands in package.json's `name`
+// field (which has its own validation rules) or in shell scripts.
+const VALID_NAME = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+export function isValidFunctionName(name) {
+    return VALID_NAME.test(name);
+}
+// File contents for the scaffolded project. Each renderer takes the
+// function name and returns the raw file body. Kept as named exports
+// so the unit test can assert content without having to spin up the
+// oclif command lifecycle.
+export function renderHandler() {
+    return `// env.PRIMITIVE_API_KEY is auto-injected by the Primitive Functions runtime.
+import { createPrimitiveClient } from "@primitivedotdev/sdk/api";
+
+export default {
+  async fetch(
+    req: Request,
+    env: { PRIMITIVE_API_KEY: string },
+  ): Promise<Response> {
+    const event = (await req.json()) as {
+      email: { headers: { from?: string; subject?: string } };
+    };
+    const client = createPrimitiveClient({ apiKey: env.PRIMITIVE_API_KEY });
+
+    const reply = await client.send({
+      from: "you@your-domain.primitive.email",
+      to: event.email.headers.from ?? "you@your-domain.primitive.email",
+      subject: \`Re: \${event.email.headers.subject ?? ""}\`,
+      bodyText: "Got your message.",
+    });
+
+    return Response.json({ ok: true, reply });
+  },
+};
+`;
+}
+export function renderPackageJson(name) {
+    const pkg = {
+        name,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: {
+            build: "node build.mjs",
+            deploy: `npm run build && primitive functions:deploy --name ${name} --file ./dist/handler.js`,
+            redeploy: "npm run build && primitive functions:redeploy --id $PRIMITIVE_FUNCTION_ID --file ./dist/handler.js",
+        },
+        dependencies: {
+            "@primitivedotdev/sdk": SDK_VERSION_RANGE,
+        },
+        devDependencies: {
+            esbuild: ESBUILD_VERSION_RANGE,
+            typescript: "^5.7.2",
+        },
+    };
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+export function renderBuildMjs() {
+    return `import { build } from "esbuild";
+
+// Bundle handler.ts into a single ESM file suitable for the Primitive
+// Functions runtime. The runtime is a Workers-style environment, so
+// we pick the "worker" / "browser" export conditions on @primitivedotdev/sdk
+// (which routes us to the /api subpath safely without dragging in
+// node:crypto-dependent webhook helpers).
+
+await build({
+  entryPoints: ["handler.ts"],
+  bundle: true,
+  format: "esm",
+  platform: "browser",
+  target: "es2022",
+  conditions: ["worker", "browser"],
+  outfile: "dist/handler.js",
+});
+`;
+}
+export function renderTsconfig() {
+    const tsconfig = {
+        compilerOptions: {
+            target: "ES2022",
+            module: "ESNext",
+            moduleResolution: "Bundler",
+            strict: true,
+            lib: ["ES2022", "WebWorker"],
+            types: [],
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ["handler.ts"],
+    };
+    return `${JSON.stringify(tsconfig, null, 2)}\n`;
+}
+export function renderGitignore() {
+    return "node_modules\ndist\n";
+}
+export function renderReadme(name) {
+    return `# ${name}
+
+## What this is
+
+A Primitive Function: a JavaScript handler that runs on inbound mail.
+It receives the \`email.received\` event, demonstrates a basic reply
+via the Primitive SDK, and returns a JSON envelope.
+
+## Develop
+
+\`\`\`
+npm install
+npm run build
+\`\`\`
+
+## Deploy
+
+\`\`\`
+npm run deploy
+\`\`\`
+
+The deploy step calls \`primitive functions:deploy\` and requires
+\`PRIMITIVE_API_KEY\` to be set in your shell (or pass \`--api-key\`).
+Run \`primitive login\` once to save a key in your CLI config if you
+prefer that to an env var.
+`;
+}
+// Files written by the scaffolder, in the order they're created.
+// Exported as a pure function so the unit test can verify the
+// exact content of every file without invoking the command and
+// touching disk.
+export function scaffoldFiles(name) {
+    return [
+        { contents: renderHandler(), relativePath: "handler.ts" },
+        { contents: renderPackageJson(name), relativePath: "package.json" },
+        { contents: renderBuildMjs(), relativePath: "build.mjs" },
+        { contents: renderTsconfig(), relativePath: "tsconfig.json" },
+        { contents: renderGitignore(), relativePath: ".gitignore" },
+        { contents: renderReadme(name), relativePath: "README.md" },
+    ];
+}
+// Write the scaffold to disk. Refuses to overwrite an existing
+// directory: if `outDir` exists the function throws and leaves the
+// filesystem untouched. On any write error after creating the
+// directory, the partially-written tree is cleaned up so re-runs
+// see a clean slate. Exported for unit testing.
+export function writeScaffold(params) {
+    if (!isValidFunctionName(params.name)) {
+        throw new Errors.CLIError(`Invalid function name "${params.name}". Use lowercase letters, digits, hyphens, or underscores (1-63 chars, must start with a letter or digit).`, { exit: 1 });
+    }
+    const files = scaffoldFiles(params.name);
+    const written = [];
+    // Create the target directory with recursive: false so the check
+    // and the create happen in one syscall. mkdirSync throws EEXIST
+    // atomically if the path already exists, which closes the TOCTOU
+    // window between a separate existsSync check and the mkdir call.
+    try {
+        mkdirSync(params.outDir, { recursive: false });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EEXIST") {
+            throw new Errors.CLIError(`Target directory already exists: ${params.outDir}. Refusing to overwrite. Remove it or pick a different --out-dir.`, { exit: 1 });
+        }
+        if (code === "ENOENT") {
+            throw new Errors.CLIError(`Parent directory does not exist for ${params.outDir}. Create it first or pick a different --out-dir.`, { exit: 1 });
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Errors.CLIError(`Failed to create ${params.outDir}: ${detail}`, {
+            exit: 1,
+        });
+    }
+    try {
+        for (const file of files) {
+            const fullPath = resolve(params.outDir, file.relativePath);
+            mkdirSync(dirname(fullPath), { recursive: true });
+            writeFileSync(fullPath, file.contents, "utf8");
+            written.push(fullPath);
+        }
+    }
+    catch (error) {
+        // Roll back the partial scaffold so the user can retry without
+        // tripping the "directory already exists" guard above.
+        try {
+            rmSync(params.outDir, { force: true, recursive: true });
+        }
+        catch {
+            // Best-effort cleanup; surface the original error regardless.
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Errors.CLIError(`Failed to write scaffold to ${params.outDir}: ${detail}`, { exit: 1 });
+    }
+    return { written };
+}
+class FunctionsInitCommand extends Command {
+    static description = `Scaffold a new Primitive Function project in ./<name>/ with handler.ts, package.json, build.mjs, tsconfig.json, .gitignore, and README.md.
+
+  The scaffolded handler imports \`createPrimitiveClient\` from
+  \`@primitivedotdev/sdk/api\` and demonstrates the canonical pattern:
+  parse the email.received event, send a reply via the SDK, return a
+  JSON envelope. The build script uses esbuild's JS API and emits
+  ./dist/handler.js, ready to hand to \`primitive functions:deploy --file\`.
+
+  Refuses to overwrite an existing directory. Use --out-dir to pick a
+  different target path than ./<name>/.`;
+    static summary = "Scaffold a new Primitive Function project ready for functions:deploy";
+    static examples = [
+        "<%= config.bin %> functions:init my-fn",
+        "<%= config.bin %> functions:init my-fn --out-dir ./functions/my-fn",
+    ];
+    static args = {
+        name: Args.string({
+            description: "Function name. Lowercase letters, digits, hyphens, underscores. 1-63 chars. Used as the directory name (when --out-dir is not set) and as the package.json name.",
+            required: true,
+        }),
+    };
+    static flags = {
+        "out-dir": Flags.string({
+            description: "Directory to scaffold into. Defaults to ./<name>/. Must not already exist.",
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FunctionsInitCommand);
+        const outDir = resolve(flags["out-dir"] ?? `./${args.name}`);
+        writeScaffold({ name: args.name, outDir });
+        this.log(`Scaffolded ${outDir}.`);
+        this.log("Next:");
+        this.log(`  cd ${outDir}`);
+        this.log("  npm install");
+        this.log("  npm run build");
+        this.log(`  primitive functions:deploy --name ${args.name} --file ./dist/handler.js`);
+    }
+}
+export default FunctionsInitCommand;

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

@@ -5,7 +5,9 @@ import EmailsLatestCommand from "./commands/emails-latest.js";
 import EmailsWaitCommand from "./commands/emails-wait.js";
 import EmailsWatchCommand from "./commands/emails-watch.js";
 import FunctionsDeployCommand from "./commands/functions-deploy.js";
+import FunctionsInitCommand from "./commands/functions-init.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";
@@ -139,6 +141,13 @@ export const COMMANDS = {
     // inbound mail. `watch` defaults to a human table; `wait` defaults to JSONL.
     "emails:watch": EmailsWatchCommand,
     "emails:wait": EmailsWaitCommand,
+    // `functions:init` scaffolds a deployable Function project so a
+    // new author can go zero-to-deployed without writing the handler,
+    // package.json, build script, and tsconfig from scratch. The
+    // scaffolded handler imports from @primitivedotdev/sdk/api (the
+    // runtime-client subpath) and demonstrates client.send() so the
+    // first thing the author sees is the SDK pattern, not raw fetch.
+    "functions:init": FunctionsInitCommand,
     // `functions:deploy` and `functions:redeploy` are file-input
     // shortcuts for create-function / update-function. The underlying
     // ops take `code` as a body string, which is awkward at the CLI
@@ -147,5 +156,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

@@ -709,6 +709,39 @@
       "summary": "Wait for matching inbound emails",
       "enableJsonFlag": false
     },
+    "functions:init": {
+      "aliases": [],
+      "args": {
+        "name": {
+          "description": "Function name. Lowercase letters, digits, hyphens, underscores. 1-63 chars. Used as the directory name (when --out-dir is not set) and as the package.json name.",
+          "name": "name",
+          "required": true
+        }
+      },
+      "description": "Scaffold a new Primitive Function project in ./<name>/ with handler.ts, package.json, build.mjs, tsconfig.json, .gitignore, and README.md.\n\n  The scaffolded handler imports `createPrimitiveClient` from\n  `@primitivedotdev/sdk/api` and demonstrates the canonical pattern:\n  parse the email.received event, send a reply via the SDK, return a\n  JSON envelope. The build script uses esbuild's JS API and emits\n  ./dist/handler.js, ready to hand to `primitive functions:deploy --file`.\n\n  Refuses to overwrite an existing directory. Use --out-dir to pick a\n  different target path than ./<name>/.",
+      "examples": [
+        "<%= config.bin %> functions:init my-fn",
+        "<%= config.bin %> functions:init my-fn --out-dir ./functions/my-fn"
+      ],
+      "flags": {
+        "out-dir": {
+          "description": "Directory to scaffold into. Defaults to ./<name>/. Must not already exist.",
+          "name": "out-dir",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "functions:init",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Scaffold a new Primitive Function project ready for functions:deploy",
+      "enableJsonFlag": false
+    },
     "functions:deploy": {
       "aliases": [],
       "args": {},
@@ -859,6 +892,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 +3033,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 +3116,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 +3480,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 +3621,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 +4283,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.21.0"
+  "version": "0.23.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.21.0",
+  "version": "0.23.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:init <name>` to scaffold a deployable project (handler, package.json, build script). 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": " "