shopstack 0.2.0 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shopstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # shopstack
 
-Dependency-free JavaScript client and CLI for Shopstack's asynchronous checkout API.
+JavaScript client and CLI for Shopstack's asynchronous checkout API.
 
 ## Install
 
@@ -12,22 +12,25 @@ npm install -g shopstack
 
 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
+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.
 
-## Personal account
+## Verified signup
 
 ```bash
-shopstack signup user --email you@example.com
+shopstack signup
 ```
 
-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
+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 or polling capability. It checkpoints the pending signup before polling. If
-the command is interrupted, resume it with:
+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_...
@@ -36,7 +39,7 @@ shopstack signup resume sup_...
 ## Developer account and users
 
 ```bash
-shopstack signup developer --email developer@example.com
+shopstack signup
 shopstack users create --external-id customer-123 --profile customer-123
 ```
 
@@ -65,7 +68,7 @@ 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.
+`https://unpkg.com/shopstack@0.2.2/SKILL.md` with the release-pinned package.
 
 ## Connections
 
@@ -110,6 +113,12 @@ 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.
+
 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
@@ -125,6 +134,14 @@ Card values are never accepted as command-line flags.
 ```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,
 });
@@ -136,9 +153,18 @@ const result = await shopstack.runCheckout(checkoutRequest, {
 });
 ```
 
+`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.
+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.

package/SKILL.md

@@ -41,14 +41,16 @@ Never ask the model to print or relay a Shopstack API key. The CLI and MCP serve
 Start verified CLI signup:
 
 ```bash
