shopstack 0.1.0 → 0.2.0

package/README.md

@@ -1,25 +1,144 @@
 # shopstack
 
-Shopstack CLI is currently in pre-launch.
-
-When installed, it tells users:
-
-> Wow you're fast! Apply for access at https://shopstack.ai
+Dependency-free JavaScript client and CLI for Shopstack's asynchronous checkout API.
 
 ## Install
 
 ```bash
+npm install shopstack
+# or
 npm install -g shopstack
 ```
 
-## What it does now
+Node.js 18 or newer is required.
+
+Version 0.2.0 defaults to Shopstack's currently deployed public staging API at
+`https://shopstack-staging.shopstack.workers.dev/v1`. Set
+`SHOPSTACK_API_URL` only when targeting a different Shopstack environment.
+
+## Personal account
+
+```bash
+shopstack signup user --email you@example.com
+```
+
+This starts a 15-minute signup and waits while you open the verification email.
+No account or API key exists until the link is consumed. The CLI then retrieves
+the first key with its private polling capability and stores it in
+`~/.config/shopstack/config.json` with file mode `0600`; it never prints the
+key or polling capability. It checkpoints the pending signup before polling. If
+the command is interrupted, resume it with:
 
-This package is intentionally in a pre-launch placeholder state.
+```bash
+shopstack signup resume sup_...
+```
 
-If you run the command directly:
+## Developer account and users
 
 ```bash
-shopstack
+shopstack signup developer --email developer@example.com
+shopstack users create --external-id customer-123 --profile customer-123
 ```
 
-You will see the same access message.
+The developer key administers users but cannot run their checkouts. Each created
+user receives an independently scoped API key and CLI profile.
+
+## MCP
+
+Configure any stdio MCP client to run:
+
+```json
+{
+  "mcpServers": {
+    "shopstack": {
+      "command": "npx",
+      "args": ["-y", "shopstack-mcp"]
+    }
+  }
+}
+```
+
+The MCP server can start and poll verified signup, manage local profiles,
+create developer-owned users, list/connect Link, and create/poll/message/cancel
+checkouts. It exposes status, activity, and the latest bounded mechanical intent
+phase. It deliberately has no card-input or payment-approval tool.
+
+The canonical agent skill ships as `SKILL.md` in this package. After
+publication it is available at
+`https://unpkg.com/shopstack@0.2.0/SKILL.md` with the release-pinned package.
+
+## Connections
+
+```bash
+shopstack connect list
+shopstack connect link
+```
+
+Link is currently the only persistent payment provider. Connecting it is
+optional.
+
+## Run a checkout
+
+Create `checkout.json` using the canonical API body:
+
+```json
+{
+  "item_url": "https://merchant.example/product",
+  "instructions": "Buy one in blue",
+  "customer": {
+    "email": "buyer@example.com",
+    "name": "Example Buyer",
+    "phone": "+12125550100",
+    "shipping_address": {
+      "line1": "1 Example Street",
+      "line2": "Apartment 2",
+      "suburb": "Manhattan",
+      "city": "New York",
+      "region": "NY",
+      "postal_code": "10001",
+      "country": "US"
+    }
+  },
+  "maximum_amount": "75.00",
+  "currency": "USD"
+}
+```
+
+Then run:
+
+```bash
+shopstack checkout run --file checkout.json
+```
+
+When no provider is selected, the checkout runs normally until the payment
+form, then asks for card details through a no-echo terminal prompt. Card data is
+sent only to the protected payment-details endpoint. The CLI separately shows
+the exact final amount and asks for approval before Shopstack can submit.
+
+To use an active Link connection, add `"payment_provider": "link"` to the
+request.
+
+Card values are never accepted as command-line flags.
+
+## JavaScript client
+
+```js
+import { ShopstackClient } from "shopstack";
+
+const shopstack = new ShopstackClient({
+  apiKey: process.env.SHOPSTACK_API_KEY,
+});
+
+const result = await shopstack.runCheckout(checkoutRequest, {
+  paymentDetails: async () => secureCardSource(),
+  approve: async (approval) => askYourUserToApprove(approval),
+  message: async (checkout) => askYourUser(checkout.activity),
+});
+```
+
+`runCheckout` returns at a required input if its corresponding callback is
+omitted. Final payment approval is never inferred from a message or from
+supplying a card.
+
+Set `SHOPSTACK_API_URL` to target a different Shopstack API and
+`SHOPSTACK_CONFIG_FILE` to relocate CLI profiles.

