shopstack 0.3.0 → 0.3.2

package/README.md

@@ -6,9 +6,9 @@ guest restaurant reservations.
 ## Install
 
 ```bash
-npm install shopstack@0.3.0
+npm install shopstack@0.3.2
 # or
-npm install -g shopstack@0.3.0
+npm install -g shopstack@0.3.2
 ```
 
 Node.js 18 or newer is required.
@@ -18,12 +18,13 @@ 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.0` with `shopstack-mcp@0.2.0`.
+This preview release pairs `shopstack@0.3.2` with `shopstack-mcp@0.2.2`.
 Both packages use the `preview` distribution tag. The `latest` versions are
 unchanged. Use the exact versions above to install this release.
 
-Set `SHOPSTACK_API_URL` to the Shopstack API address supplied for your environment,
-including `/v1`. There is no staging or production default. Use a separate
+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.
 
@@ -34,18 +35,20 @@ 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. Existing profiles without an address need
-an explicit `SHOPSTACK_API_URL`; their keys and scopes are not changed.
+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 signup
+## Verified signup and sign-in
 
 ```bash
-shopstack signup
+shopstack login
 ```
 
 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
+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
@@ -76,7 +79,7 @@ Configure any stdio MCP client to run:
   "mcpServers": {
     "shopstack": {
       "command": "npx",
-      "args": ["-y", "shopstack-mcp@0.2.0"],
+      "args": ["-y", "shopstack-mcp@0.2.2"],
       "env": {
         "SHOPSTACK_API_URL": "https://shopstack-release-preview.shopstack.workers.dev/v1",
         "SHOPSTACK_CONFIG_FILE": "/absolute/private/path/shopstack-config.json"
@@ -107,7 +110,7 @@ one MCP server and three focused skills:
 - `shopstack-checkout` for checkout creation and monitoring;
 - `shopstack-onboarding` for verified signup and private local profiles.
 
-The plugin pins `shopstack-mcp@0.2.0`, which installs the matching
+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.
@@ -119,8 +122,12 @@ shopstack connect list
 shopstack connect link
 ```
 
-Link is currently the only persistent payment provider. Connecting it is
-optional.
+Link is currently the only persistent payment provider. Connecting it in advance
+is optional. Select `payment_provider: "link"` to prepare the cart first; at card
+issuance Shopstack returns the Link sign-in or approval URL and waits. After Link
+responds, checkout resumes automatically. No “done” message is needed. The CLI
+keeps watching; MCP agents use `wait_checkout_update` with the latest
+`presentation_revision`. Final order approval is still a separate step.
 
 ## Run a guest reservation
 
@@ -196,7 +203,7 @@ 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
+To use Link, with or without a prior connection, add `"payment_provider": "link"` to the
 request.
 
 Card values are never accepted as command-line flags.
@@ -234,7 +241,7 @@ restart recovery and durable credential storage; never use browser storage.
 omitted. Final payment approval is never inferred from a message or from
 supplying a card.
 
-Set `SHOPSTACK_API_URL` to select the intended Shopstack API and
+Optionally set `SHOPSTACK_API_URL` to override the hosted API and
 `SHOPSTACK_CONFIG_FILE` to select its private profile store.
 
 ## Release verification

package/SKILL.md

@@ -8,8 +8,8 @@ description: Use Shopstack to onboard a verified personal account or a developer
 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.
-Before signup, configure the issued API address, including `/v1`, through
-`SHOPSTACK_API_URL`; the release has no staging or production default. Use a
+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.
@@ -19,8 +19,8 @@ chat to fix an environment mismatch.
 For the JavaScript client and CLI:
 
 ```bash
-npm install shopstack@0.3.0
-npm install -g shopstack@0.3.0
+npm install shopstack@0.3.1
+npm install -g shopstack@0.3.1
 ```
 
 For MCP clients, configure the local stdio server:
@@ -30,7 +30,7 @@ For MCP clients, configure the local stdio server:
   "mcpServers": {
     "shopstack": {
       "command": "npx",
-      "args": ["-y", "shopstack-mcp@0.2.0"]
+      "args": ["-y", "shopstack-mcp@0.2.1"]
     }
   }
 }
