shopstack 0.2.6 → 0.3.1

package/src/client.d.ts

@@ -2,7 +2,100 @@ export interface ShopstackClientOptions {
   apiKey?: string;
   baseUrl?: string;
   fetch?: typeof fetch;
-  webSocket?: typeof WebSocket;
+  /** Uses the runtime WebSocket when available; null selects bounded HTTP waits. */
+  webSocket?: typeof WebSocket | null;
+}
+
+export interface ShippingAddress {
+  city: string;
+  country: string;
+  line1: string;
+  line2?: string;
+  postal_code: string;
+  region?: string;
+  suburb?: string;
+}
+
+export interface CreateCheckoutRequest {
+  currency: string;
+  customer: {
+    /** When absent or blank, the service uses a checkout-scoped temporary inbox. */
+    email?: string;
+    name: string;
+    phone?: string;
+    shipping_address: ShippingAddress;
+  };
+  external_reference?: string;
+  instructions?: string;
+  item_url: string;
+  maximum_amount: string;
+  model_handle?: "qwen";
+  payment_provider?: "link";
+  proxy?: {
+    country?: string;
+    /** Explicit browser locale; the service does not infer it from country. */
+    locale?: string;
+  };
+}
+
+export interface ReservationDiner {
+  country: string;
+  /** Optional booking contact address. If omitted, Shopstack creates a temporary inbox. */
+  email?: string;
+  first_name: string;
+  last_name: string;
+  phone_number: string;
+}
+
+export interface CreateReservationRequest {
+  diner: ReservationDiner;
+  external_reference?: string;
+  /** The service resolves this place name and its local time zone. */
+  location: { query: string };
+  /** Include all known search details. The service asks for missing information. */
+  request: string;
+}
+
+export interface ReservationProgress {
+  type: "progress";
+  request_id: string;
+  sequence: number;
+  call_id: number;
+  operation:
+    | "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";
+  phase: "started" | "completed" | "failed" | "selected";
+  elapsed_ms: number;
+  duration_ms?: number;
+  http_status?: number;
+  failure?: string;
+}
+
+export interface ReservationMutationOptions {
+  idempotencyKey?: string;
+  /** Display only. Callback failure does not retry or cancel the operation. */
+  onProgress?: (event: ReservationProgress) => unknown;
 }
 
 export interface PaymentCard {
@@ -34,6 +127,7 @@ export interface Checkout {
     | "failed"
     | "cancelled";
   revision: number;
+  /** Monotonic display version; it can advance without a lifecycle change. */
   presentation_revision: number;
   activity: string;
   intent?: {
@@ -42,6 +136,7 @@ export interface Checkout {
     updated_at: string;
   };
   item_url: string;
+  /** Present this exact owner-only URL verbatim. Never reconstruct its token. */
   live_view_url?: string;
   required_input?: { type: "payment_card" };
   approval?: PaymentApproval;
@@ -52,9 +147,124 @@ export interface Checkout {
   expires_at: string;
 }
 
+export interface Reservation {
+  id: string;
+  status:
+    | "active"
+    | "confirmation_required"
+    | "confirmed"
+    | "cancelled"
+    | "booking_unknown"
+    | "cancellation_unknown";
+  revision: number;
+  turn: ReservationTurn;
+  created_at: string;
+  updated_at: string;
+  /** Search-session expiry; it does not end the life of a confirmed booking. */
+  expires_at: string;
+  /** Last retained time for reading and managing the confirmed booking. */
+}
+
+export type ReservationTurn =
+  | { type: "question" | "message"; message: string }
+  | {
+      type: "location_options";
+      message: string;
+      locations: { location_id: string; label: string }[];
+    }
+  | {
+      type: "options";
+      message: string;
+      options: ReservationCompactOption[];
+      more_available: number;
+    }
+  | {
+      type: "confirmation_required";
+      message: string;
+      confirmation_prompt: {
+        restaurant: string;
+        address: string;
+        date_time: string;
+        party_size: number;
+        option_id: string;
+        time_id: string;
+        diner: ReservationDiner;
+      };
+    }
+  | {
+      type: "confirmation";
+      message: string;
+      confirmation: {
+        confirmation_number: string;
+        restaurant: string;
+        date_time: string;
+        party_size: number;
+        status: string;
+      };
+    }
+  | {
+      type: "cancellation";
+      message: string;
+      cancellation: { confirmation_number: string; status: string };
+    };
+
+export interface ReservationTime {
+  date_time: string;
+  time_id: string;
+}
+
+export interface ReservationCompactOption {
+  address: string;
+  available_times: ReservationTime[];
+  caveats: string[];
+  cuisines: string[];
+  cover_photo_url?: string;
+  description_excerpt?: string;
+  fit: string[];
+  name: string;
+  option_id: string;
+  price_label?: string;
+  rating?: number;
+  review_count?: number;
+  tags: ("more_availability" | "most_proven")[];
+}
+
+export interface ReservationOption extends Omit<
+  ReservationCompactOption,
+  | "available_times"
+  | "caveats"
+  | "cover_photo_url"
+  | "description_excerpt"
+  | "fit"
+  | "tags"
+> {
+  description?: string;
+  match_reasons: string[];
+  photo_urls: string[];
+  times: ReservationTime[];
+  unverified: string[];
+}
+
+export interface ReservationOptionPage {
+  limit: number;
+  more_available: number;
+  next_offset?: number;
+  offset: number;
+  options: ReservationCompactOption[];
+  total_available: number;
+}
+
+export interface RunReservationOptions {
+  idempotencyKey?: string;
+  onTurn?(reservation: Reservation): void | Promise<void>;
+  respond?(
+    reservation: Reservation,
+  ): string | Promise<string | undefined> | undefined;
+}
+
 export interface RunCheckoutOptions {
   idempotencyKey?: string;
-  onCreated?(checkout: Checkout): void | Promise<void>;
+  /** @deprecated Checkout monitoring uses revision notifications and bounded waits. */
   pollIntervalMs?: number;
   timeoutMs?: number;
   onProgress?(checkout: Checkout): void | Promise<void>;
@@ -70,19 +280,7 @@ 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 LiveViewCapability {
-  live_view_url: string;
-}
-
-export interface AccountLoginStarted {
+export interface AccountSignupStarted {
   id: string;
   account_type: "personal" | "developer";
   email: string;
@@ -92,7 +290,7 @@ export interface AccountLoginStarted {
   poll_token: string;
 }
 
-export interface VerifiedAccountLogin {
+export interface VerifiedAccountSignup {
   id: string;
   status: "verified";
   verified_at: string;
@@ -102,43 +300,45 @@ export interface VerifiedAccountLogin {
   user?: Record<string, unknown>;
 }
 
-export interface LoginOptions {
+export interface SignupOptions {
   accountType: "personal" | "developer";
   email: string;
   pollIntervalMs?: number;
   timeoutMs?: number;
-  persistence?: LoginPersistence;
-  onProgress?(progress: LoginProgress): void | Promise<void>;
+  persistence?: SignupPersistence;
+  onProgress?(progress: SignupProgress): void | Promise<void>;
   onVerificationRequired?(
-    login: Omit<AccountLoginStarted, "poll_token">,
+    signup: Omit<AccountSignupStarted, "poll_token">,
   ): void | Promise<void>;
 }
 
-export interface PendingLoginState {
+export interface PendingSignupState {
   accountType: "personal" | "developer";
   attemptId: string;
+  /** Exact API base URL that issued this signup; never send its capabilities elsewhere. */
+  baseUrl?: string;
   email: string;
   expiresAt?: string;
   idempotencyKey: string;
   pollToken?: string;
   recoveryKey: string;
-  loginId?: string;
+  signupId?: string;
 }
 
-export interface LoginPersistence {
+export interface SignupPersistence {
   loadPending(input: {
     accountType: "personal" | "developer";
     email: string;
-  }): Promise<PendingLoginState | undefined>;
-  savePending(state: PendingLoginState): Promise<void>;
+  }): Promise<PendingSignupState | undefined>;
+  savePending(state: PendingSignupState): Promise<void>;
   completePending(
-    state: PendingLoginState,
-    result: VerifiedAccountLogin,
+    state: PendingSignupState,
+    result: VerifiedAccountSignup,
   ): Promise<void>;
-  deletePending(state: PendingLoginState): Promise<void>;
+  deletePending(state: PendingSignupState): Promise<void>;
 }
 
-export interface LoginProgress {
+export interface SignupProgress {
   state:
     | "pending"
     | "email_sent"
@@ -155,7 +355,7 @@ export interface LoginProgress {
   key_type?: "user" | "developer";
 }
 
-export type CompletedAccountLogin = Omit<VerifiedAccountLogin, "api_key">;
+export type CompletedAccountSignup = Omit<VerifiedAccountSignup, "api_key">;
 
 export class ShopstackApiError extends Error {
   code: string;
@@ -165,20 +365,21 @@ export class ShopstackApiError extends Error {
 
 export class ShopstackClient {
   constructor(options?: ShopstackClientOptions);
-  startAccountLogin(input: {
+  baseUrl: string;
+  startAccountSignup(input: {
     accountType: "personal" | "developer";
     email: string;
-  }): Promise<AccountLoginStarted>;
-  pollAccountLogin(
-    loginId: string,
+  }): Promise<AccountSignupStarted>;
+  pollAccountSignup(
+    signupId: string,
     pollToken: string,
-  ): Promise<Omit<AccountLoginStarted, "poll_token"> | VerifiedAccountLogin>;
-  waitForAccountLogin(
-    loginId: string,
+  ): Promise<Omit<AccountSignupStarted, "poll_token"> | VerifiedAccountSignup>;
+  waitForAccountSignup(
+    signupId: string,
     pollToken: string,
     options?: { pollIntervalMs?: number; timeoutMs?: number },
-  ): Promise<VerifiedAccountLogin>;
-  login(input: LoginOptions): Promise<CompletedAccountLogin>;
+  ): Promise<VerifiedAccountSignup>;
+  signup(input: SignupOptions): Promise<CompletedAccountSignup>;
   createUser(input: {
     externalId: string;
     idempotencyKey?: string;
@@ -199,23 +400,57 @@ export class ShopstackClient {
     paymentProvider?: "link",
     options?: { idempotencyKey?: string },
   ): Promise<Record<string, unknown>>;
+  createReservation(
+    reservation: CreateReservationRequest,
+    options?: ReservationMutationOptions,
+  ): Promise<Reservation>;
+  getReservation(reservationId: string): Promise<Reservation>;
+  listReservationOptions(
+    reservationId: string,
+    options?: { limit?: number; offset?: number },
+  ): Promise<ReservationOptionPage>;
+  getReservationOption(
+    reservationId: string,
+    optionId: string,
+  ): Promise<ReservationOption>;
+  sendReservationMessage(
+    reservationId: string,
+    content: string,
+    expectedRevision: number,
+    options?: ReservationMutationOptions,
+  ): Promise<Reservation>;
+  cancelReservation(
+    reservationId: string,
+    expectedRevision: number,
+    options?: ReservationMutationOptions,
+  ): Promise<Reservation>;
+  runReservation(
+    reservation: CreateReservationRequest,
+    options?: RunReservationOptions,
+  ): Promise<Reservation>;
   createCheckout(
-    checkout: Record<string, unknown>,
+    checkout: CreateCheckoutRequest,
     options?: { idempotencyKey?: string },
   ): Promise<Checkout>;
   getCheckout(checkoutId: string): Promise<Checkout>;
-  createLiveView(
-    checkoutId: string,
-    options?: { idempotencyKey?: string },
-  ): Promise<LiveViewCapability>;
-  createCheckoutUpdateSubscription(
-    checkoutId: string,
-  ): Promise<CheckoutUpdateSubscription>;
   waitForCheckoutUpdate(
     checkoutId: string,
-    afterRevision: number,
-    waitSeconds?: number,
+    options: { after: number; wait?: number; signal?: AbortSignal },
   ): Promise<Checkout | undefined>;
+  subscribeToCheckoutUpdates(
+    checkoutId: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<{
+    socket_url: string;
+    protocol: "shopstack.v1";
+    token: string;
+    expires_at: string;
+    presentation_revision: number;
+  }>;
+  createLiveView(
+    checkoutId: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<{ live_view_url: string }>;
   cancelCheckout(
     checkoutId: string,
     options?: { idempotencyKey?: string },
@@ -227,7 +462,6 @@ export class ShopstackClient {
   ): Promise<Record<string, unknown>>;
   listMessages(checkoutId: string): Promise<Record<string, unknown>>;
   listEvents(checkoutId: string): Promise<Record<string, unknown>>;
-  listArtifacts(checkoutId: string): Promise<Record<string, unknown>>;
   providePaymentDetails(
     checkoutId: string,
     card: PaymentCard,
@@ -240,7 +474,7 @@ export class ShopstackClient {
     options?: { idempotencyKey?: string },
   ): Promise<Checkout>;
   runCheckout(
-    checkout: Record<string, unknown>,
+    checkout: CreateCheckoutRequest,
     options?: RunCheckoutOptions,
   ): Promise<Checkout>;
 }