package/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: shopstack-checkout
+description: Use Shopstack to onboard a verified personal account or a developer with independently scoped end users, inspect optional Link connectivity, and run asynchronous online checkouts while displaying status, activity, and mechanical intent. Trigger for buying products, automating checkout, integrating Shopstack into an agent, or managing developer-owned shopping users.
+---
+
+# Shopstack Checkout
+
+Use Shopstack as the checkout execution layer. Keep account verification, user ownership, protected payment input, and final payment approval at their typed boundaries.
+
+## Install
+
+For the JavaScript client and CLI:
+
+```bash
+npm install shopstack
+npm install -g shopstack
+```
+
+For MCP clients, configure the local stdio server:
+
+```json
+{
+  "mcpServers": {
+    "shopstack": {
+      "command": "npx",
+      "args": ["-y", "shopstack-mcp"]
+    }
+  }
+}
+```
+
+Never ask the model to print or relay a Shopstack API key. The CLI and MCP server save verified keys in the private local Shopstack profile file.
+
+## Choose the account shape
+
+- Use a personal account for `Shopstack -> user`.
+- Use a developer account for `Shopstack -> developer -> user1, user2, ...`.
+- A developer management key creates and manages users but cannot run a user's checkout.
+- Every developer-owned user receives an independent user API key and profile.
+
+Start verified CLI signup:
+
+```bash
+shopstack signup user --email user@example.com
+shopstack signup developer --email developer@example.com
+```
+
+The user must open the time-limited verification link. No account or API key exists before verification. The CLI polls the signup, saves the verified key with mode `0600`, and does not print it.
+It checkpoints the pending polling capability before waiting. If the process is
+interrupted, use `shopstack signup resume SIGNUP_ID`; the capability remains
+private in the same local profile store.
+
+After developer signup, create an end user:
+
+```bash
+shopstack users create --external-id customer-123 --profile customer-123
+```
+
+Use `shopstack profiles list` and `shopstack profiles use NAME` to select a local profile without exposing its key.
+
+## Choose payment connectivity
+
+Link is currently the only persistent payment provider, and it is optional:
+
+```bash
+shopstack connect list
+shopstack connect link
+```
+
+Include `payment_provider: "link"` only when the active user's Link connection reports checkout-ready. Otherwise omit `payment_provider`. Shopstack will run until card entry and request one protected checkout-scoped card through the SDK or no-echo CLI prompt.
+
+Never put card data in MCP arguments, natural-language messages, model output, logs, or ordinary CLI flags.
+
+## Create and monitor a checkout
+
+Supply the canonical customer schema unchanged:
+
+```json
+{
+  "item_url": "https://merchant.example/product",
+  "instructions": "Buy one in blue",
+  "customer": {
+    "email": "buyer@example.com",
+    "name": "Example Buyer",
+    "phone": "+12125550100",
+    "shipping_address": {
+      "line1": "1 Example Street",
+      "line2": "Apartment 2",
+      "suburb": "Manhattan",
+      "city": "New York",
+      "region": "NY",
+      "postal_code": "10001",
+      "country": "US"
+    }
+  },
+  "maximum_amount": "75.00",
+  "currency": "USD"
+}
+```
+
+Run it with:
+
+```bash
+shopstack checkout run --file checkout.json
+```
+
+Or create with MCP, then call `poll_checkout`. Display these authoritative fields to the user when they change:
+
+- `status`: one of exactly `queued`, `started`, `help_required`, `approval_required`, `submitting`, `complete`, `failed`, `cancelled`;
+- `activity`: bounded present-tense display text;
+- `intent.name`, `intent.phase`, and `intent.updated_at`: bounded mechanical action progress with no arguments or reasoning;
+- `required_input`: a typed handoff such as protected payment-card input;
+- `approval`: the exact amount-bound approval request when present.
+
+Poll every two seconds for `queued`, `started`, and `submitting`; every five seconds for `help_required` and `approval_required`; stop at `complete`, `failed`, or `cancelled`.
+
+## Respond at typed boundaries
+
+- Use `GET/POST /v1/checkout/{id}/messages` only for ordinary missing information.
+- Use protected SDK/CLI payment input when `required_input.type` is `payment_card`.
+- Use only the dedicated payment-approval endpoint from a separately scoped trusted backend.
+- MCP and messages cannot approve payment and expose no approval tool.
+- Never infer approval from a user's conversational message.
+- Cancel with the typed cancellation operation if the user withdraws the request.
+
+Use the checkout's canonical current representation as state truth. Events are ordered evidence, not a replacement state machine. Preserve idempotency keys on retried mutations.

package/bin/shopstack

@@ -1,3 +1,10 @@
 #!/usr/bin/env node
 
