shopstack 0.2.6 → 0.3.1

package/README.md

@@ -1,42 +1,69 @@
 # shopstack
 
-JavaScript client and CLI for Shopstack's asynchronous checkout API.
+Dependency-free JavaScript client and CLI for Shopstack checkouts and guided
+guest restaurant reservations.
 
 ## Install
 
 ```bash
-npm install shopstack
+npm install shopstack@0.3.1
 # or
-npm install -g shopstack
+npm install -g shopstack@0.3.1
 ```
 
 Node.js 18 or newer is required.
 
-The CLI and client default to Shopstack's production API at
-`https://api.shopstack.ai/v1`. Set
-`SHOPSTACK_API_URL` only when targeting a different Shopstack environment.
+`checkout run` uses WebSocket update notifications on runtimes that provide
+WebSocket (Node.js 22 or newer). It reads the authenticated checkout resource
+after each notification. Older runtimes, or a failed socket connection, use the
+bounded HTTP update wait. The one-time socket token is never placed in a URL.
+
+This preview release pairs `shopstack@0.3.1` with `shopstack-mcp@0.2.1`.
+Both packages use the `preview` distribution tag. The `latest` versions are
+unchanged. Use the exact versions above to install this release.
+
+The CLI and MCP use `https://shopstack-release-preview.shopstack.workers.dev/v1`
+by default. No API URL setting is needed for this hosted release. Set
+`SHOPSTACK_API_URL` only to select another environment. Use a separate
+`SHOPSTACK_CONFIG_FILE` for each environment. Both features use that one API and
+verified profile; customers do not run a Worker, model, database, or proxy.
+
+```sh
+# Isolated hosted release preview; not staging or production.
+export SHOPSTACK_API_URL="https://shopstack-release-preview.shopstack.workers.dev/v1"
+export SHOPSTACK_CONFIG_FILE="/absolute/private/path/shopstack-config.json"
+```
+
+New profiles remember their API address. A conflicting environment override
+fails before the credential is sent. For a legacy profile without an address,
+set its original `SHOPSTACK_API_URL` if it does not belong to the hosted release.
 
-## Verified login
+## Verified signup and sign-in
 
 ```bash
-shopstack login [--email EMAIL] [--profile NAME] [--account-type personal|developer]
+shopstack login
 ```
 
-The command asks for an email when `--email` is absent. It uses the `default`
-profile and Personal account preference unless flags select other values. An
-existing account keeps its current account type. A new email creates the
-requested account type. The command waits for up to 15 minutes while you open
-the verification email. It does not issue a new API key until the link is
-consumed. The CLI privately persists all retry and polling capabilities before
-the first request, then retrieves a new key after verification and stores it in
+The command asks for email and Personal or Developer account type. It starts a
+15-minute verification and waits while you open the email. A new email creates
+an account; an existing email signs in to the same account with a new device
+key. Other devices remain signed in. `shopstack signup` remains an alias. No
+new key is issued until verification. 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 login`; the matching pending attempt resumes automatically.
+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 login
+shopstack signup
 shopstack users create --external-id customer-123 --profile customer-123
 ```
 
@@ -52,22 +79,41 @@ Configure any stdio MCP client to run:
   "mcpServers": {
     "shopstack": {
       "command": "npx",
-      "args": ["-y", "shopstack-mcp"]
+      "args": ["-y", "shopstack-mcp@0.2.1"],
+      "env": {
+        "SHOPSTACK_API_URL": "https://shopstack-release-preview.shopstack.workers.dev/v1",
+        "SHOPSTACK_CONFIG_FILE": "/absolute/private/path/shopstack-config.json"
+      }
     }
   }
 }
 ```
 
-The MCP server has one verified login tool, manages local profiles,
+Use a different API address only when Shopstack supplies one for your environment.
+That command uses the coordinated packages. See `packages/mcp/README.md` for the release
+gate and local development setup. The old source-only launcher is not evidence
+that a registry installation contains the current SDK.
+
+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. Checkout creation returns the exact live-view URL as a clickable MCP
-resource; `get_live_view` replaces a lost one-time link for an active checkout.
-It exposes status, activity, and the latest bounded mechanical intent phase. It
-deliberately has no card-input or payment-approval tool.
+checkouts. It also creates, reads, continues, and cancels reservation
+conversations. It exposes status, activity, and the latest bounded mechanical
+intent phase. It deliberately has no card-input or payment-approval tool.
+
+## Codex plugin
 
-The canonical agent skill ships as `SKILL.md` in this package. After
-publication it is available at
-`https://unpkg.com/shopstack@0.2.5/SKILL.md` with the release-pinned package.
+The repository contains one Shopstack plugin in `plugins/shopstack`. It uses
+one MCP server and three focused skills:
+
+- `shopstack-reservations` for natural restaurant search, selection, booking,
+  and cancellation;
+- `shopstack-checkout` for checkout creation and monitoring;
+- `shopstack-onboarding` for verified signup and private local profiles.
+
+The plugin pins `shopstack-mcp@0.2.1`, which installs the matching
+reservation-capable `shopstack` client. Configure the API address
+before starting the plugin or use a profile already bound to that API. The existing top-level
+`SKILL.md` remains in the npm client package for compatibility.
 
 ## Connections
 