@@ -67,7 +67,10 @@ 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 and temporary email are created only when booking. Cancel a confirmed
+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
@@ -80,12 +83,14 @@ reservation with the typed reservation cancellation operation.
 Start verified CLI signup:
 
 ```bash
-shopstack signup
+shopstack login
 ```
 
 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
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shopstack",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Shopstack API client and command-line checkout and reservation tools.",
   "type": "module",
   "exports": {

package/specs/openapi.json

@@ -23,7 +23,8 @@
     "/accounts": {
       "post": {
         "operationId": "startAccountSignup",
-        "summary": "Start verified personal or developer account signup",
+        "summary": "Start email-verified signup or sign-in",
+        "description": "A new email creates the selected account type after verification. An existing email signs in to the same account with a new profile key; other devices remain signed in. The requested account type must match the existing account. Suspended accounts and users remain blocked. No key is issued before verification, and the key is delivered once through the caller's private polling capability, never in the email page.",
         "security": [],
         "parameters": [
           {
@@ -45,7 +46,7 @@
         },
         "responses": {
           "202": {
-            "description": "Verification email accepted; no account or API key exists yet",
+            "description": "Verification email accepted; no new API key has been issued",
             "content": {
               "application/json": {
                 "schema": {
@@ -198,6 +199,26 @@
               }
             }
           },
+          "403": {
+            "description": "The verified account or implicit user is unavailable",
+            "content": {
+              "text/html": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "The requested account type does not match the verified existing account",
+            "content": {
+              "text/html": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
           "410": {
             "description": "Verification capability expired",
             "content": {
@@ -1843,6 +1864,12 @@
               "phone_number"
             ],
             "properties": {
+              "email": {
+                "type": "string",
+                "format": "email",
+                "maxLength": 254,
+                "description": "Optional booking contact email. When supplied, this exact trimmed address is used for the guest profile. Otherwise Shopstack creates a temporary inbox when booking. Do not ask for an email if it was omitted."
+              },
               "country": {
                 "type": "string",
                 "pattern": "^[A-Z]{2}$"
@@ -2358,7 +2385,8 @@
                 "minimum": 1
               },
               "status": {
-                "type": "string"
+                "type": "string",
+                "description": "Shopstack booking outcome, confirmed. Provider lifecycle labels are not returned as this status."
               }
             }
           }
@@ -2391,7 +2419,8 @@
                 "type": "string"
               },
               "status": {
-                "type": "string"
+                "type": "string",
+                "description": "Shopstack cancellation outcome, cancelled."
               }
             }
           }
@@ -2641,7 +2670,7 @@
           },
           "payment_provider": {
             "$ref": "#/components/schemas/PaymentProvider",
-            "description": "Optional. Select Link only when this user has an active Link connection; otherwise the checkout requests protected one-checkout card input at the payment form."
+            "description": "Optional. Select Link without connecting first. At card issuance the checkout returns a Link login or approval URL in required_input and waits. Omission requests protected one-checkout card input instead. Link approval does not approve final order submission."
           },
           "external_reference": {
             "type": "string",
@@ -2761,14 +2790,62 @@
         }
       },
       "RequiredInput": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "const": "payment_card"
+              }
+            }
+          },
+          {
+            "$ref": "#/components/schemas/LinkRequiredInput"
+          }
+        ]
+      },
+      "LinkRequiredInput": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Owner-private Link login or credential approval. Open the exact URL or approve in Link. This does not approve Shopstack order submission. The checkout resumes automatically after Link responds.",
         "required": [
-          "type"
+          "type",
+          "action",
+          "url",
+          "amount_cents",
+          "currency"
         ],
         "properties": {
           "type": {
-            "const": "payment_card"
+            "const": "link"
+          },
+          "action": {
+            "enum": [
+              "connect",
+              "approve"
+            ]
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "maxLength": 2048
+          },
+          "phrase": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "amount_cents": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 500000
+          },
+          "currency": {
+            "$ref": "#/components/schemas/Currency"
           }
         }
       },

package/src/cli.js