-console.log("Wow you're fast! Apply for access at https://shopstack.ai");
+import { runCli } from "../src/cli.js";
+
+try {
+  await runCli(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,13 +1,30 @@
 {
   "name": "shopstack",
-  "version": "0.1.0",
-  "description": "Shopstack CLI placeholder package while access is being rolled out.",
+  "version": "0.2.0",
+  "description": "Shopstack API client and command-line checkout tools.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/client.d.ts",
+      "import": "./src/client.js"
+    },
+    "./config": {
+      "types": "./src/config.d.ts",
+      "import": "./src/config.js"
+    }
+  },
+  "types": "./src/client.d.ts",
+  "files": [
+    "SKILL.md",
+    "bin",
+    "src"
+  ],
   "bin": {
-    "shopstack": "./bin/shopstack"
+    "shopstack": "bin/shopstack"
   },
   "scripts": {
-    "postinstall": "node ./scripts/postinstall.js",
-    "shopstack": "node ./bin/shopstack"
+    "shopstack": "node ./bin/shopstack",
+    "test": "node --test"
   },
   "engines": {
     "node": ">=18"
@@ -16,6 +33,7 @@
   "keywords": [
     "shopstack",
     "cli",
-    "coming-soon"
+    "checkout",
+    "payments"
   ]
 }

package/src/cli.js

@@ -0,0 +1,386 @@
+import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+
+import { ShopstackClient } from "./client.js";
+import { ConfigStore } from "./config.js";
+
+const HELP = `Shopstack
+
+Account setup:
+  shopstack signup user --email EMAIL
+  shopstack signup developer --email EMAIL
+  shopstack signup resume SIGNUP_ID
+  shopstack users create --external-id ID [--profile NAME]
+  shopstack profiles list
+  shopstack profiles use NAME
+
+Payment connection:
+  shopstack connect list
+  shopstack connect link
+
+Checkout:
+  shopstack checkout create --file checkout.json
+  shopstack checkout run --file checkout.json
+  shopstack checkout get CHECKOUT_ID
+  shopstack checkout cancel CHECKOUT_ID
+`;
+
+function parseOptions(args, allowed) {
+  const positional = [];
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+    const name = value.slice(2);
+    if (!allowed.has(name)) throw new Error(`Unknown option: --${name}`);
+    const optionValue = args[index + 1];
+    if (optionValue === undefined || optionValue.startsWith("--")) {
+      throw new Error(`Option --${name} requires a value.`);
+    }
+    options[name] = optionValue;
+    index += 1;
+  }
+  return { options, positional };
+}
+
+function required(options, name) {
+  const value = options[name];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Missing required option: --${name}`);
+  }
+  return value;
+}
+
+function writeJson(stream, value) {
+  stream.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function readJsonFile(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function visiblePrompt(message, dependencies) {
+  if (dependencies.prompt) return dependencies.prompt(message);
+  const input = dependencies.stdin ?? process.stdin;
+  const output = dependencies.stdout ?? process.stdout;
+  const interface_ = createInterface({ input, output });
+  try {
+    return await interface_.question(message);
+  } finally {
+    interface_.close();
+  }
+}
+
+async function hiddenPrompt(message, dependencies) {
+  if (dependencies.secretPrompt) return dependencies.secretPrompt(message);
+  const input = dependencies.stdin ?? process.stdin;
+  const output = dependencies.stderr ?? process.stderr;
+  if (!input.isTTY || typeof input.setRawMode !== "function") {
+    throw new Error(
+      "Protected payment input requires an interactive terminal.",
+    );
+  }
+  output.write(message);
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const restore = () => {
+      input.off("data", onData);
+      input.setRawMode(false);
+      input.pause();
+      output.write("\n");
+    };
+    const onData = (chunk) => {
+      const text = String(chunk);
+      for (const character of text) {
+        if (character === "\r" || character === "\n") {
+          restore();
+          resolve(value);
+          return;
+        }
+        if (character === "\u0003") {
+          restore();
+          reject(new Error("Payment input cancelled."));
+          return;
+        }
+        if (character === "\u007f" || character === "\b") {
+          value = value.slice(0, -1);
+        } else {
+          value += character;
+        }
+      }
+    };
+    input.setRawMode(true);
+    input.resume();
+    input.on("data", onData);
+  });
+}
+
+function sanitizedAccountResult(result) {
+  return {
+    account: result.account,
+    api_key_saved: true,
+    key_type: result.key_type,
+    ...(result.user === undefined ? {} : { user: result.user }),
+  };
+}
+
+function sanitizedUserResult(result, profile) {
+  const { api_key: _apiKey, ...user } = result;
+  return { api_key_saved: true, profile, user };
+}
+
+async function saveVerifiedSignup(result, profileName, configStore) {
+  await configStore.saveProfile(
+    profileName,
+    {
+      accountId: result.account.id,
+      apiKey: result.api_key,
+      keyType: result.key_type,
+      ...(result.user?.id === undefined ? {} : { userId: result.user.id }),
+    },
+    { activate: true },
+  );
+}
+
+async function activeClient(dependencies, requiredKind = "user") {
+  const profile = await dependencies.configStore.activeProfile();
+  const environmentKey = process.env.SHOPSTACK_API_KEY;
+  const apiKey = environmentKey || profile?.apiKey;
+  const keyType = environmentKey ? requiredKind : profile?.keyType;
+  if (!apiKey)
+    throw new Error("No active Shopstack API key. Run signup first.");
+  if (requiredKind && keyType !== requiredKind) {
+    throw new Error(`This command requires an active ${requiredKind} profile.`);
+  }
+  return {
+    client: dependencies.clientFactory({
+      apiKey,
+      baseUrl: process.env.SHOPSTACK_API_URL,
+    }),
+    profile,
+  };
+}
+
+export async function runCli(args, supplied = {}) {
+  const dependencies = {
+    clientFactory: (options) => new ShopstackClient(options),
+    configStore: new ConfigStore(),
+    confirm: undefined,
+    prompt: undefined,
+    readJsonFile,
+    secretPrompt: undefined,
+    stderr: process.stderr,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    ...supplied,
+  };
+  const [group, action, ...rest] = args;
+  if (group === undefined || group === "help" || group === "--help") {
+    dependencies.stdout.write(HELP);
+    return;
+  }
+
+  if (group === "signup") {
+    if (action === "resume") {
+      if (rest.length !== 1) {
+        throw new Error("Use `shopstack signup resume SIGNUP_ID`.");
+      }
+      const pending = await dependencies.configStore.pendingSignup(rest[0]);
+      if (pending === undefined) {
+        throw new Error("That signup is not present in the local profile store.");
+      }
+      const client = dependencies.clientFactory({
+        baseUrl: process.env.SHOPSTACK_API_URL,
+      });
+      const result = await client.waitForAccountSignup(
+        pending.id,
+        pending.pollToken,
+      );
+      await saveVerifiedSignup(result, pending.profile, dependencies.configStore);
+      await dependencies.configStore.deletePendingSignup(pending.id);
+      writeJson(dependencies.stdout, {
+        ...sanitizedAccountResult(result),
+        profile: pending.profile,
+      });
+      return;
+    }
+    if (action !== "user" && action !== "developer") {
+      throw new Error(
+        "Use `shopstack signup user` or `shopstack signup developer`.",
+      );
+    }
+    const { options, positional } = parseOptions(
+      rest,
+      new Set(["email", "profile"]),
+    );
+    if (positional.length > 0) throw new Error("Unexpected signup argument.");
+    const email = required(options, "email");
+    const client = dependencies.clientFactory({
+      baseUrl: process.env.SHOPSTACK_API_URL,
+    });
+    const accountType = action === "user" ? "personal" : "developer";
+    const profileName =
+      options.profile ?? (action === "developer" ? "developer" : "default");
+    const signup = await client.startAccountSignup({
+      accountType,
+      email,
+    });
+    await dependencies.configStore.savePendingSignup({
+      accountType: signup.account_type,
+      email: signup.email,
+      expiresAt: signup.expires_at,
+      id: signup.id,
+      pollToken: signup.poll_token,
+      profile: profileName,
+    });
+    dependencies.stderr.write(
+      `Verification email sent to ${signup.email}. Open the link before ${signup.expires_at}. If interrupted, resume signup ${signup.id}.\n`,
+    );
+    const result = await client.waitForAccountSignup(
+      signup.id,
+      signup.poll_token,
+    );
+    await saveVerifiedSignup(result, profileName, dependencies.configStore);
+    await dependencies.configStore.deletePendingSignup(signup.id);
+    writeJson(dependencies.stdout, {
+      ...sanitizedAccountResult(result),
+      profile: profileName,
+    });
+    return;
+  }
+
+  if (group === "users" && action === "create") {
+    const { options, positional } = parseOptions(
+      rest,
+      new Set(["external-id", "profile"]),
+    );
+    if (positional.length > 0) throw new Error("Unexpected user argument.");
+    const externalId = required(options, "external-id");
+    const { client, profile } = await activeClient(dependencies, "developer");
+    const result = await client.createUser({ externalId });
+    const profileName = options.profile ?? externalId;
+    await dependencies.configStore.saveProfile(
+      profileName,
+      {
+        accountId: profile.accountId,
+        apiKey: result.api_key,
+        keyType: "user",
+        userId: result.id,
+      },
+      { activate: true },
+    );
+    writeJson(dependencies.stdout, sanitizedUserResult(result, profileName));
+    return;
+  }
+
+  if (group === "profiles" && action === "list") {
+    const config = await dependencies.configStore.load();
+    writeJson(dependencies.stdout, {
+      active: config.active,
+      profiles: Object.entries(config.profiles).map(([name, profile]) => ({
+        account_id: profile.accountId,
+        key_type: profile.keyType,
+        name,
+        ...(profile.userId === undefined ? {} : { user_id: profile.userId }),
+      })),
+    });
+    return;
+  }
+  if (group === "profiles" && action === "use") {
+    if (rest.length !== 1) throw new Error("A profile name is required.");
+    await dependencies.configStore.useProfile(rest[0]);
+    writeJson(dependencies.stdout, { active: rest[0] });
+    return;
+  }
+
+  if (group === "connect" && (action === "list" || action === "link")) {
+    if (rest.length > 0) throw new Error("Unexpected connection argument.");
+    const { client } = await activeClient(dependencies, "user");
+    const result =
+      action === "list"
+        ? await client.listConnections()
+        : await client.connect("link");
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "checkout" && action === "create") {
+    const { options, positional } = parseOptions(rest, new Set(["file"]));
+    if (positional.length > 0) throw new Error("Unexpected checkout argument.");
+    const { client } = await activeClient(dependencies, "user");
+    const result = await client.createCheckout(
+      await dependencies.readJsonFile(required(options, "file")),
+    );
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "checkout" && action === "run") {
+    const { options, positional } = parseOptions(rest, new Set(["file"]));
+    if (positional.length > 0) throw new Error("Unexpected checkout argument.");
+    const { client } = await activeClient(dependencies, "user");
+    const request = await dependencies.readJsonFile(required(options, "file"));
+    const result = await client.runCheckout(request, {
+      onProgress: (checkout) => {
+        const intent =
+          checkout.intent?.name === undefined
+            ? ""
+            : ` ${checkout.intent.name}:${checkout.intent.phase}`;
+        dependencies.stderr.write(
+          `[${checkout.status}]${intent} ${checkout.activity ?? ""}`.trimEnd() +
+            "\n",
+        );
+      },
+      approve: async (approval) => {
+        const summary = [
+          `Subtotal: ${approval.subtotal ?? "unavailable"} ${approval.currency}`,
+          `Shipping: ${approval.shipping ?? "unavailable"} ${approval.currency}`,
+          `Tax: ${approval.tax ?? "unavailable"} ${approval.currency}`,
+          `Total: ${approval.total} ${approval.currency}`,
+        ].join("\n");
+        dependencies.stderr.write(`${summary}\n`);
+        if (dependencies.confirm) return dependencies.confirm(approval);
+        const answer = await visiblePrompt(
+          "Approve this exact payment? [y/N] ",
+          dependencies,
+        );
+        return /^y(?:es)?$/iu.test(answer.trim());
+      },
+      message: (checkout) =>
+        visiblePrompt(
+          `${checkout.activity || "Shopstack needs more information"}: `,
+          dependencies,
+        ),
+      paymentDetails: async () => ({
+        number: await hiddenPrompt("Card number: ", dependencies),
+        exp_month: Number(
+          await hiddenPrompt("Expiry month (1-12): ", dependencies),
+        ),
+        exp_year: Number(
+          await hiddenPrompt("Expiry year (YYYY): ", dependencies),
+        ),
+        cvc: await hiddenPrompt("CVC: ", dependencies),
+      }),
+    });
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "checkout" && (action === "get" || action === "cancel")) {
+    if (rest.length !== 1) throw new Error("A checkout ID is required.");
+    const { client } = await activeClient(dependencies, "user");
+    const result =
+      action === "get"
+        ? await client.getCheckout(rest[0])
+        : await client.cancelCheckout(rest[0]);
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  throw new Error("Unknown command. Run `shopstack help`.");
+}
+
+export { HELP };

package/src/client.d.ts

@@ -0,0 +1,177 @@
+export interface ShopstackClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+
+export interface PaymentCard {
+  number: string;
+  exp_month: number;
+  exp_year: number;
+  cvc: string;
+}
+
+export interface PaymentApproval {
+  id: string;
+  subtotal: string | null;
+  shipping: string | null;
+  tax: string | null;
+  total: string;
+  currency: string;
+  expires_at: string;
+}
+
+export interface Checkout {
+  id: string;
+  status:
+    | "queued"
+    | "started"
+    | "help_required"
+    | "approval_required"
+    | "submitting"
+    | "complete"
+    | "failed"
+    | "cancelled";
+  revision: number;
+  activity: string;
+  intent?: {
+    name: string;
+    phase: "selected" | "completed" | "uncertain" | "failed";
+    updated_at: string;
+  };
+  item_url: string;
+  required_input?: { type: "payment_card" };
+  approval?: PaymentApproval;
+  result?: Record<string, unknown>;
+  failure?: Record<string, unknown>;
+  created_at: string;
+  updated_at: string;
+  expires_at: string;
+}
+
+export interface RunCheckoutOptions {
+  idempotencyKey?: string;
+  pollIntervalMs?: number;
+  timeoutMs?: number;
+  onProgress?(checkout: Checkout): void | Promise<void>;
+  paymentDetails?(
+    checkout: Checkout,
+  ): PaymentCard | Promise<PaymentCard | undefined> | undefined;
+  approve?(
+    approval: PaymentApproval,
+    checkout: Checkout,
+  ): boolean | Promise<boolean | undefined> | undefined;
+  message?(
+    checkout: Checkout,
+  ): string | Promise<string | undefined> | undefined;
+}
+
+export interface AccountSignupStarted {
+  id: string;
+  account_type: "personal" | "developer";
+  email: string;
+  status: "verification_required";
+  created_at: string;
+  expires_at: string;
+  poll_token: string;
+}
+
+export interface VerifiedAccountSignup {
+  id: string;
+  status: "verified";
+  verified_at: string;
+  account: Record<string, unknown>;
+  api_key: string;
+  key_type: "user" | "developer";
+  user?: Record<string, unknown>;
+}
+
+export interface SignupOptions {
+  accountType: "personal" | "developer";
+  email: string;
+  idempotencyKey?: string;
+  pollIntervalMs?: number;
+  timeoutMs?: number;
+  onVerificationRequired?(signup: Omit<AccountSignupStarted, "poll_token">):
+    | void
+    | Promise<void>;
+}
+
+export class ShopstackApiError extends Error {
+  code: string;
+  requestId?: string;
+  status?: number;
+}
+
+export class ShopstackClient {
+  constructor(options?: ShopstackClientOptions);
+  startAccountSignup(input: {
+    accountType: "personal" | "developer";
+    email: string;
+    idempotencyKey?: string;
+  }): Promise<AccountSignupStarted>;
+  pollAccountSignup(
+    signupId: string,
+    pollToken: string,
+  ): Promise<
+    Omit<AccountSignupStarted, "poll_token"> | VerifiedAccountSignup
+  >;
+  waitForAccountSignup(
+    signupId: string,
+    pollToken: string,
+    options?: { pollIntervalMs?: number; timeoutMs?: number },
+  ): Promise<VerifiedAccountSignup>;
+  signup(input: SignupOptions): Promise<VerifiedAccountSignup>;
+  createUser(input: {
+    externalId: string;
+    idempotencyKey?: string;
+  }): Promise<Record<string, unknown>>;
+  listUsers(): Promise<Record<string, unknown>>;
+  getUser(userId: string): Promise<Record<string, unknown>>;
+  rotateUserApiKey(
+    userId: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<Record<string, unknown>>;
+  updateUser(
+    userId: string,
+    status: "active" | "suspended",
+    options?: { idempotencyKey?: string },
+  ): Promise<Record<string, unknown>>;
+  listConnections(): Promise<Record<string, unknown>>;
+  connect(
+    paymentProvider?: "link",
+    options?: { idempotencyKey?: string },
+  ): Promise<Record<string, unknown>>;
+  createCheckout(
+    checkout: Record<string, unknown>,
+    options?: { idempotencyKey?: string },
+  ): Promise<Checkout>;
+  getCheckout(checkoutId: string): Promise<Checkout>;
+  cancelCheckout(
+    checkoutId: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<Checkout>;
+  sendMessage(
+    checkoutId: string,
+    content: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<Record<string, unknown>>;
+  listMessages(checkoutId: string): Promise<Record<string, unknown>>;
+  listEvents(checkoutId: string): Promise<Record<string, unknown>>;
+  listArtifacts(checkoutId: string): Promise<Record<string, unknown>>;
+  providePaymentDetails(
+    checkoutId: string,
+    card: PaymentCard,
+    options?: { idempotencyKey?: string },
+  ): Promise<Checkout>;
+  decidePaymentApproval(
+    checkoutId: string,
+    approvalId: string,
+    approved: boolean,
+    options?: { idempotencyKey?: string },
+  ): Promise<Checkout>;
+  runCheckout(
+    checkout: Record<string, unknown>,
+    options?: RunCheckoutOptions,
+  ): Promise<Checkout>;
+}

package/src/client.js

@@ -0,0 +1,358 @@
+import { randomUUID } from "node:crypto";
+
+const TERMINAL_STATUSES = new Set(["complete", "failed", "cancelled"]);
+
+export class ShopstackApiError extends Error {
+  constructor(message, { code = "api_error", requestId, status } = {}) {
+    super(message);
+    this.name = "ShopstackApiError";
+    this.code = code;
+    this.requestId = requestId;
+    this.status = status;
+  }
+}
+
+function idempotencyKey(prefix) {
+  return `${prefix}-${randomUUID()}`;
+}
+
+function delay(milliseconds) {
+  return milliseconds <= 0
+    ? Promise.resolve()
+    : new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+export class ShopstackClient {
+  constructor({
+    apiKey,
+    baseUrl = "https://shopstack-staging.shopstack.workers.dev/v1",
+    fetch: fetchImplementation = globalThis.fetch,
+  } = {}) {
+    if (typeof baseUrl !== "string" || !/^https?:\/\//u.test(baseUrl)) {
+      throw new TypeError("baseUrl must be an HTTP(S) URL");
+    }
+    if (typeof fetchImplementation !== "function") {
+      throw new TypeError("a fetch implementation is required");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/u, "");
+    this.fetch = fetchImplementation;
+  }
+
+  async request(
+    path,
+    {
+      bearerToken,
+      body,
+      idempotencyKey: mutationKey,
+      method = "GET",
+    } = {},
+  ) {
+    const headers = new Headers({ Accept: "application/json" });
+    const authorization = bearerToken ?? this.apiKey;
+    if (authorization) {
+      headers.set("Authorization", `Bearer ${authorization}`);
+    }
+    if (body !== undefined) headers.set("Content-Type", "application/json");
+    if (mutationKey) headers.set("Idempotency-Key", mutationKey);
+    const response = await this.fetch(`${this.baseUrl}${path}`, {
+      body: body === undefined ? undefined : JSON.stringify(body),
+      headers,
+      method,
+    });
+    const raw = await response.text();
+    let payload;
+    try {
+      payload = raw ? JSON.parse(raw) : undefined;
+    } catch {
+      throw new ShopstackApiError("Shopstack returned invalid JSON.", {
+        status: response.status,
+      });
+    }
+    if (!response.ok) {
+      const error = payload?.error;
+      throw new ShopstackApiError(
+        typeof error?.message === "string"
+          ? error.message
+          : `Shopstack request failed with status ${response.status}.`,
+        {
+          code: typeof error?.code === "string" ? error.code : "api_error",
+          requestId:
+            typeof error?.request_id === "string"
+              ? error.request_id
+              : undefined,
+          status: response.status,
+        },
+      );
+    }
+    return payload;
+  }
+
+  startAccountSignup({ accountType, email, idempotencyKey: key } = {}) {
+    return this.request("/accounts", {
+      body: { account_type: accountType, email },
+      idempotencyKey: key ?? idempotencyKey("account"),
+      method: "POST",
+    });
+  }
+
+  pollAccountSignup(signupId, pollToken) {
+    return this.request(`/accounts/${encodeURIComponent(signupId)}`, {
+      bearerToken: pollToken,
+    });
+  }
+
+  async waitForAccountSignup(
+    signupId,
+    pollToken,
+    { pollIntervalMs = 2_000, timeoutMs = 15 * 60 * 1_000 } = {},
+  ) {
+    const startedAt = Date.now();
+    while (true) {
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new ShopstackApiError("Email verification timed out.", {
+          code: "signup_timeout",
+        });
+      }
+      const current = await this.pollAccountSignup(signupId, pollToken);
+      if (current.status === "verified") return current;
+      await delay(pollIntervalMs);
+    }
+  }
+
+  async signup({
+    accountType,
+    email,
+    idempotencyKey: key,
+    onVerificationRequired,
+    pollIntervalMs = 2_000,
+    timeoutMs = 15 * 60 * 1_000,
+  } = {}) {
+    const signup = await this.startAccountSignup({
+      accountType,
+      email,
+      idempotencyKey: key,
+    });
+    if (typeof onVerificationRequired === "function") {
+      await onVerificationRequired({
+        account_type: signup.account_type,
+        email: signup.email,
+        expires_at: signup.expires_at,
+        id: signup.id,
+        status: signup.status,
+      });
+    }
+    return this.waitForAccountSignup(signup.id, signup.poll_token, {
+      pollIntervalMs,
+      timeoutMs,
+    });
+  }
+
+  createUser({ externalId, idempotencyKey: key } = {}) {
+    return this.request("/users", {
+      body: { external_id: externalId },
+      idempotencyKey: key ?? idempotencyKey("user"),
+      method: "POST",
+    });
+  }
+
+  listUsers() {
+    return this.request("/users");
+  }
+
+  getUser(userId) {
+    return this.request(`/users/${encodeURIComponent(userId)}`);
+  }
+
+  rotateUserApiKey(userId, { idempotencyKey: key } = {}) {
+    return this.request(`/users/${encodeURIComponent(userId)}/api-key/rotate`, {
+      idempotencyKey: key ?? idempotencyKey("rotate"),
+      method: "POST",
+    });
+  }
+
+  updateUser(userId, status, { idempotencyKey: key } = {}) {
+    return this.request(`/users/${encodeURIComponent(userId)}`, {
+      body: { status },
+      idempotencyKey: key ?? idempotencyKey("user-update"),
+      method: "PATCH",
+    });
+  }
+
+  listConnections() {
+    return this.request("/connect");
+  }
+
+  connect(paymentProvider = "link", { idempotencyKey: key } = {}) {
+    return this.request("/connect", {
+      body: { payment_provider: paymentProvider },
+      idempotencyKey: key ?? idempotencyKey("connect"),
+      method: "POST",
+    });
+  }
+
+  createCheckout(checkout, { idempotencyKey: key } = {}) {
+    return this.request("/checkout", {
+      body: checkout,
+      idempotencyKey: key ?? idempotencyKey("checkout"),
+      method: "POST",
+    });
+  }
+
+  getCheckout(checkoutId) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}`);
+  }
+
+  cancelCheckout(checkoutId, { idempotencyKey: key } = {}) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}/cancel`, {
+      idempotencyKey: key ?? idempotencyKey("cancel"),
+      method: "POST",
+    });
+  }
+
+  sendMessage(checkoutId, content, { idempotencyKey: key } = {}) {
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/messages`,
+      {
+        body: { content },
+        idempotencyKey: key ?? idempotencyKey("message"),
+        method: "POST",
+      },
+    );
+  }
+
+  listMessages(checkoutId) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}/messages`);
+  }
+
+  listEvents(checkoutId) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}/events`);
+  }
+
+  listArtifacts(checkoutId) {
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/artifacts`,
+    );
+  }
+
+  providePaymentDetails(checkoutId, card, { idempotencyKey: key } = {}) {
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/payment-details`,
+      {
+        body: { card },
+        idempotencyKey: key ?? idempotencyKey("payment-details"),
+        method: "POST",
+      },
+    );
+  }
+
+  decidePaymentApproval(
+    checkoutId,
+    approvalId,
+    approved,
+    { idempotencyKey: key } = {},
+  ) {
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/payment-approval`,
+      {
+        body: { approval_id: approvalId, approved },
+        idempotencyKey: key ?? idempotencyKey("approval"),
+        method: "POST",
+      },
+    );
+  }
+
+  async runCheckout(checkoutRequest, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30 * 60 * 1_000;
+    const startedAt = Date.now();
+    let checkout = await this.createCheckout(checkoutRequest, {
+      idempotencyKey: options.idempotencyKey,
+    });
+    let progressFingerprint;
+    const publishProgress = async (current) => {
+      if (typeof options.onProgress !== "function") return;
+      const fingerprint = JSON.stringify([
+        current.status,
+        current.revision,
+        current.activity,
+        current.intent?.name,
+        current.intent?.phase,
+        current.intent?.updated_at,
+        current.required_input?.type,
+        current.approval?.id,
+      ]);
+      if (fingerprint === progressFingerprint) return;
+      progressFingerprint = fingerprint;
+      await options.onProgress(current);
+    };
+    await publishProgress(checkout);
+    let handledPaymentRevision;
+    let handledApprovalId;
+    let handledMessageRevision;
+    while (!TERMINAL_STATUSES.has(checkout.status)) {
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new ShopstackApiError("Checkout monitoring timed out.", {
+          code: "checkout_timeout",
+        });
+      }
+      checkout = await this.getCheckout(checkout.id);
+      await publishProgress(checkout);
+      if (
+        checkout.required_input?.type === "payment_card" &&
+        handledPaymentRevision !== checkout.revision
+      ) {
+        if (typeof options.paymentDetails !== "function") return checkout;
+        handledPaymentRevision = checkout.revision;
+        const card = await options.paymentDetails(checkout);
+        if (card === undefined) return checkout;
+        await this.providePaymentDetails(checkout.id, card, {
+          idempotencyKey: `payment-details-${checkout.id}-${checkout.revision}`,
+        });
+        continue;
+      }
+      if (
+        checkout.status === "approval_required" &&
+        checkout.approval &&
+        handledApprovalId !== checkout.approval.id
+      ) {
+        if (typeof options.approve !== "function") return checkout;
+        handledApprovalId = checkout.approval.id;
+        const approved = await options.approve(checkout.approval, checkout);
+        if (typeof approved !== "boolean") return checkout;
+        await this.decidePaymentApproval(
+          checkout.id,
+          checkout.approval.id,
+          approved,
+          { idempotencyKey: `approval-${checkout.approval.id}` },
+        );
+        if (!approved) return this.getCheckout(checkout.id);
+        continue;
+      }
+      if (
+        checkout.status === "help_required" &&
+        checkout.required_input === undefined &&
+        handledMessageRevision !== checkout.revision
+      ) {
+        if (typeof options.message !== "function") return checkout;
+        handledMessageRevision = checkout.revision;
+        const content = await options.message(checkout);
+        if (typeof content !== "string" || content.length === 0)
+          return checkout;
+        await this.sendMessage(checkout.id, content, {
+          idempotencyKey: `message-${checkout.id}-${checkout.revision}`,
+        });
+        continue;
+      }
+      if (!TERMINAL_STATUSES.has(checkout.status)) {
+        const pollIntervalMs =
+          options.pollIntervalMs ??
+          (checkout.status === "help_required" ||
+          checkout.status === "approval_required"
+            ? 5_000
+            : 2_000);
+        await delay(pollIntervalMs);
+      }
+    }
+    return checkout;
+  }
+}

package/src/config.d.ts

@@ -0,0 +1,36 @@
+export interface ShopstackProfile {
+  accountId: string;
+  apiKey: string;
+  keyType: "developer" | "user";
+  userId?: string;
+}
+
+export interface PendingSignup {
+  accountType: "developer" | "personal";
+  email: string;
+  expiresAt: string;
+  id: string;
+  pollToken: string;
+  profile: string;
+}
+
+export class ConfigStore {
+  constructor(path?: string);
+  activeProfile(): Promise<ShopstackProfile | undefined>;
+  saveProfile(
+    name: string,
+    profile: ShopstackProfile,
+    options?: { activate?: boolean },
+  ): Promise<ShopstackProfile>;
+  useProfile(name: string): Promise<ShopstackProfile>;
+  savePendingSignup(signup: PendingSignup): Promise<PendingSignup>;
+  pendingSignup(signupId: string): Promise<PendingSignup | undefined>;
+  deletePendingSignup(signupId: string): Promise<void>;
+  load(): Promise<{
+    active: string | null;
+    pendingSignups: Record<string, PendingSignup>;
+    profiles: Record<string, ShopstackProfile>;
+  }>;
+}
+
+export function defaultConfigPath(): string;

package/src/config.js

@@ -0,0 +1,101 @@
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export function defaultConfigPath() {
+  return (
+    process.env.SHOPSTACK_CONFIG_FILE ??
+    join(homedir(), ".config", "shopstack", "config.json")
+  );
+}
+
+export class ConfigStore {
+  constructor(path = defaultConfigPath()) {
+    this.path = path;
+  }
+
+  async load() {
+    try {
+      const parsed = JSON.parse(await readFile(this.path, "utf8"));
+      if (
+        typeof parsed !== "object" ||
+        parsed === null ||
+        typeof parsed.profiles !== "object" ||
+        parsed.profiles === null
+      ) {
+        throw new Error("Shopstack configuration is invalid.");
+      }
+      if (
+        parsed.pendingSignups !== undefined &&
+        (typeof parsed.pendingSignups !== "object" ||
+          parsed.pendingSignups === null ||
+          Array.isArray(parsed.pendingSignups))
+      ) {
+        throw new Error("Shopstack configuration is invalid.");
+      }
+      parsed.pendingSignups ??= {};
+      return parsed;
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        return { active: null, pendingSignups: {}, profiles: {} };
+      }
+      throw error;
+    }
+  }
+
+  async write(config) {
+    const directory = dirname(this.path);
+    await mkdir(directory, { mode: 0o700, recursive: true });
+    const temporary = `${this.path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, {
+      mode: 0o600,
+    });
+    await rename(temporary, this.path);
+    await chmod(this.path, 0o600);
+  }
+
+  async saveProfile(name, profile, { activate = false } = {}) {
+    if (!/^[A-Za-z0-9._-]{1,80}$/u.test(name)) {
+      throw new Error("Profile name is invalid.");
+    }
+    const config = await this.load();
+    config.profiles[name] = { ...profile };
+    if (activate || config.active === null) config.active = name;
+    await this.write(config);
+    return config.profiles[name];
+  }
+
+  async useProfile(name) {
+    const config = await this.load();
+    if (!Object.hasOwn(config.profiles, name)) {
+      throw new Error(`Unknown Shopstack profile: ${name}`);
+    }
+    config.active = name;
+    await this.write(config);
+    return config.profiles[name];
+  }
+
+  async activeProfile() {
+    const config = await this.load();
+    const name = config.active;
+    return typeof name === "string" ? config.profiles[name] : undefined;
+  }
+
+  async savePendingSignup(signup) {
+    const config = await this.load();
+    config.pendingSignups[signup.id] = { ...signup };
+    await this.write(config);
+    return config.pendingSignups[signup.id];
+  }
+
+  async pendingSignup(signupId) {
+    const config = await this.load();
+    return config.pendingSignups[signupId];
+  }
+
+  async deletePendingSignup(signupId) {
+    const config = await this.load();
+    delete config.pendingSignups[signupId];
+    await this.write(config);
+  }
+}

package/scripts/postinstall.js

@@ -1,6 +0,0 @@
-#!/usr/bin/env node
-
-const message =
-  "Wow you're fast! Apply for access at https://shopstack.ai";
-
-console.log(message);