shopstack 0.2.5 → 0.3.0

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 { 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 } = {}) {
@@ -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,
     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,10 +67,17 @@ export class ShopstackClient {
       body,
       idempotencyKey: mutationKey,
       method = "GET",
+      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}`);
@@ -179,29 +89,56 @@ export class ShopstackClient {
       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,
         },
       );
     }
@@ -286,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", {
@@ -296,6 +234,7 @@ export class ShopstackClient {
     }
     pending ??= {
       accountType,
+      baseUrl: this.baseUrl,
       attemptId: `attempt-${randomUUID()}`,
       email: normalizedEmail,
       idempotencyKey: idempotencyKey("account"),
@@ -432,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,
@@ -444,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",
+      },
     );
   }
 
@@ -496,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`,
@@ -535,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,
@@ -556,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
@@ -578,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 (
@@ -593,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 (
@@ -617,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();
     }
   }
 }

package/src/config.d.ts

@@ -1,12 +1,14 @@
 export interface ShopstackProfile {
   accountId: string;
   apiKey: string;
+  baseUrl?: string;
   keyType: "developer" | "user";
   userId?: string;
 }
 
 export interface PendingSignup {
   accountType: "developer" | "personal";
+  baseUrl?: string;
   attemptId?: string;
   email: string;
   expiresAt?: string;
@@ -53,3 +55,8 @@ export class ConfigStore {
 }
 
 export function defaultConfigPath(): string;
+
+export function resolveProfileBaseUrl(
+  profile?: { baseUrl?: string },
+  selectedBaseUrl?: string,
+): string | undefined;

package/src/config.js

@@ -2,6 +2,17 @@ import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
+export function resolveProfileBaseUrl(profile, selectedBaseUrl) {
+  const saved = profile?.baseUrl?.replace(/\/+$/u, "");
+  const selected = selectedBaseUrl?.replace(/\/+$/u, "");
+  if (saved !== undefined && selected !== undefined && saved !== selected) {
+    throw new Error(
+      "This profile belongs to a different Shopstack API. Select its endpoint or use a separate profile store.",
+    );
+  }
+  return saved ?? selected;
+}
+
 export function defaultConfigPath() {
   return (
     process.env.SHOPSTACK_CONFIG_FILE ??
@@ -131,6 +142,7 @@ export class ConfigStore {
       accountId: result.account.id,
       apiKey: result.api_key,
       keyType: result.key_type,
+      ...(entry[1].baseUrl === undefined ? {} : { baseUrl: entry[1].baseUrl }),
       ...(result.user?.id === undefined ? {} : { userId: result.user.id }),
     };
     config.active = profileName;

package/src/reservation-progress.js

@@ -0,0 +1,132 @@
+const operations = new Set([
+  "resolve_location",
+  "get_search_filters",
+  "search_restaurants",
+  "prepare_booking",
+  "confirm_booking",
+  "decline_booking",
+  "ask_user",
+  "reply",
+  "request",
+  "model_decision",
+  "model_request",
+  "model_retry_wait",
+  "restaurant_request",
+  "provider_session",
+  "location_lookup",
+  "availability_recheck",
+  "slot_lock",
+  "slot_unlock",
+  "guest_profile",
+  "booking_submit",
+  "booking_status",
+  "booking_cancel",
+  "guest_inbox",
+]);
+const phases = new Set(["started", "completed", "failed", "selected"]);
+const failures = new Set([
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_SOCKET",
+  "TimeoutError",
+  "AbortError",
+  "model_invalid_response",
+  "operation_failed",
+]);
+const nonnegative = (value) => Number.isSafeInteger(value) && value >= 0;
+
+// Reconstruct the closed display shape. Provider bodies and arbitrary fields never pass through.
+function publicProgress(frame, previous, requestId) {
+  if (
+    frame.request_id !== requestId ||
+    !nonnegative(frame.sequence) ||
+    frame.sequence <= previous ||
+    frame.sequence > 512 ||
+    !nonnegative(frame.call_id) ||
+    !nonnegative(frame.elapsed_ms) ||
+    !operations.has(frame.operation) ||
+    !phases.has(frame.phase)
+  )
+    throw new Error("Invalid progress frame.");
+  const event = Object.fromEntries(
+    [
+      "type",
+      "request_id",
+      "sequence",
+      "call_id",
+      "operation",
+      "phase",
+      "elapsed_ms",
+    ].map((key) => [key, frame[key]]),
+  );
+  if (nonnegative(frame.duration_ms)) event.duration_ms = frame.duration_ms;
+  if (
+    Number.isInteger(frame.http_status) &&
+    frame.http_status >= 100 &&
+    frame.http_status <= 599
+  )
+    event.http_status = frame.http_status;
+  if (failures.has(frame.failure)) event.failure = frame.failure;
+  return event;
+}
+
+export async function readReservationProgress(response, onProgress) {
+  const requestId = response.headers.get("x-request-id");
+  if (!/^req_[a-f0-9]{32}$/u.test(requestId ?? "") || !response.body)
+    throw new Error("Invalid progress stream.");
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let text = "";
+  let bytes = 0;
+  let sequence = 0;
+  let result;
+  try {
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > 17 * 1024 * 1024)
+        throw new Error("Progress stream limit exceeded.");
+      text += decoder.decode(chunk.value, { stream: true });
+      for (;;) {
+        const end = text.indexOf("\n");
+        if (end < 0) break;
+        const frame = JSON.parse(text.slice(0, end));
+        text = text.slice(end + 1);
+        if (result || !frame || typeof frame !== "object")
+          throw new Error("Invalid stream order.");
+        if (frame.type === "progress") {
+          const event = publicProgress(frame, sequence, requestId);
+          sequence = event.sequence;
+          try {
+            Promise.resolve(onProgress?.(event)).catch(() => {});
+          } catch {
+            /* Display failure cannot retry a mutation. */
+          }
+        } else if (
+          frame.type === "result" &&
+          frame.request_id === requestId &&
+          Number.isInteger(frame.status) &&
+          frame.status >= 200 &&
+          frame.status <= 599 &&
+          Object.hasOwn(frame, "body")
+        ) {
+          result = { status: frame.status, payload: frame.body };
+        } else throw new Error("Invalid result frame.");
+      }
+    }
+    text += decoder.decode();
+    if (!result || text.length) throw new Error("Incomplete progress stream.");
+    return result;
+  } finally {
+    // Also release failed/truncated streams. No automatic request retry.
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}