shopstack 0.2.6 → 0.3.1

package/src/client.js

@@ -1,7 +1,15 @@
 import { randomBytes, randomUUID } from "node:crypto";
-import WebSocket from "ws";
+import { readReservationProgress } from "./reservation-progress.js";
+import { DEFAULT_API_URL, resolveProfileBaseUrl } from "./config.js";
+import { checkoutMonitor } from "./checkout-monitor.js";
 
 const TERMINAL_STATUSES = new Set(["complete", "failed", "cancelled"]);
+const TERMINAL_RESERVATION_STATUSES = new Set([
+  "confirmed",
+  "cancelled",
+  "booking_unknown",
+  "cancellation_unknown",
+]);
 
 export class ShopstackApiError extends Error {
   constructor(message, { code = "api_error", requestId, status } = {}) {
@@ -17,11 +25,11 @@ function idempotencyKey(prefix) {
   return `${prefix}-${randomUUID()}`;
 }
 
-function loginRecoveryKey() {
-  return `login_recovery_${randomBytes(32).toString("base64url")}`;
+function signupRecoveryKey() {
+  return `signup_recovery_${randomBytes(32).toString("base64url")}`;
 }
 
-function loginAttemptKey(accountType, email) {
+function signupAttemptKey(accountType, email) {
   return `${accountType}\u0000${email.trim().toLowerCase()}`;
 }
 
@@ -31,122 +39,17 @@ function delay(milliseconds) {
     : 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://api.shopstack.ai/v1",
+    baseUrl = process.env.SHOPSTACK_API_URL ?? DEFAULT_API_URL,
     fetch: fetchImplementation = globalThis.fetch,
-    webSocket: webSocketImplementation = WebSocket,
+    webSocket = globalThis.WebSocket,
   } = {}) {
     if (typeof baseUrl !== "string" || !/^https?:\/\//u.test(baseUrl)) {
-      throw new TypeError("baseUrl must be an HTTP(S) URL");
+      throw new TypeError(
+        "Set baseUrl or SHOPSTACK_API_URL to the intended Shopstack HTTP(S) API endpoint.",
+      );
     }
     if (typeof fetchImplementation !== "function") {
       throw new TypeError("a fetch implementation is required");
@@ -154,7 +57,7 @@ export class ShopstackClient {
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/+$/u, "");
     this.fetch = fetchImplementation;
-    this.WebSocket = webSocketImplementation;
+    this.webSocket = webSocket;
   }
 
   async request(
@@ -164,76 +67,115 @@ export class ShopstackClient {
       body,
       idempotencyKey: mutationKey,
       method = "GET",
-      loginRecoveryKey: recoveryKey,
+      onProgress,
+      signupRecoveryKey: recoveryKey,
+      signal,
     } = {},
   ) {
     const headers = new Headers({ Accept: "application/json" });
+    const progress =
+      typeof onProgress === "function" &&
+      method === "POST" &&
+      /^\/reservations(?:\/|$)/u.test(path);
+    if (progress) headers.set("Accept", "application/x-ndjson");
     const authorization = bearerToken ?? this.apiKey;
     if (authorization) {
       headers.set("Authorization", `Bearer ${authorization}`);
     }
     if (body !== undefined) headers.set("Content-Type", "application/json");
     if (mutationKey) headers.set("Idempotency-Key", mutationKey);
-    if (recoveryKey) headers.set("Login-Recovery-Key", recoveryKey);
+    if (recoveryKey) headers.set("Signup-Recovery-Key", recoveryKey);
     const response = await this.fetch(`${this.baseUrl}${path}`, {
       body: body === undefined ? undefined : JSON.stringify(body),
       headers,
       method,
+      signal,
     });
-    const raw = await response.text();
     let payload;
-    try {
-      payload = raw ? JSON.parse(raw) : undefined;
-    } catch {
-      throw new ShopstackApiError("Shopstack returned invalid JSON.", {
-        status: response.status,
-      });
+    let status = response.status;
+    if (
+      progress &&
+      response.headers.get("content-type")?.split(";")[0] ===
+        "application/x-ndjson"
+    ) {
+      try {
+        ({ payload, status } = await readReservationProgress(
+          response,
+          onProgress,
+        ));
+      } catch {
+        const requestId = response.headers.get("x-request-id");
+        throw new ShopstackApiError(
+          "The reservation response was interrupted or invalid. Check the reservation state before retrying; booking may already have occurred.",
+          {
+            code: "reservation_response_incomplete",
+            requestId: /^req_[a-f0-9]{32}$/u.test(requestId ?? "")
+              ? requestId
+              : undefined,
+            status: 502,
+          },
+        );
+      }
+    } else {
+      const raw = await response.text();
+      try {
+        payload = raw ? JSON.parse(raw) : undefined;
+      } catch {
+        throw new ShopstackApiError("Shopstack returned invalid JSON.", {
+          status: response.status,
+        });
+      }
     }
-    if (!response.ok) {
+    if (status < 200 || status >= 300) {
       const error = payload?.error;
       throw new ShopstackApiError(
         typeof error?.message === "string"
           ? error.message
-          : `Shopstack request failed with status ${response.status}.`,
+          : `Shopstack request failed with status ${status}.`,
         {
           code: typeof error?.code === "string" ? error.code : "api_error",
           requestId:
             typeof error?.request_id === "string"
               ? error.request_id
               : undefined,
-          status: response.status,
+          status,
         },
       );
     }
     return payload;
   }
 
-  _startAccountLogin({ accountType, email, idempotencyKey: key, recoveryKey }) {
-    return this.request("/login", {
+  _startAccountSignup({
+    accountType,
+    email,
+    idempotencyKey: key,
+    recoveryKey,
+  }) {
+    return this.request("/accounts", {
       body: { account_type: accountType, email },
       idempotencyKey: key,
       method: "POST",
-      loginRecoveryKey: recoveryKey,
+      signupRecoveryKey: recoveryKey,
     });
   }
 
-  startAccountLogin({ accountType, email } = {}) {
-    return this._startAccountLogin({
+  startAccountSignup({ accountType, email } = {}) {
+    return this._startAccountSignup({
       accountType,
       email,
       idempotencyKey: idempotencyKey("account"),
-      recoveryKey: loginRecoveryKey(),
+      recoveryKey: signupRecoveryKey(),
     });
   }
 
-  pollAccountLogin(loginId, pollToken) {
-    return this.request(`/login/${encodeURIComponent(loginId)}`, {
+  pollAccountSignup(signupId, pollToken) {
+    return this.request(`/accounts/${encodeURIComponent(signupId)}`, {
       bearerToken: pollToken,
     });
   }
 
-  async waitForAccountLogin(
-    loginId,
+  async waitForAccountSignup(
+    signupId,
     pollToken,
     { pollIntervalMs = 2_000, timeoutMs = 15 * 60 * 1_000 } = {},
   ) {
@@ -241,16 +183,16 @@ export class ShopstackClient {
     while (true) {
       if (Date.now() - startedAt >= timeoutMs) {
         throw new ShopstackApiError("Email verification timed out.", {
-          code: "login_timeout",
+          code: "signup_timeout",
         });
       }
-      const current = await this.pollAccountLogin(loginId, pollToken);
+      const current = await this.pollAccountSignup(signupId, pollToken);
       if (current.status === "verified") return current;
       await delay(pollIntervalMs);
     }
   }
 
-  async login({
+  async signup({
     accountType,
     email,
     onProgress,
@@ -260,17 +202,17 @@ export class ShopstackClient {
     timeoutMs = 15 * 60 * 1_000,
   } = {}) {
     const normalizedEmail = email.trim().toLowerCase();
-    const memoryKey = loginAttemptKey(accountType, normalizedEmail);
-    this._pendingLogins ??= new Map();
+    const memoryKey = signupAttemptKey(accountType, normalizedEmail);
+    this._pendingSignups ??= new Map();
     const storage = persistence ?? {
       completePending: async (state, result) => {
         this.apiKey = result.api_key;
-        this._pendingLogins.delete(memoryKey);
+        this._pendingSignups.delete(memoryKey);
       },
-      deletePending: async () => this._pendingLogins.delete(memoryKey),
-      loadPending: async () => this._pendingLogins.get(memoryKey),
+      deletePending: async () => this._pendingSignups.delete(memoryKey),
+      loadPending: async () => this._pendingSignups.get(memoryKey),
       savePending: async (state) => {
-        this._pendingLogins.set(memoryKey, structuredClone(state));
+        this._pendingSignups.set(memoryKey, structuredClone(state));
       },
     };
     const publish = async (state, details = {}) => {
@@ -281,6 +223,7 @@ export class ShopstackClient {
       accountType,
       email: normalizedEmail,
     });
+    resolveProfileBaseUrl(pending, this.baseUrl);
     if (pending?.expiresAt && Date.parse(pending.expiresAt) <= Date.now()) {
       await storage.deletePending(pending);
       await publish("expired", {
@@ -291,10 +234,11 @@ export class ShopstackClient {
     }
     pending ??= {
       accountType,
+      baseUrl: this.baseUrl,
       attemptId: `attempt-${randomUUID()}`,
       email: normalizedEmail,
       idempotencyKey: idempotencyKey("account"),
-      recoveryKey: loginRecoveryKey(),
+      recoveryKey: signupRecoveryKey(),
     };
     await storage.savePending(pending);
     await publish("pending", {
@@ -302,8 +246,8 @@ export class ShopstackClient {
       email: normalizedEmail,
     });
     try {
-      if (!pending.loginId || !pending.pollToken) {
-        const started = await this._startAccountLogin({
+      if (!pending.signupId || !pending.pollToken) {
+        const started = await this._startAccountSignup({
           accountType,
           email: normalizedEmail,
           idempotencyKey: pending.idempotencyKey,
@@ -313,7 +257,7 @@ export class ShopstackClient {
           ...pending,
           expiresAt: started.expires_at,
           pollToken: started.poll_token,
-          loginId: started.id,
+          signupId: started.id,
         };
         await storage.savePending(pending);
         if (typeof onVerificationRequired === "function") {
@@ -336,8 +280,8 @@ export class ShopstackClient {
         email: normalizedEmail,
         expires_at: pending.expiresAt,
       });
-      const result = await this.waitForAccountLogin(
-        pending.loginId,
+      const result = await this.waitForAccountSignup(
+        pending.signupId,
         pending.pollToken,
         { pollIntervalMs, timeoutMs },
       );
@@ -354,7 +298,7 @@ export class ShopstackClient {
       const { api_key: _credential, ...completed } = result;
       return completed;
     } catch (error) {
-      if (error?.code === "login_expired") {
+      if (error?.code === "signup_expired") {
         await storage.deletePending(pending);
         await publish("expired", {
           account_type: accountType,
@@ -367,7 +311,7 @@ export class ShopstackClient {
         });
       } else if (
         error?.code === "idempotency_conflict" ||
-        error?.code === "invalid_login_recovery"
+        error?.code === "invalid_signup_recovery"
       ) {
         await storage.deletePending(pending);
         await publish("conflict", {
@@ -427,6 +371,96 @@ export class ShopstackClient {
     });
   }
 
+  createReservation(reservation, { idempotencyKey: key, onProgress } = {}) {
+    return this.request("/reservations", {
+      body: reservation,
+      idempotencyKey: key ?? idempotencyKey("reservation"),
+      onProgress,
+      method: "POST",
+    });
+  }
+
+  getReservation(reservationId) {
+    return this.request(`/reservations/${encodeURIComponent(reservationId)}`);
+  }
+
+  listReservationOptions(reservationId, { limit = 6, offset = 0 } = {}) {
+    const query = new URLSearchParams({
+      offset: String(offset),
+      limit: String(limit),
+    });
+    return this.request(
+      `/reservations/${encodeURIComponent(reservationId)}/options?${query.toString()}`,
+    );
+  }
+
+  getReservationOption(reservationId, optionId) {
+    return this.request(
+      `/reservations/${encodeURIComponent(reservationId)}/options/${encodeURIComponent(optionId)}`,
+    );
+  }
+
+  sendReservationMessage(
+    reservationId,
+    content,
+    expectedRevision,
+    { idempotencyKey: key, onProgress } = {},
+  ) {
+    return this.request(
+      `/reservations/${encodeURIComponent(reservationId)}/messages`,
+      {
+        body: { content, expected_revision: expectedRevision },
+        idempotencyKey: key ?? idempotencyKey("reservation-message"),
+        onProgress,
+        method: "POST",
+      },
+    );
+  }
+
+  cancelReservation(
+    reservationId,
+    expectedRevision,
+    { idempotencyKey: key, onProgress } = {},
+  ) {
+    return this.request(
+      `/reservations/${encodeURIComponent(reservationId)}/cancel`,
+      {
+        body: { expected_revision: expectedRevision },
+        idempotencyKey: key ?? idempotencyKey("reservation-cancel"),
+        onProgress,
+        method: "POST",
+      },
+    );
+  }
+
+  async runReservation(reservationRequest, options = {}) {
+    let reservation = await this.createReservation(reservationRequest, {
+      idempotencyKey: options.idempotencyKey,
+    });
+    while (!TERMINAL_RESERVATION_STATUSES.has(reservation.status)) {
+      if (typeof options.onTurn === "function") {
+        await options.onTurn(reservation);
+      }
+      if (typeof options.respond !== "function") return reservation;
+      const content = await options.respond(reservation);
+      if (typeof content !== "string" || content.trim().length === 0) {
+        return reservation;
+      }
+      reservation = await this.sendReservationMessage(
+        reservation.id,
+        content.trim(),
+        reservation.revision,
+        {
+          idempotencyKey: `reservation-message-${reservation.id}-${reservation.revision}`,
+        },
+      );
+    }
+    if (typeof options.onTurn === "function") {
+      await options.onTurn(reservation);
+    }
+    return reservation;
+  }
+
   createCheckout(checkout, { idempotencyKey: key } = {}) {
     return this.request("/checkout", {
       body: checkout,
@@ -439,29 +473,37 @@ export class ShopstackClient {
     return this.request(`/checkout/${encodeURIComponent(checkoutId)}`);
   }
 
-  createLiveView(checkoutId, { idempotencyKey: key } = {}) {
+  waitForCheckoutUpdate(checkoutId, { after, wait = 25, signal } = {}) {
+    if (!Number.isSafeInteger(after) || after < 0) {
+      throw new TypeError("after must be a non-negative safe integer.");
+    }
+    if (!Number.isSafeInteger(wait) || wait < 1 || wait > 25) {
+      throw new TypeError("wait must be an integer from 1 through 25.");
+    }
+    const query = new URLSearchParams({
+      after: String(after),
+      wait: String(wait),
+    });
     return this.request(
-      `/checkout/${encodeURIComponent(checkoutId)}/live-view`,
-      {
-        idempotencyKey: key ?? idempotencyKey("live-view"),
-        method: "POST",
-      },
+      `/checkout/${encodeURIComponent(checkoutId)}/updates?${query}`,
+      { signal },
     );
   }
 
-  createCheckoutUpdateSubscription(checkoutId) {
+  subscribeToCheckoutUpdates(checkoutId, { signal } = {}) {
     return this.request(`/checkout/${encodeURIComponent(checkoutId)}/updates`, {
       method: "POST",
+      signal,
     });
   }
 
-  waitForCheckoutUpdate(checkoutId, afterRevision, waitSeconds = 25) {
-    const query = new URLSearchParams({
-      after: String(afterRevision),
-      wait: String(waitSeconds),
-    });
+  createLiveView(checkoutId, { idempotencyKey: key } = {}) {
     return this.request(
-      `/checkout/${encodeURIComponent(checkoutId)}/updates?${query.toString()}`,
+      `/checkout/${encodeURIComponent(checkoutId)}/live-view`,
+      {
+        idempotencyKey: key ?? idempotencyKey("live-view"),
+        method: "POST",
+      },
     );
   }
 
@@ -491,12 +533,6 @@ export class ShopstackClient {
     return this.request(`/checkout/${encodeURIComponent(checkoutId)}/events`);
   }
 
-  listArtifacts(checkoutId) {
-    return this.request(
-      `/checkout/${encodeURIComponent(checkoutId)}/artifacts`,
-    );
-  }
-
   providePaymentDetails(checkoutId, card, { idempotencyKey: key } = {}) {
     return this.request(
       `/checkout/${encodeURIComponent(checkoutId)}/payment-details`,
@@ -530,16 +566,12 @@ 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,
@@ -551,20 +583,20 @@ export class ShopstackClient {
       progressFingerprint = fingerprint;
       await options.onProgress(current);
     };
-    const watcher = new CheckoutUpdateWatcher(this, checkout.id);
+    await publishProgress(checkout);
     let handledPaymentRevision;
     let handledApprovalId;
     let handledMessageRevision;
+    const monitor = checkoutMonitor(this, checkout.id, this.webSocket);
     try {
-      while (true) {
-        await publishProgress(checkout);
-        if (TERMINAL_STATUSES.has(checkout.status)) return checkout;
-        const elapsed = Date.now() - startedAt;
-        if (elapsed >= timeoutMs) {
+      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
@@ -573,10 +605,9 @@ export class ShopstackClient {
           handledPaymentRevision = checkout.revision;
           const card = await options.paymentDetails(checkout);
           if (card === undefined) return checkout;
-          checkout = await this.providePaymentDetails(checkout.id, card, {
+          await this.providePaymentDetails(checkout.id, card, {
             idempotencyKey: `payment-details-${checkout.id}-${checkout.revision}`,
           });
-          handledMessageRevision = checkout.revision;
           continue;
         }
         if (
@@ -588,13 +619,13 @@ export class ShopstackClient {
           handledApprovalId = checkout.approval.id;
           const approved = await options.approve(checkout.approval, checkout);
           if (typeof approved !== "boolean") return checkout;
-          checkout = await this.decidePaymentApproval(
+          await this.decidePaymentApproval(
             checkout.id,
             checkout.approval.id,
             approved,
             { idempotencyKey: `approval-${checkout.approval.id}` },
           );
-          if (!approved) return checkout;
+          if (!approved) return this.getCheckout(checkout.id);
           continue;
         }
         if (
@@ -612,27 +643,16 @@ export class ShopstackClient {
           });
           continue;
         }
-        const remainingMs = timeoutMs - (Date.now() - startedAt);
-        const update = await watcher.wait(
-          presentationRevision(checkout),
-          remainingMs,
-        );
-        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));
+        if (!TERMINAL_STATUSES.has(checkout.status)) {
+          await monitor.wait(
+            checkout.presentation_revision ?? 0,
+            timeoutMs - (Date.now() - startedAt),
+          );
         }
-        checkout =
-          update.kind === "checkout"
-            ? update.checkout
-            : await this.getCheckout(checkout.id);
       }
+      return checkout;
     } finally {
-      watcher.close();
+      monitor.close();
     }
   }
 }