@@ -7,6 +7,9 @@ import { ConfigStore, resolveProfileBaseUrl } from "./config.js";
 const HELP = `Shopstack
 
 Account setup:
+  shopstack login
+  shopstack login user --email EMAIL
+  shopstack login developer --email EMAIL
   shopstack signup
   shopstack signup user --email EMAIL
   shopstack signup developer --email EMAIL
@@ -305,7 +308,7 @@ export async function runCli(args, supplied = {}) {
     return;
   }
 
-  if (group === "signup") {
+  if (group === "signup" || group === "login") {
     if (action === "resume") {
       if (rest.length !== 1) {
         throw new Error("Use `shopstack signup resume SIGNUP_ID`.");
@@ -646,6 +649,17 @@ export async function runCli(args, supplied = {}) {
           `[${checkout.status}]${intent} ${checkout.activity ?? ""}`.trimEnd() +
             "\n",
         );
+        if (checkout.required_input?.type === "link") {
+          const input = checkout.required_input;
+          dependencies.stderr.write(
+            `${input.action === "connect" ? "Connect Link" : "Approve in Link"}: ${input.url}\n` +
+              `Amount: ${input.currency} ${(input.amount_cents / 100).toFixed(2)}\n` +
+              (input.action === "connect" && input.phrase
+                ? `Code: ${input.phrase}\n`
+                : "") +
+              "The checkout resumes automatically. Final order approval is separate.\n",
+          );
+        }
       },
       approve: async (approval) => {
         const summary = [

package/src/client.d.ts

@@ -40,6 +40,8 @@ export interface CreateCheckoutRequest {
 
 export interface ReservationDiner {
   country: string;
+  /** Optional booking contact address. If omitted, Shopstack creates a temporary inbox. */
+  email?: string;
   first_name: string;
   last_name: string;
   phone_number: string;
@@ -136,7 +138,17 @@ export interface Checkout {
   item_url: string;
   /** Present this exact owner-only URL verbatim. Never reconstruct its token. */
   live_view_url?: string;
-  required_input?: { type: "payment_card" };
+  required_input?:
+    | { type: "payment_card" }
+    | {
+        type: "link";
+        action: "connect" | "approve";
+        /** Owner-private Link URL. Present it verbatim; never reconstruct it. */
+        url: string;
+        phrase?: string;
+        amount_cents: number;
+        currency: string;
+      };
   approval?: PaymentApproval;
   result?: Record<string, unknown>;
   failure?: Record<string, unknown>;

package/src/client.js

@@ -1,6 +1,6 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import { readReservationProgress } from "./reservation-progress.js";
-import { resolveProfileBaseUrl } from "./config.js";
+import { DEFAULT_API_URL, resolveProfileBaseUrl } from "./config.js";
 import { checkoutMonitor } from "./checkout-monitor.js";
 
 const TERMINAL_STATUSES = new Set(["complete", "failed", "cancelled"]);
@@ -42,7 +42,7 @@ function delay(milliseconds) {
 export class ShopstackClient {
   constructor({
     apiKey,
-    baseUrl = process.env.SHOPSTACK_API_URL,
+    baseUrl = process.env.SHOPSTACK_API_URL ?? DEFAULT_API_URL,
     fetch: fetchImplementation = globalThis.fetch,
     webSocket = globalThis.WebSocket,
   } = {}) {
@@ -576,7 +576,7 @@ export class ShopstackClient {
         current.intent?.name,
         current.intent?.phase,
         current.intent?.updated_at,
-        current.required_input?.type,
+        current.required_input,
         current.approval?.id,
       ]);
       if (fingerprint === progressFingerprint) return;
@@ -597,6 +597,12 @@ export class ShopstackClient {
         }
         checkout = await this.getCheckout(checkout.id);
         await publishProgress(checkout);
+        if (
+          checkout.required_input?.type === "link" &&
+          typeof options.onProgress !== "function"
+        ) {
+          return checkout;
+        }
         if (
           checkout.required_input?.type === "payment_card" &&
           handledPaymentRevision !== checkout.revision

package/src/config.d.ts

@@ -1,3 +1,5 @@
+export const DEFAULT_API_URL: string;
+
 export interface ShopstackProfile {
   accountId: string;
   apiKey: string;

package/src/config.js

@@ -2,6 +2,9 @@ import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
+export const DEFAULT_API_URL =
+  "https://shopstack-release-preview.shopstack.workers.dev/v1";
+
 export function resolveProfileBaseUrl(profile, selectedBaseUrl) {
   const saved = profile?.baseUrl?.replace(/\/+$/u, "");
   const selected = selectedBaseUrl?.replace(/\/+$/u, "");
@@ -10,7 +13,7 @@ export function resolveProfileBaseUrl(profile, selectedBaseUrl) {
       "This profile belongs to a different Shopstack API. Select its endpoint or use a separate profile store.",
     );
   }
-  return saved ?? selected;
+  return saved ?? selected ?? DEFAULT_API_URL;
 }
 
 export function defaultConfigPath() {