-shopstack signup user --email user@example.com
-shopstack signup developer --email developer@example.com
+shopstack signup
 ```
 
-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.
+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:
 
@@ -107,12 +109,27 @@ 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.
 
-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 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.
 
 ## Respond at typed boundaries
 

package/bin/shopstack

@@ -5,6 +5,8 @@ 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.0",
-  "description": "Shopstack API client and command-line checkout tools.",
+  "version": "0.2.2",
+  "description": "Production Shopstack SDK and CLI for agentic checkout.",
   "type": "module",
   "exports": {
     ".": {
@@ -23,17 +23,41 @@
     "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": "node --test test",
+    "test:coverage": "node --test --experimental-test-coverage test",
+    "prepublishOnly": "npm run check"
   },
   "engines": {
     "node": ">=18"
   },
+  "repository": {
+    "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"
-  ]
+    "payments",
+    "agentic-commerce",
+    "agents"
+  ],
+  "devDependencies": {
+    "prettier": "3.6.2"
+  }
 }

package/src/cli.js

@@ -4,25 +4,50 @@ import { createInterface } from "node:readline/promises";
 import { ShopstackClient } from "./client.js";
 import { ConfigStore } from "./config.js";
 
-const HELP = `Shopstack
+const VERSION = "0.2.2";
+
+const HELP = `Shopstack CLI ${VERSION}
+
+Usage:
+  shopstack <command> [options]
 
 Account setup:
+  shopstack signup
+    # Create or resume an email-verified Personal or Developer profile.
   shopstack signup user --email EMAIL
+    # Create a Personal profile without interactive account-type prompts.
   shopstack signup developer --email EMAIL
+    # Create a Developer management profile without interactive prompts.
   shopstack signup resume SIGNUP_ID
+    # Resume a known pending email-verification flow.
   shopstack users create --external-id ID [--profile NAME]
+    # Create an independently scoped user from a Developer profile.
   shopstack profiles list
+    # List local profiles without printing their credentials.
   shopstack profiles use NAME
+    # Select the profile used by later commands.
 
 Payment connection:
   shopstack connect list
+    # Inspect payment connections for the active user profile.
   shopstack connect link
+    # Connect Link Agentic Wallet in the trusted browser flow.
 
 Checkout:
   shopstack checkout create --file checkout.json
+    # Create a checkout and return control immediately.
   shopstack checkout run --file checkout.json
+    # Create, monitor, and complete a checkout interactively.
   shopstack checkout get CHECKOUT_ID
+    # Read the canonical current checkout state.
   shopstack checkout cancel CHECKOUT_ID
+    # Cancel a checkout that has not reached a terminal state.
+
+Options:
+  -h, --help
+    # Show this command reference.
+  -v, --version
+    # Print the installed Shopstack CLI version.
 `;
 
 function parseOptions(args, allowed) {
@@ -54,6 +79,11 @@ function required(options, name) {
   return value;
 }
 
+function isAffirmative(value) {
+  const answer = String(value).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+
 function writeJson(stream, value) {
   stream.write(`${JSON.stringify(value, null, 2)}\n`);
 }
@@ -145,9 +175,72 @@ async function saveVerifiedSignup(result, profileName, configStore) {
   );
 }
 
+function signupPersistence(configStore, profileName) {
+  return {
+    async loadPending(input) {
+      return typeof configStore.findPendingSignup === "function"
+        ? configStore.findPendingSignup(input)
+        : undefined;
+    },
+    async savePending(state) {
+      await configStore.savePendingSignup({ ...state, profile: profileName });
+    },
+    async completePending(state, result) {
+      const pendingId = state.attemptId ?? state.signupId ?? state.id;
+      if (typeof configStore.completePendingSignup === "function") {
+        await configStore.completePendingSignup(pendingId, profileName, result);
+        return;
+      }
+      await saveVerifiedSignup(result, profileName, configStore);
+      await configStore.deletePendingSignup(pendingId);
+    },
+    async deletePending(state) {
+      await configStore.deletePendingSignup(
+        state.attemptId ?? state.signupId ?? state.id,
+      );
+    },
+  };
+}
+
+async function reportSignupProgress(progress, stream) {
+  switch (progress.state) {
+    case "email_sent":
+      stream.write("Verification email sent.\n");
+      return;
+    case "waiting":
+      stream.write("Waiting for verification...\n");
+      return;
+    case "verified":
+      stream.write("✓ Email verified\n");
+      return;
+    case "complete":
+      stream.write("✓ Shopstack account created\n");
+      stream.write("✓ Credentials saved securely\n");
+      return;
+    case "expired":
+      stream.write("Signup expired. Start again to receive a new email.\n");
+      return;
+    case "rate_limited":
+      stream.write(
+        "Signup is rate-limited. Retry after the indicated delay.\n",
+      );
+      return;
+    case "conflict":
+      stream.write("Signup retry state conflicted and was cleared.\n");
+      return;
+    case "retryable_failure":
+      stream.write(
+        "Signup paused after a retryable failure. Run signup again to resume.\n",
+      );
+      return;
+    default:
+      return;
+  }
+}
+
 async function activeClient(dependencies, requiredKind = "user") {
   const profile = await dependencies.configStore.activeProfile();
-  const environmentKey = process.env.SHOPSTACK_API_KEY;
+  const environmentKey = dependencies.env.SHOPSTACK_API_KEY;
   const apiKey = environmentKey || profile?.apiKey;
   const keyType = environmentKey ? requiredKind : profile?.keyType;
   if (!apiKey)
@@ -158,7 +251,7 @@ async function activeClient(dependencies, requiredKind = "user") {
   return {
     client: dependencies.clientFactory({
       apiKey,
-      baseUrl: process.env.SHOPSTACK_API_URL,
+      baseUrl: dependencies.env.SHOPSTACK_API_URL,
     }),
     profile,
   };
@@ -175,13 +268,23 @@ export async function runCli(args, supplied = {}) {
     stderr: process.stderr,
     stdin: process.stdin,
     stdout: process.stdout,
+    env: process.env,
     ...supplied,
   };
   const [group, action, ...rest] = args;
-  if (group === undefined || group === "help" || group === "--help") {
+  if (
+    group === undefined ||
+    group === "help" ||
+    group === "--help" ||
+    group === "-h"
+  ) {
     dependencies.stdout.write(HELP);
     return;
   }
+  if (group === "--version" || group === "-v") {
+    dependencies.stdout.write(`${VERSION}\n`);
+    return;
+  }
 
   if (group === "signup") {
     if (action === "resume") {
@@ -190,65 +293,130 @@ export async function runCli(args, supplied = {}) {
       }
       const pending = await dependencies.configStore.pendingSignup(rest[0]);
       if (pending === undefined) {
-        throw new Error("That signup is not present in the local profile store.");
+        throw new Error(
+          "That signup is not present in the local profile store.",
+        );
       }
       const client = dependencies.clientFactory({
-        baseUrl: process.env.SHOPSTACK_API_URL,
+        baseUrl: dependencies.env.SHOPSTACK_API_URL,
+      });
+      const result = await client.signup({
+        accountType: pending.accountType,
+        email: pending.email,
+        onProgress: (progress) =>
+          reportSignupProgress(progress, dependencies.stderr),
+        persistence: signupPersistence(
+          dependencies.configStore,
+          pending.profile,
+        ),
       });
-      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") {
+    if (action !== undefined && action !== "user" && action !== "developer") {
       throw new Error(
         "Use `shopstack signup user` or `shopstack signup developer`.",
       );
     }
+    const signupArgs = action === undefined ? [] : rest;
     const { options, positional } = parseOptions(
-      rest,
+      signupArgs,
       new Set(["email", "profile"]),
     );
     if (positional.length > 0) throw new Error("Unexpected signup argument.");
-    const email = required(options, "email");
+    const pendingCandidates =
+      action === undefined &&
+      typeof dependencies.configStore.pendingSignups === "function"
+        ? await dependencies.configStore.pendingSignups()
+        : [];
+    const resumable =
+      pendingCandidates.length === 1 ? pendingCandidates[0] : undefined;
+    let accountType;
+    let email;
+    if (resumable !== undefined) {
+      accountType = resumable.accountType;
+      email = resumable.email;
+      dependencies.stderr.write("Resuming pending signup.\n");
+    } else if (action === undefined) {
+      email = String(await visiblePrompt("Email: ", dependencies)).trim();
+      if (email.length === 0) throw new Error("Email is required.");
+      const selected = String(
+        await visiblePrompt(
+          "Account type (Personal / Developer): ",
+          dependencies,
+        ),
+      )
+        .trim()
+        .toLowerCase();
+      if (selected === "personal" || selected === "user") {
+        accountType = "personal";
+      } else if (selected === "developer") {
+        accountType = "developer";
+      } else {
+        throw new Error("Account type must be Personal or Developer.");
+      }
+    } else {
+      accountType = action === "user" ? "personal" : "developer";
+      email = required(options, "email");
+    }
     const client = dependencies.clientFactory({
-      baseUrl: process.env.SHOPSTACK_API_URL,
+      baseUrl: dependencies.env.SHOPSTACK_API_URL,
     });
-    const accountType = action === "user" ? "personal" : "developer";
     const profileName =
-      options.profile ?? (action === "developer" ? "developer" : "default");
-    const signup = await client.startAccountSignup({
+      options.profile ??
+      resumable?.profile ??
+      (accountType === "developer" ? "developer" : "default");
+    const result = await client.signup({
       accountType,
       email,
+      onProgress: (progress) =>
+        reportSignupProgress(progress, dependencies.stderr),
+      persistence: signupPersistence(dependencies.configStore, profileName),
     });
-    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,
     });
+    if (accountType === "developer") {
+      dependencies.stderr.write(
+        "The developer management credential cannot run user checkouts. Create a user profile with `shopstack users create --external-id ID`.\n",
+      );
+      if (
+        action === undefined &&
+        isAffirmative(
+          await visiblePrompt(
+            "Create the first developer-owned user now? (y/N): ",
+            dependencies,
+          ),
+        )
+      ) {
+        const externalId = String(
+          await visiblePrompt("User external ID: ", dependencies),
+        ).trim();
+        if (externalId.length === 0) {
+          throw new Error("User external ID is required.");
+        }
+        const { client: developerClient, profile } = await activeClient(
+          dependencies,
+          "developer",
+        );
+        const user = await developerClient.createUser({ externalId });
+        await dependencies.configStore.saveProfile(
+          externalId,
+          {
+            accountId: profile.accountId,
+            apiKey: user.api_key,
+            keyType: "user",
+            userId: user.id,
+          },
+          { activate: true },
+        );
+        writeJson(dependencies.stdout, sanitizedUserResult(user, externalId));
+      }
+    }
     return;
   }
 
@@ -324,6 +492,11 @@ export async function runCli(args, supplied = {}) {
     const { client } = await activeClient(dependencies, "user");
     const request = await dependencies.readJsonFile(required(options, "file"));
     const result = await client.runCheckout(request, {
+      onCreated: (checkout) => {
+        if (typeof checkout.live_view_url === "string") {
+          dependencies.stderr.write(`Live view: ${checkout.live_view_url}\n`);
+        }
+      },
       onProgress: (checkout) => {
         const intent =
           checkout.intent?.name === undefined
@@ -383,4 +556,4 @@ export async function runCli(args, supplied = {}) {
   throw new Error("Unknown command. Run `shopstack help`.");
 }
 
-export { HELP };
+export { HELP, VERSION };