shopstack 0.2.0 → 0.2.2

package/src/client.d.ts

@@ -2,6 +2,7 @@ export interface ShopstackClientOptions {
   apiKey?: string;
   baseUrl?: string;
   fetch?: typeof fetch;
+  webSocket?: typeof WebSocket;
 }
 
 export interface PaymentCard {
@@ -33,6 +34,7 @@ export interface Checkout {
     | "failed"
     | "cancelled";
   revision: number;
+  presentation_revision: number;
   activity: string;
   intent?: {
     name: string;
@@ -40,6 +42,7 @@ export interface Checkout {
     updated_at: string;
   };
   item_url: string;
+  live_view_url?: string;
   required_input?: { type: "payment_card" };
   approval?: PaymentApproval;
   result?: Record<string, unknown>;
@@ -51,6 +54,7 @@ export interface Checkout {
 
 export interface RunCheckoutOptions {
   idempotencyKey?: string;
+  onCreated?(checkout: Checkout): void | Promise<void>;
   pollIntervalMs?: number;
   timeoutMs?: number;
   onProgress?(checkout: Checkout): void | Promise<void>;
@@ -66,6 +70,14 @@ export interface RunCheckoutOptions {
   ): string | Promise<string | undefined> | undefined;
 }
 
+export interface CheckoutUpdateSubscription {
+  socket_url: string;
+  protocol: "shopstack.v1";
+  token: string;
+  expires_at: string;
+  presentation_revision: number;
+}
+
 export interface AccountSignupStarted {
   id: string;
   account_type: "personal" | "developer";
@@ -89,14 +101,58 @@ export interface VerifiedAccountSignup {
 export interface SignupOptions {
   accountType: "personal" | "developer";
   email: string;
-  idempotencyKey?: string;
   pollIntervalMs?: number;
   timeoutMs?: number;
-  onVerificationRequired?(signup: Omit<AccountSignupStarted, "poll_token">):
-    | void
-    | Promise<void>;
+  persistence?: SignupPersistence;
+  onProgress?(progress: SignupProgress): void | Promise<void>;
+  onVerificationRequired?(
+    signup: Omit<AccountSignupStarted, "poll_token">,
+  ): void | Promise<void>;
+}
+
+export interface PendingSignupState {
+  accountType: "personal" | "developer";
+  attemptId: string;
+  email: string;
+  expiresAt?: string;
+  idempotencyKey: string;
+  pollToken?: string;
+  recoveryKey: string;
+  signupId?: string;
+}
+
+export interface SignupPersistence {
+  loadPending(input: {
+    accountType: "personal" | "developer";
+    email: string;
+  }): Promise<PendingSignupState | undefined>;
+  savePending(state: PendingSignupState): Promise<void>;
+  completePending(
+    state: PendingSignupState,
+    result: VerifiedAccountSignup,
+  ): Promise<void>;
+  deletePending(state: PendingSignupState): Promise<void>;
+}
+
+export interface SignupProgress {
+  state:
+    | "pending"
+    | "email_sent"
+    | "waiting"
+    | "verified"
+    | "expired"
+    | "rate_limited"
+    | "conflict"
+    | "retryable_failure"
+    | "complete";
+  account_type?: "personal" | "developer";
+  email?: string;
+  expires_at?: string;
+  key_type?: "user" | "developer";
 }
 
+export type CompletedAccountSignup = Omit<VerifiedAccountSignup, "api_key">;
+
 export class ShopstackApiError extends Error {
   code: string;
   requestId?: string;
@@ -108,20 +164,17 @@ export class ShopstackClient {
   startAccountSignup(input: {
     accountType: "personal" | "developer";
     email: string;
-    idempotencyKey?: string;
   }): Promise<AccountSignupStarted>;
   pollAccountSignup(
     signupId: string,
     pollToken: string,
-  ): Promise<
-    Omit<AccountSignupStarted, "poll_token"> | VerifiedAccountSignup
-  >;
+  ): Promise<Omit<AccountSignupStarted, "poll_token"> | VerifiedAccountSignup>;
   waitForAccountSignup(
     signupId: string,
     pollToken: string,
     options?: { pollIntervalMs?: number; timeoutMs?: number },
   ): Promise<VerifiedAccountSignup>;
-  signup(input: SignupOptions): Promise<VerifiedAccountSignup>;
+  signup(input: SignupOptions): Promise<CompletedAccountSignup>;
   createUser(input: {
     externalId: string;
     idempotencyKey?: string;
@@ -147,6 +200,14 @@ export class ShopstackClient {
     options?: { idempotencyKey?: string },
   ): Promise<Checkout>;
   getCheckout(checkoutId: string): Promise<Checkout>;
+  createCheckoutUpdateSubscription(
+    checkoutId: string,
+  ): Promise<CheckoutUpdateSubscription>;
+  waitForCheckoutUpdate(
+    checkoutId: string,
+    afterRevision: number,
+    waitSeconds?: number,
+  ): Promise<Checkout | undefined>;
   cancelCheckout(
     checkoutId: string,
     options?: { idempotencyKey?: string },

package/src/client.js

@@ -1,4 +1,5 @@
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
+import WebSocket from "ws";
 
 const TERMINAL_STATUSES = new Set(["complete", "failed", "cancelled"]);
 
@@ -16,17 +17,133 @@ function idempotencyKey(prefix) {
   return `${prefix}-${randomUUID()}`;
 }
 
+function signupRecoveryKey() {
+  return `signup_recovery_${randomBytes(32).toString("base64url")}`;
+}
+
+function signupAttemptKey(accountType, email) {
+  return `${accountType}\u0000${email.trim().toLowerCase()}`;
+}
+
 function delay(milliseconds) {
   return milliseconds <= 0
     ? Promise.resolve()
     : new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
+function presentationRevision(checkout) {
+  return Number.isInteger(checkout?.presentation_revision)
+    ? checkout.presentation_revision
+    : checkout.revision;
+}
+
+class CheckoutUpdateWatcher {
+  constructor(client, checkoutId) {
+    this.client = client;
+    this.checkoutId = checkoutId;
+    this.latestRevision = 0;
+    this.waiter = undefined;
+    this.socket = undefined;
+    this.unavailable = typeof client.WebSocket !== "function";
+  }
+
+  async connect() {
+    if (this.socket || this.unavailable) return;
+    try {
+      const subscription = await this.client.createCheckoutUpdateSubscription(
+        this.checkoutId,
+      );
+      const socket = new this.client.WebSocket(subscription.socket_url, [
+        subscription.protocol,
+        subscription.token,
+      ]);
+      this.socket = socket;
+      socket.addEventListener("message", (event) => {
+        let payload;
+        try {
+          payload = JSON.parse(String(event.data));
+        } catch {
+          return;
+        }
+        if (
+          payload?.type !== "checkout_changed" ||
+          !Number.isInteger(payload.presentation_revision) ||
+          payload.presentation_revision < 1 ||
+          typeof payload.terminal !== "boolean"
+        ) {
+          return;
+        }
+        this.latestRevision = Math.max(
+          this.latestRevision,
+          payload.presentation_revision,
+        );
+        this.waiter?.();
+      });
+      const unavailable = () => {
+        this.unavailable = true;
+        this.waiter?.();
+      };
+      socket.addEventListener("error", unavailable);
+      socket.addEventListener("close", unavailable);
+    } catch {
+      this.unavailable = true;
+    }
+  }
+
+  async wait(afterRevision, timeoutMs) {
+    await this.connect();
+    if (this.latestRevision > afterRevision) return { kind: "changed" };
+    if (!this.unavailable) {
+      const changed = await new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+          if (settled) return;
+          settled = true;
+          this.waiter = undefined;
+          clearTimeout(timer);
+          resolve(value);
+        };
+        this.waiter = () =>
+          settle(
+            this.latestRevision > afterRevision ? "changed" : "unavailable",
+          );
+        const timer = setTimeout(
+          () => settle("timeout"),
+          Math.max(1, Math.min(timeoutMs, 25_000)),
+        );
+      });
+      if (changed === "changed") return { kind: "changed" };
+      if (changed === "timeout") return { kind: "refresh" };
+    }
+    try {
+      const checkout = await this.client.waitForCheckoutUpdate(
+        this.checkoutId,
+        afterRevision,
+        Math.max(1, Math.min(25, Math.ceil(timeoutMs / 1_000))),
+      );
+      return checkout === undefined
+        ? { kind: "refresh" }
+        : { checkout, kind: "checkout" };
+    } catch {
+      return { kind: "unavailable" };
+    }
+  }
+
+  close() {
+    try {
+      this.socket?.close(1000, "Checkout monitoring complete");
+    } catch {
+      // Monitoring teardown must not alter the checkout result.
+    }
+  }
+}
+
 export class ShopstackClient {
   constructor({
     apiKey,
-    baseUrl = "https://shopstack-staging.shopstack.workers.dev/v1",
+    baseUrl = "https://api.shopstack.ai/v1",
     fetch: fetchImplementation = globalThis.fetch,
+    webSocket: webSocketImplementation = WebSocket,
   } = {}) {
     if (typeof baseUrl !== "string" || !/^https?:\/\//u.test(baseUrl)) {
       throw new TypeError("baseUrl must be an HTTP(S) URL");
@@ -37,6 +154,7 @@ export class ShopstackClient {
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/+$/u, "");
     this.fetch = fetchImplementation;
+    this.WebSocket = webSocketImplementation;
   }
 
   async request(
@@ -46,6 +164,7 @@ export class ShopstackClient {
       body,
       idempotencyKey: mutationKey,
       method = "GET",
+      signupRecoveryKey: recoveryKey,
     } = {},
   ) {
     const headers = new Headers({ Accept: "application/json" });
@@ -55,6 +174,7 @@ export class ShopstackClient {
     }
     if (body !== undefined) headers.set("Content-Type", "application/json");
     if (mutationKey) headers.set("Idempotency-Key", mutationKey);
+    if (recoveryKey) headers.set("Signup-Recovery-Key", recoveryKey);
     const response = await this.fetch(`${this.baseUrl}${path}`, {
       body: body === undefined ? undefined : JSON.stringify(body),
       headers,
@@ -88,11 +208,26 @@ export class ShopstackClient {
     return payload;
   }
 
-  startAccountSignup({ accountType, email, idempotencyKey: key } = {}) {
+  _startAccountSignup({
+    accountType,
+    email,
+    idempotencyKey: key,
+    recoveryKey,
+  }) {
     return this.request("/accounts", {
       body: { account_type: accountType, email },
-      idempotencyKey: key ?? idempotencyKey("account"),
+      idempotencyKey: key,
       method: "POST",
+      signupRecoveryKey: recoveryKey,
+    });
+  }
+
+  startAccountSignup({ accountType, email } = {}) {
+    return this._startAccountSignup({
+      accountType,
+      email,
+      idempotencyKey: idempotencyKey("account"),
+      recoveryKey: signupRecoveryKey(),
     });
   }
 
@@ -123,29 +258,135 @@ export class ShopstackClient {
   async signup({
     accountType,
     email,
-    idempotencyKey: key,
+    onProgress,
     onVerificationRequired,
+    persistence,
     pollIntervalMs = 2_000,
     timeoutMs = 15 * 60 * 1_000,
   } = {}) {
-    const signup = await this.startAccountSignup({
+    const normalizedEmail = email.trim().toLowerCase();
+    const memoryKey = signupAttemptKey(accountType, normalizedEmail);
+    this._pendingSignups ??= new Map();
+    const storage = persistence ?? {
+      completePending: async (state, result) => {
+        this.apiKey = result.api_key;
+        this._pendingSignups.delete(memoryKey);
+      },
+      deletePending: async () => this._pendingSignups.delete(memoryKey),
+      loadPending: async () => this._pendingSignups.get(memoryKey),
+      savePending: async (state) => {
+        this._pendingSignups.set(memoryKey, structuredClone(state));
+      },
+    };
+    const publish = async (state, details = {}) => {
+      if (typeof onProgress === "function")
+        await onProgress({ state, ...details });
+    };
+    let pending = await storage.loadPending({
       accountType,
-      email,
-      idempotencyKey: key,
+      email: normalizedEmail,
     });
-    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,
+    if (pending?.expiresAt && Date.parse(pending.expiresAt) <= Date.now()) {
+      await storage.deletePending(pending);
+      await publish("expired", {
+        account_type: accountType,
+        email: normalizedEmail,
       });
+      pending = undefined;
     }
-    return this.waitForAccountSignup(signup.id, signup.poll_token, {
-      pollIntervalMs,
-      timeoutMs,
+    pending ??= {
+      accountType,
+      attemptId: `attempt-${randomUUID()}`,
+      email: normalizedEmail,
+      idempotencyKey: idempotencyKey("account"),
+      recoveryKey: signupRecoveryKey(),
+    };
+    await storage.savePending(pending);
+    await publish("pending", {
+      account_type: accountType,
+      email: normalizedEmail,
     });
+    try {
+      if (!pending.signupId || !pending.pollToken) {
+        const started = await this._startAccountSignup({
+          accountType,
+          email: normalizedEmail,
+          idempotencyKey: pending.idempotencyKey,
+          recoveryKey: pending.recoveryKey,
+        });
+        pending = {
+          ...pending,
+          expiresAt: started.expires_at,
+          pollToken: started.poll_token,
+          signupId: started.id,
+        };
+        await storage.savePending(pending);
+        if (typeof onVerificationRequired === "function") {
+          await onVerificationRequired({
+            account_type: started.account_type,
+            email: started.email,
+            expires_at: started.expires_at,
+            id: started.id,
+            status: started.status,
+          });
+        }
+        await publish("email_sent", {
+          account_type: accountType,
+          email: normalizedEmail,
+          expires_at: started.expires_at,
+        });
+      }
+      await publish("waiting", {
+        account_type: accountType,
+        email: normalizedEmail,
+        expires_at: pending.expiresAt,
+      });
+      const result = await this.waitForAccountSignup(
+        pending.signupId,
+        pending.pollToken,
+        { pollIntervalMs, timeoutMs },
+      );
+      await storage.completePending(pending, result);
+      await publish("verified", {
+        account_type: accountType,
+        email: normalizedEmail,
+      });
+      await publish("complete", {
+        account_type: accountType,
+        email: normalizedEmail,
+        key_type: result.key_type,
+      });
+      const { api_key: _credential, ...completed } = result;
+      return completed;
+    } catch (error) {
+      if (error?.code === "signup_expired") {
+        await storage.deletePending(pending);
+        await publish("expired", {
+          account_type: accountType,
+          email: normalizedEmail,
+        });
+      } else if (error?.code === "rate_limited") {
+        await publish("rate_limited", {
+          account_type: accountType,
+          email: normalizedEmail,
+        });
+      } else if (
+        error?.code === "idempotency_conflict" ||
+        error?.code === "invalid_signup_recovery"
+      ) {
+        await storage.deletePending(pending);
+        await publish("conflict", {
+          account_type: accountType,
+          email: normalizedEmail,
+        });
+      } else {
+        await publish("retryable_failure", {
+          account_type: accountType,
+          email: normalizedEmail,
+        });
+      }
+      throw error;
+    }
   }
 
   createUser({ externalId, idempotencyKey: key } = {}) {
@@ -203,6 +444,22 @@ export class ShopstackClient {
     return this.request(`/checkout/${encodeURIComponent(checkoutId)}`);
   }
 
+  createCheckoutUpdateSubscription(checkoutId) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}/updates`, {
+      method: "POST",
+    });
+  }
+
+  waitForCheckoutUpdate(checkoutId, afterRevision, waitSeconds = 25) {
+    const query = new URLSearchParams({
+      after: String(afterRevision),
+      wait: String(waitSeconds),
+    });
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/updates?${query.toString()}`,
+    );
+  }
+
   cancelCheckout(checkoutId, { idempotencyKey: key } = {}) {
     return this.request(`/checkout/${encodeURIComponent(checkoutId)}/cancel`, {
       idempotencyKey: key ?? idempotencyKey("cancel"),
@@ -268,12 +525,16 @@ export class ShopstackClient {
     let checkout = await this.createCheckout(checkoutRequest, {
       idempotencyKey: options.idempotencyKey,
     });
+    if (typeof options.onCreated === "function") {
+      await options.onCreated(checkout);
+    }
     let progressFingerprint;
     const publishProgress = async (current) => {
       if (typeof options.onProgress !== "function") return;
       const fingerprint = JSON.stringify([
         current.status,
         current.revision,
+        current.presentation_revision,
         current.activity,
         current.intent?.name,
         current.intent?.phase,
@@ -285,74 +546,88 @@ export class ShopstackClient {
       progressFingerprint = fingerprint;
       await options.onProgress(current);
     };
-    await publishProgress(checkout);
+    const watcher = new CheckoutUpdateWatcher(this, checkout.id);
     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}` },
+    try {
+      while (true) {
+        await publishProgress(checkout);
+        if (TERMINAL_STATUSES.has(checkout.status)) return checkout;
+        const elapsed = Date.now() - startedAt;
+        if (elapsed >= timeoutMs) {
+          throw new ShopstackApiError("Checkout monitoring timed out.", {
+            code: "checkout_timeout",
+          });
+        }
+        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;
+          checkout = await this.providePaymentDetails(checkout.id, card, {
+            idempotencyKey: `payment-details-${checkout.id}-${checkout.revision}`,
+          });
+          handledMessageRevision = 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;
+          checkout = await this.decidePaymentApproval(
+            checkout.id,
+            checkout.approval.id,
+            approved,
+            { idempotencyKey: `approval-${checkout.approval.id}` },
+          );
+          if (!approved) return checkout;
+          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;
+        }
+        const remainingMs = timeoutMs - (Date.now() - startedAt);
+        const update = await watcher.wait(
+          presentationRevision(checkout),
+          remainingMs,
         );
-        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);
+        if (update.kind === "unavailable") {
+          const pollIntervalMs =
+            options.pollIntervalMs ??
+            (checkout.status === "help_required" ||
+            checkout.status === "approval_required"
+              ? 5_000
+              : 2_000);
+          await delay(Math.min(pollIntervalMs, remainingMs));
+        }
+        checkout =
+          update.kind === "checkout"
+            ? update.checkout
+            : await this.getCheckout(checkout.id);
       }
+    } finally {
+      watcher.close();
     }
-    return checkout;
   }
 }