shopstack 0.1.0 → 0.2.1

package/README.md

@@ -1,25 +1,160 @@
 # 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.
+
+The 0.2.1 source candidate 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.
+
+## Verified signup
+
+```bash
+shopstack signup
+```
+
+The command asks for email and Personal or Developer account type. It 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 generates and privately
+persists all retry and polling capabilities before the first request, then
+retrieves the first key after verification and stores it in
+`~/.config/shopstack/config.json` with file mode `0600`; it never prints the
+key, recovery capability, or polling capability. If the command is interrupted,
+rerun `shopstack signup`; the matching pending attempt resumes automatically.
+The explicit helper also remains available:
+
+```bash
+shopstack signup resume sup_...
+```
+
+## Developer account and users
+
+```bash
+shopstack signup
+shopstack users create --external-id customer-123 --profile customer-123
+```
+
+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.
 
-This package is intentionally in a pre-launch placeholder state.
+The canonical agent skill ships as `SKILL.md` in this package. After
+publication it is available at
+`https://unpkg.com/shopstack@0.2.1/SKILL.md` with the release-pinned package.
 
-If you run the command directly:
+## Connections
 
 ```bash
-shopstack
+shopstack connect list
+shopstack connect link
 ```
 
-You will see the same access message.
+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 onboarding = new ShopstackClient();
+const account = await onboarding.signup({
+  accountType: "developer",
+  email: "developer@example.com",
+  onProgress: ({ state }) => console.log(state),
+  persistence: secureSignupPersistence,
+});
+
+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),
+});
+```
+
+`signup` generates retry state internally and returns the completed account
+identity only after the one-time credential is stored. It never returns the API
+key, recovery key, or polling token. Pass a secure persistence adapter for
+restart recovery and durable credential storage; never use browser storage.
+
+`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,128 @@
+---
+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
+```
+
+The command prompts for email and Personal or Developer account type. The user
+must open the time-limited verification link. No account or API key exists
+before verification. The CLI generates and privately stores its retry and
+polling capabilities before the request, polls signup, saves the verified key
+with mode `0600`, and prints none of those credentials. Rerunning
+`shopstack signup` automatically resumes the matching pending attempt after an
+interruption; `shopstack signup resume SIGNUP_ID` remains an explicit helper.
+
+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,21 +1,43 @@
 {
   "name": "shopstack",
-  "version": "0.1.0",
-  "description": "Shopstack CLI placeholder package while access is being rolled out.",
+  "version": "0.2.1",
+  "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"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jimbo132/shopstack-cli.git"
+  },
   "license": "MIT",
   "keywords": [
     "shopstack",
     "cli",
-    "coming-soon"
+    "checkout",
+    "payments"
   ]
 }