@@ -77,10 +123,43 @@ shopstack connect link
 ```
 
 Link is currently the only persistent payment provider. Connecting it is
-optional. `shopstack connect link` opens the HTTPS Link setup page, displays the
-confirmation phrase, and checks the connection every five seconds for up to
-five minutes. It prints `Link connected` when the connection is ready. If a
-browser cannot open automatically, use the exact URL printed in the terminal.
+optional.
+
+## Run a guest reservation
+
+Create `reservation.json` with the diner details, location name, and a detailed
+natural-language request. Do not add coordinates or a time zone:
+
+```json
+{
+  "diner": {
+    "country": "US",
+    "first_name": "Ada",
+    "last_name": "Lovelace",
+    "phone_number": "+12125550123"
+  },
+  "location": {
+    "query": "Times Square, New York"
+  },
+  "request": "Dinner tomorrow for two around 7:30 PM. Quiet Italian, vegetarian choices required, about $80 per person."
+}
+```
+
+Then run:
+
+```bash
+shopstack reservation run --file reservation.json
+```
+
+The CLI asks natural follow-up questions and displays current location,
+restaurant, and time IDs. It shows the exact locked booking summary before it
+asks for confirmation. A clear confirmation is sent through the same
+reservation message route; there is no separate reservation approval command.
+Use `shopstack reservation get`, `message`, or `cancel` for individual API
+operations. Use `shopstack reservation options RESERVATION_ID` for another
+stored page and `shopstack reservation option RESERVATION_ID OPTION_ID` for
+full provider details. These reads do not repeat model inference or restaurant
+search.
 
 ## Run a checkout
 
@@ -115,19 +194,6 @@ Then run:
 shopstack checkout run --file checkout.json
 ```
 
-The CLI prints the private owner live-view URL as soon as checkout creation
-succeeds. Do not redirect it into shared logs or expose it to a model. The page
-is view-only unless the model explicitly requests human assistance; while that
-request is active, one owner viewer can use **Take control** and **Return
-control**. **Stop** is always available and never approves payment.
-
-Treat the printed URL as opaque and open it exactly as returned, including its
-`#token=...` fragment. If that fragment is lost while the checkout is active,
-run `shopstack checkout view CHECKOUT_ID` to receive a replacement URL. The
-replacement disconnects an older viewer session but does not restart checkout.
-Omit `model_handle` to use the production GLM route. Set it to `qwen` only when
-you explicitly need the fixed Qwen comparison route.
-
 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
@@ -144,11 +210,11 @@ Card values are never accepted as command-line flags.
 import { ShopstackClient } from "shopstack";
 
 const onboarding = new ShopstackClient();
