@primitivedotdev/sdk 0.22.0 → 0.24.0

package/README.md

@@ -1,13 +1,18 @@
 # `@primitivedotdev/sdk`
 
-The official Node.js SDK and command-line tool for [Primitive](https://primitive.dev), an email API for sending and receiving programmatic mail.
+The official Node.js library for [Primitive](https://primitive.dev), an email API for sending and receiving programmatic mail. Typed client for receiving and verifying inbound webhooks, sending mail, parsing raw MIME, and calling the full HTTP API.
 
-The package ships two things in one install:
+## Looking for the CLI?
 
-- A **`primitive` CLI** for interactive use, scripts, and agent workflows. Sends mail, reads inbound, inspects send history, manages domains and webhook endpoints, all in one binary.
-- A **typed Node library** for programmatic integration in app code. Receives and verifies inbound webhooks, sends mail, parses raw MIME, and exposes the full HTTP API as generated functions.
+The `primitive` CLI now ships as a separate package, [`@primitivedotdev/cli`](https://www.npmjs.com/package/@primitivedotdev/cli). Install it with:
 
-Pick whichever fits the call site. The two share the same auth (`PRIMITIVE_API_KEY`), the same data shapes, and the same OpenAPI spec.
+```bash
+npm install -g @primitivedotdev/cli
+# or, no-install:
+npx @primitivedotdev/cli@latest <command>
+```
+
+This package retains the CLI for a few minor releases for backward compatibility (`npx @primitivedotdev/sdk@latest <command>` still works and prints a one-line migration banner). The retained CLI snapshot will be removed in a future minor release.
 
 ## Install
 
@@ -15,56 +20,16 @@ Pick whichever fits the call site. The two share the same auth (`PRIMITIVE_API_K
 npm install @primitivedotdev/sdk
 ```
 
-For one-off CLI use, `npx @primitivedotdev/sdk@latest <command>` works without installing.
-
 Requires Node.js 22 or newer.
 
 ## Set your API key
 
-Get a key from your [dashboard](https://primitive.dev) and export it. Both the CLI and the library default to reading `PRIMITIVE_API_KEY` from the environment.
+Get a key from your [dashboard](https://primitive.dev) and export it. The library defaults to reading `PRIMITIVE_API_KEY` from the environment.
 
 ```bash
 export PRIMITIVE_API_KEY=prim_...
 ```
 
-## Command line
-
-Everything below assumes `PRIMITIVE_API_KEY` is set. Each command also accepts `--api-key <value>` if you want to pass it explicitly.
-
-```bash
-# Confirm the key is live and see which account it authenticates.
-primitive whoami
-
-# Send an email. --wait blocks until the receiving MTA returns a delivery
-# outcome (a synchronous SMTP 250 from Gmail, etc.); without it, the call
-# returns once Primitive has accepted the message for delivery.
-primitive send --to alice@example.com --body "Hi Alice!" --wait
-
-# See the most recent inbound emails as a compact text table.
-# IDs are full UUIDs when piped, truncated for interactive terminals.
-primitive emails:latest --limit 5
-
-# Read one inbound's full record (body, headers, threading metadata).
-primitive emails:get-email --id <uuid>
-
-# Reply to an inbound. Threading and the "Re:" subject are derived
-# server-side from the parent message; you supply only the body.
-primitive sending:reply-to-email --id <inbound-id> --body-text "..."
-
-# See where you are allowed to send. Returns a typed list of
-# permission rules (managed-zone wildcards, your own verified domains,
-# specific addresses with grants). The send-mail call enforces these
-# at request time.
-primitive sending:get-send-permissions
-
-# Look up an operation's request/response schema, including per-field
-# descriptions sourced from the OpenAPI spec.
-primitive describe emails:get-email
-primitive describe sending:send-email
-```
-
-Run `primitive --help` for the full topic list and `primitive <topic> --help` for the commands within each. Every command accepts `--help`, and the descriptions are detailed enough that the CLI is self-documenting for most workflows.
-
 ## Library
 
 The default root import is intentionally small and centered on the two most common app-code use cases: receiving inbound webhook deliveries and sending mail.

package/bin/run.js

@@ -1,5 +1,20 @@
 #!/usr/bin/env node
 
+// The CLI moved to @primitivedotdev/cli. This bin is retained on
+// @primitivedotdev/sdk for a few minor versions so existing scripts
+// and agent prompts that invoke `npx @primitivedotdev/sdk@latest
+// <command>` keep working. Every invocation prints a one-line stderr
+// banner with the migration command; the actual oclif runtime runs
+// unchanged after that. The CLI surface will be removed from
+// @primitivedotdev/sdk in a future minor release; until then this
+// shipped snapshot is frozen against the 0.23.0 command set.
 import { execute } from "@oclif/core";
 
+process.stderr.write(
+  "[@primitivedotdev/sdk] Heads up: the CLI moved to @primitivedotdev/cli. " +
+    "Switch to `npx @primitivedotdev/cli@latest <command>` " +
+    "(or `npm install -g @primitivedotdev/cli`). " +
+    "The CLI surface will be removed from @primitivedotdev/sdk in a future minor release.\n",
+);
+
 await execute({ dir: import.meta.url });

package/dist/oclif/commands/functions-deploy.js

@@ -3,6 +3,7 @@ import { createFunction } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
 import { extractErrorPayload, readTextFileFlag, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 import { resolveCliAuth } from "../auth.js";
+import { emitRawSendMailFetchWarning } from "../lint/raw-send-mail-fetch.js";
 // `primitive functions:deploy` is the agent-grade shortcut for
 // `functions:create-function`. The underlying operation takes `code`
 // as a string in the JSON body, which is awkward at the CLI for
@@ -72,6 +73,12 @@ class FunctionsDeployCommand extends Command {
             const sourceMap = flags["source-map-file"]
                 ? readTextFileFlag(flags["source-map-file"], "--source-map-file")
                 : undefined;
+            // Non-blocking deploy-time lint: if the bundle has a raw
+            // fetch(...) call against /send-mail, nudge the author toward
+            // `createPrimitiveClient` from `@primitivedotdev/sdk/api`.
+            // The warning lands on stderr so it never contaminates the
+            // JSON stdout the caller may pipe into jq.
+            emitRawSendMailFetchWarning(code, (chunk) => process.stderr.write(chunk));
             const baseUrlOverridden = flags["api-base-url-1"] !== undefined ||
                 flags["api-base-url-2"] !== undefined;
             const auth = resolveCliAuth({

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-redeploy.js

@@ -3,6 +3,7 @@ import { updateFunction } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
 import { extractErrorPayload, readTextFileFlag, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 import { resolveCliAuth } from "../auth.js";
+import { emitRawSendMailFetchWarning } from "../lint/raw-send-mail-fetch.js";
 // `primitive functions:redeploy` is the agent-grade shortcut for
 // `functions:update-function`. Same file-reading ergonomic as
 // functions:deploy but for an existing function. Use this to push a
@@ -61,6 +62,12 @@ class FunctionsRedeployCommand extends Command {
             const sourceMap = flags["source-map-file"]
                 ? readTextFileFlag(flags["source-map-file"], "--source-map-file")
                 : undefined;
+            // Non-blocking deploy-time lint: if the bundle has a raw
+            // fetch(...) call against /send-mail, nudge the author toward
+            // `createPrimitiveClient` from `@primitivedotdev/sdk/api`.
+            // Same check as functions:deploy; warning goes to stderr and
+            // the deploy continues regardless.
+            emitRawSendMailFetchWarning(code, (chunk) => process.stderr.write(chunk));
             const baseUrlOverridden = flags["api-base-url-1"] !== undefined ||
                 flags["api-base-url-2"] !== undefined;
             const auth = resolveCliAuth({

package/dist/oclif/index.js

@@ -5,6 +5,7 @@ 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";
@@ -140,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

package/dist/oclif/lint/raw-send-mail-fetch.js

@@ -0,0 +1,98 @@
+// Deploy-time lint for `functions:deploy --file <bundle>` and
+// `functions:redeploy --file <bundle>`. Looks for a raw
+// `fetch("...primitive.dev/.../send-mail", ...)` call in the bundle
+// text and, on a match, emits a stderr warning telling the author
+// to prefer `createPrimitiveClient` from `@primitivedotdev/sdk/api`.
+//
+// Why: a recurring pattern in agent-assisted Function deploys is to
+// copy the REST snippet from the docs and call `fetch` directly
+// against the Primitive send-mail endpoint, even after the docs
+// switched to leading with the SDK and `functions:init` ships a
+// scaffold that uses `createPrimitiveClient`. The SDK already
+// handles dual-host routing, error envelopes, and send-permission
+// gate denials; raw `fetch` re-discovers each of those by hand. The
+// warning is the catch-net at deploy time: the deploy still
+// proceeds.
+//
+// Scope by design:
+// - We only flag the empirically observed footgun: `/send-mail`.
+//   Not arbitrary calls to api.primitive.dev. Other endpoints have
+//   not surfaced the same pattern.
+// - We require the URL string literal to immediately follow the
+//   `fetch(` token (allowing whitespace) so we don't trip on a
+//   comment that merely mentions the URL. esbuild strips most
+//   comments anyway, but anchoring on `fetch(` keeps the rule
+//   honest without trying to parse JS.
+// - We only look at the bundle text passed in. Source maps and
+//   sibling files are not scanned.
+// - Variable-URL cases (`fetch(url, ...)` where `url` was assembled
+//   elsewhere) are accepted false negatives. The value here is
+//   catching the obvious inline-literal case, not full taint
+//   analysis.
+// Match `fetch(` then a string literal (single, double, or backtick)
+// whose contents include `primitive.dev` and end with `/send-mail`
+// (optionally with a query string or trailing path boundary). Examples
+// matched:
+//   fetch("https://api.primitive.dev/v1/send-mail", {...})
+//   fetch(`https://www.primitive.dev/api/v1/send-mail`, {...})
+//   fetch('https://primitive.dev/api/v1/send-mail?wait=1')
+//
+// The `[^`'"]*` inside the literal forbids the closing quote
+// character itself so we can't accidentally span across two adjacent
+// string literals. The trailing `(?![A-Za-z0-9_-])` forbids any
+// letter, digit, underscore, or hyphen immediately after `send-mail`
+// so `/send-mail-template-preview` does not trip the rule. (Plain
+// `\b` does not help here because `-` is itself a non-word character,
+// so `mail\b` still matches `mail-...`.)
+const RAW_SEND_MAIL_FETCH_REGEX = /fetch\s*\(\s*[`'"][^`'"]*primitive\.dev[^`'"]*\/send-mail(?![A-Za-z0-9_-])/g;
+// How much surrounding text to include on either side of the match
+// when building the sample snippet. Kept short on purpose: bundles
+// are minified and a 120-char window is enough to spot the call
+// without flooding stderr.
+const SNIPPET_PADDING = 60;
+export function detectRawSendMailFetch(bundleText) {
+    // Reset lastIndex defensively: this regex is module-scoped with
+    // the /g flag, so a prior call's state would skip the next match.
+    RAW_SEND_MAIL_FETCH_REGEX.lastIndex = 0;
+    const match = RAW_SEND_MAIL_FETCH_REGEX.exec(bundleText);
+    if (!match) {
+        return { found: false, sampleSnippet: null };
+    }
+    const start = Math.max(0, match.index - SNIPPET_PADDING);
+    const end = Math.min(bundleText.length, match.index + match[0].length + SNIPPET_PADDING);
+    const raw = bundleText.slice(start, end);
+    // Collapse newlines and runs of whitespace so the snippet is one
+    // readable line on stderr regardless of how the bundle was
+    // formatted.
+    const sampleSnippet = raw.replace(/\s+/g, " ").trim();
+    return { found: true, sampleSnippet };
+}
+// The stderr warning copy. Three beats: name the issue, name the
+// SDK alternative, link the docs. Plus a one-line "deploy proceeds"
+// reassurance. Kept punctuation simple (commas, periods, line
+// breaks) so it doesn't trip the no-em-dashes hook and so the lines
+// wrap predictably in a terminal.
+export const RAW_SEND_MAIL_FETCH_WARNING_LINES = [
+    "warning: this bundle calls fetch(...) against /send-mail directly.",
+    "The Primitive SDK exposes createPrimitiveClient from",
+    "@primitivedotdev/sdk/api which handles host routing, error envelopes,",
+    "and gate denials for you. See https://www.primitive.dev/docs/functions",
+    "for the recommended in-handler pattern. Continuing with deploy.",
+];
+export function formatRawSendMailFetchWarning(finding) {
+    const lines = [...RAW_SEND_MAIL_FETCH_WARNING_LINES];
+    if (finding.sampleSnippet) {
+        lines.push(`  found: ${finding.sampleSnippet}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+// Convenience: run the detector and, on a match, write the warning
+// to a stderr-shaped writer. Pulled out so both deploy and redeploy
+// share one code path and so the unit tests can pass a fake writer.
+export function emitRawSendMailFetchWarning(bundleText, write) {
+    const finding = detectRawSendMailFetch(bundleText);
+    if (finding.found) {
+        write(formatRawSendMailFetchWarning(finding));
+    }
+    return finding;
+}

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": {},
@@ -4250,5 +4283,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.22.0"
+  "version": "0.24.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.22.0",
-  "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser modules",
+  "version": "0.24.0",
+  "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser runtime modules. The CLI moved to @primitivedotdev/cli; this package retains the CLI as a deprecated alias for a few minor releases.",
   "type": "module",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -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>` 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."
+        "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": " "