@primitivedotdev/sdk 0.23.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-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/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

@@ -4283,5 +4283,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.23.0"
+  "version": "0.24.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.23.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",