-const account = await onboarding.login({
+const account = await onboarding.signup({
   accountType: "developer",
   email: "developer@example.com",
   onProgress: ({ state }) => console.log(state),
-  persistence: secureLoginPersistence,
+  persistence: secureSignupPersistence,
 });
 
 const shopstack = new ShopstackClient({
@@ -162,18 +228,36 @@ const result = await shopstack.runCheckout(checkoutRequest, {
 });
 ```
 
-`login` generates retry state internally and returns the authenticated account
-identity only after the new credential is stored. It never returns the API
+`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. While the checkout is active, the CLI and client use a one-time
-checkout-scoped WebSocket capability for change notification and always fetches
-the canonical resource after a signal. It falls back to bounded revision-aware
-HTTP waiting, then to fixed polling when either newer transport is unavailable.
-Neither the API key nor WebSocket capability is placed in the socket URL.
-
-Set `SHOPSTACK_API_URL` to target a different Shopstack API and
-`SHOPSTACK_CONFIG_FILE` to relocate CLI profiles.
+supplying a card.
+
+Optionally set `SHOPSTACK_API_URL` to override the hosted API and
+`SHOPSTACK_CONFIG_FILE` to select its private profile store.
+
+## Release verification
+
+```sh
+npm test
+npm run test:types
+npm run test:coverage
+npm run test:packed
+```
+
+The packed test creates actual SDK and MCP archives, installs them in a clean
+directory, and runs both features through TCP HTTP and stdio MCP. It checks
+verified signup, shared private profiles, exact package versions, progress,
+restaurant details, stale revisions, and single-attempt failure handling.
+Only package dependency downloads use the public network. The API is a local
+fixture; this does not create a real booking or order.
+The coverage gate needs Node.js 22.7 or newer and excludes test files. It enforces
+80% source line/function coverage and 75% branch coverage.
+
+Release order: validate the hosted preview, freeze the SDK archive, publish that
+exact SDK archive, then publish the matching MCP archive. Do not publish only one
+package or promote the hosted API before the release checks pass.

package/SKILL.md

@@ -1,19 +1,26 @@
 ---
 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.
+description: Use Shopstack to onboard a verified personal account or a developer with independently scoped end users, run guided guest restaurant reservations, inspect optional Link connectivity, and run asynchronous online checkouts. Trigger for restaurant search or booking, buying products, automating checkout, integrating Shopstack into an agent, or managing developer-owned 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.
 
+Use one Shopstack API and verified user profile for checkout and reservations.
+The CLI and MCP default to `https://shopstack-release-preview.shopstack.workers.dev/v1`.
+Use `SHOPSTACK_API_URL` only to select a different API. Use a
+separate private profile store for each environment. New profiles save their API
+address and reject a conflicting override. Never ask the user to paste a key in
+chat to fix an environment mismatch.
+
 ## Install
 
 For the JavaScript client and CLI:
 
 ```bash
-npm install shopstack
-npm install -g shopstack
+npm install shopstack@0.3.1
+npm install -g shopstack@0.3.1
 ```
 
 For MCP clients, configure the local stdio server:
@@ -23,13 +30,48 @@ For MCP clients, configure the local stdio server:
   "mcpServers": {
     "shopstack": {
       "command": "npx",
-      "args": ["-y", "shopstack-mcp"]
+      "args": ["-y", "shopstack-mcp@0.2.1"]
     }
   }
 }
 ```
 
 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.
+The install commands require the coordinated published release. Use the
+verified release archives while it is unpublished; an old registry package is
+not equivalent to the current source.
+
+## Run a guest restaurant reservation
+
+Give Shopstack the diner name, phone number, two-letter country, a location
+name, and one detailed natural-language request. Do not supply coordinates or a
+time zone. Shopstack resolves the valid OpenTable location and its time zone.
+Include as much useful detail as possible: date, local time or range, party
+size, cuisine, budget, travel distance, atmosphere, dietary needs, seating,
+accessibility, occasion, and anything to avoid.
+
+```bash
+shopstack reservation run --file reservation.json
+```
+
+Shopstack resolves the location name, asks a natural follow-up when needed, and
+returns the first six compact observed restaurants. Use
+`list_reservation_options` or `shopstack reservation options` for another page.
+Use `get_reservation_option` or `shopstack reservation option` for the exact
+stored provider description, photos, facts, and time IDs. These reads do not
+run another model inference or OpenTable search. Preserve every current
+`option_id` and `time_id`. A new search makes older IDs stale.
+
+Selection rechecks availability, locks the slot, and returns one exact booking
+summary. Send a clear confirmation only when the user confirms that exact
+summary. This confirmation is an ordinary reservation message and can create
+the booking. There is no separate reservation approval endpoint or MCP tool.
+An ambiguous reply must not be treated as confirmation. The anonymous guest
+profile is created only when booking. Pass optional `diner.email` when the user
+supplies it; that is the guest contact address. Otherwise omit it and Shopstack
+creates a temporary inbox when booking. Never require the user to give a
+restaurant email. Cancel a confirmed
+reservation with the typed reservation cancellation operation.
 
 ## Choose the account shape
 
@@ -38,22 +80,23 @@ Never ask the model to print or relay a Shopstack API key. The CLI and MCP serve
 - 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 login:
+Start verified CLI signup:
 
 ```bash
-shopstack login [--email EMAIL] [--profile NAME] [--account-type personal|developer]
+shopstack login
 ```
 
-The command prompts only for a missing email. Personal and `default` are the
-default account preference and profile. An existing account keeps its current
-type. A new email creates the requested account type. The user must open the
-time-limited verification link. The CLI generates and privately stores its
-retry and polling capabilities before the request, polls login, saves the new
-key with mode `0600`, and prints none of those credentials. Rerunning
-`shopstack login` automatically resumes the matching pending attempt after an
-interruption.
+The command prompts for email and Personal or Developer account type. The user
+must open the time-limited verification link. A new email creates an account;
+an existing email signs in to the same account and preserves other device keys.
+The selected account type must match. `shopstack signup` is also supported.
+No new API key is issued 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 login, create an end user:
+After developer signup, create an end user:
 
 ```bash
 shopstack users create --external-id customer-123 --profile customer-123
@@ -70,11 +113,6 @@ shopstack connect list
 shopstack connect link
 ```
 
-The Link command opens the HTTPS setup page, displays the confirmation phrase,
-and checks every five seconds for up to five minutes. Continue only after it
-prints `Link connected` and reports `checkout_ready: true`. If the browser does
-not open automatically, open the exact URL printed in the terminal.
-
 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.
@@ -115,39 +153,18 @@ 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`;
-- `presentation_revision`: the monotonic revision for user-visible checkout state;
 - `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.
 
-The CLI and JavaScript client subscribe with a one-time checkout-scoped
-WebSocket capability. Each valid notification means the presentation revision
-changed; the client then fetches the canonical checkout before displaying or
-acting on it. The notification is not checkout state truth and never grants
-payment authority. The capability belongs in the WebSocket subprotocol, never
-the URL, logs, model context, or messages. If WebSocket delivery is unavailable,
-the client falls back to bounded HTTP waiting and then fixed polling.
-
-MCP and manual integrations poll every two seconds for `queued`, `started`, and
-`submitting`; every five seconds for `help_required` and `approval_required`;
-stop at `complete`, `failed`, or `cancelled`.
-
-The optional `live_view_url` is a private owner-viewer capability. Show it only
-to the initiating user. Do not store it in browser storage, analytics, logs,
-model context, or ordinary messages.
-
-Present `live_view_url` exactly as returned, including its fragment; never
-construct a viewer URL from the checkout ID. MCP returns it as a clickable
-resource link. If it is lost while the checkout is active, call
-`get_live_view` (or `shopstack checkout view CHECKOUT_ID`) once and present the
-replacement verbatim.
+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 with the owning user's credential.
+- 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.

package/bin/shopstack

@@ -5,8 +5,6 @@ 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.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
   process.exitCode = 1;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "shopstack",
-  "version": "0.2.6",
-  "description": "Production Shopstack SDK and CLI for agentic checkout.",
+  "version": "0.3.1",
+  "description": "Shopstack API client and command-line checkout and reservation tools.",
   "type": "module",
   "exports": {
     ".": {
@@ -11,24 +11,26 @@
     "./config": {
       "types": "./src/config.d.ts",
       "import": "./src/config.js"
-    }
+    },
+    "./openapi": "./specs/openapi.json"
   },
   "types": "./src/client.d.ts",
   "files": [
     "SKILL.md",
     "bin",
+    "specs",
     "src"
   ],
   "bin": {
     "shopstack": "bin/shopstack"
   },
   "scripts": {
-    "check": "npm run format:check && npm run test:coverage",
-    "format:check": "prettier --check .",
     "shopstack": "node ./bin/shopstack",
-    "test": "node --test test/*.test.js",
-    "test:coverage": "node --test --experimental-test-coverage test/*.test.js",
-    "prepublishOnly": "npm run check"
+    "test": "node --test",
+    "test:packed": "SHOPSTACK_PACKED_RELEASE_TEST=1 node --test test/packed-release.test.js",
+    "test:types": "tsc --noEmit --strict --module nodenext --moduleResolution nodenext --target es2022 --lib es2022,dom type-tests/public-contract.ts",
+    "sync:contract": "node scripts/sync-contract.mjs",
+    "test:coverage": "node --experimental-test-coverage --test --test-coverage-include='src/*.js' --test-coverage-include='packages/mcp/src/*.js' --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=75"
   },
   "engines": {
     "node": ">=18"
@@ -37,27 +39,15 @@
     "type": "git",
     "url": "git+https://github.com/jimbo132/shopstack-cli.git"
   },
-  "homepage": "https://github.com/jimbo132/shopstack-cli#readme",
-  "bugs": {
-    "url": "https://github.com/jimbo132/shopstack-cli/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "sideEffects": false,
-  "dependencies": {
-    "ws": "8.21.3"
-  },
   "license": "MIT",
   "keywords": [
     "shopstack",
     "cli",
     "checkout",
-    "payments",
-    "agentic-commerce",
-    "agents"
+    "payments"
   ],
   "devDependencies": {
-    "prettier": "3.6.2"
+    "typescript": "6.0.3",
+    "yaml": "2.9.0"
   }
 }