@voyantjs/storefront-sdk 0.31.3

package/README.md

@@ -0,0 +1,33 @@
+# `@voyantjs/storefront-sdk`
+
+Framework-agnostic TypeScript client for custom Voyant storefronts.
+
+The SDK does not own HTTP routes. It wraps the existing public contracts from
+`@voyantjs/storefront`, `@voyantjs/bookings`, and `@voyantjs/checkout` behind a
+single typed client so custom booking UIs can consume Voyant booking logic
+without stitching together package-local fetchers.
+
+```ts
+import { createVoyantStorefrontClient } from "@voyantjs/storefront-sdk"
+
+const voyant = createVoyantStorefrontClient({
+  baseUrl: "https://operator.example.com",
+})
+
+const session = await voyant.booking.createSession({
+  sellCurrency: "EUR",
+  items: [
+    {
+      title: "Danube tour",
+      availabilitySlotId: "slot_123",
+      quantity: 2,
+      totalSellAmountCents: 24000,
+    },
+  ],
+})
+
+const state = voyant.booking.deriveState(session)
+```
+
+React consumers should layer React Query hooks on top of this package rather
+than reimplementing request paths directly.

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import type { z } from "zod";
+export type VoyantStorefrontFetcher = (url: string, init?: RequestInit) => Promise<Response>;
+export declare const defaultStorefrontFetcher: VoyantStorefrontFetcher;
+export declare class VoyantStorefrontApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export interface VoyantStorefrontClientOptions {
+    baseUrl: string;
+    fetcher?: VoyantStorefrontFetcher;
+    headers?: HeadersInit;
+}
+export interface StorefrontRequestOptions {
+    headers?: HeadersInit;
+    idempotencyKey?: string;
+}
+export type StorefrontQueryParamValue = string | number | boolean | null | undefined | Array<string | number | boolean>;
+export declare function withStorefrontQueryParams(path: string, query?: object): string;
+export declare function storefrontFetchWithValidation<TOut>(path: string, schema: z.ZodType<TOut>, options: Required<Pick<VoyantStorefrontClientOptions, "baseUrl" | "fetcher">> & Pick<VoyantStorefrontClientOptions, "headers">, init?: RequestInit): Promise<TOut>;
+export declare function requestHeaders(options?: StorefrontRequestOptions): HeadersInit | undefined;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,MAAM,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE5F,eAAO,MAAM,wBAAwB,EAAE,uBACU,CAAA;AAEjD,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;gBAEV,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM3D;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,uBAAuB,CAAA;IACjC,OAAO,CAAC,EAAE,WAAW,CAAA;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,yBAAyB,GACjC,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;AAEpC,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAwB9E;AAED,wBAAsB,6BAA6B,CAAC,IAAI,EACtD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EACvB,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,6BAA6B,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC,GAC3E,IAAI,CAAC,6BAA6B,EAAE,SAAS,CAAC,EAChD,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,WAAW,GAAG,SAAS,CAU1F"}

package/dist/client.js

@@ -0,0 +1,92 @@
+export const defaultStorefrontFetcher = (url, init) => fetch(url, { credentials: "include", ...init });
+export class VoyantStorefrontApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "VoyantStorefrontApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export function withStorefrontQueryParams(path, query) {
+    if (!query) {
+        return path;
+    }
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                params.append(key, String(item));
+            }
+            continue;
+        }
+        params.set(key, String(value));
+    }
+    const serialized = params.toString();
+    return serialized ? `${path}?${serialized}` : path;
+}
+export async function storefrontFetchWithValidation(path, schema, options, init) {
+    const url = joinUrl(options.baseUrl, path);
+    const headers = new Headers(options.headers);
+    for (const [key, value] of new Headers(init?.headers)) {
+        headers.set(key, value);
+    }
+    if (init?.body !== undefined && !headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
+    }
+    const response = await options.fetcher(url, { ...init, headers });
+    if (!response.ok) {
+        const body = await safeJson(response);
+        throw new VoyantStorefrontApiError(extractErrorMessage(response.status, response.statusText, body), response.status, body);
+    }
+    if (response.status === 204) {
+        return schema.parse(undefined);
+    }
+    const body = await safeJson(response);
+    const parsed = schema.safeParse(body);
+    if (!parsed.success) {
+        throw new VoyantStorefrontApiError(`Voyant storefront response failed validation: ${parsed.error.message}`, response.status, body);
+    }
+    return parsed.data;
+}
+export function requestHeaders(options) {
+    if (!options?.headers && !options?.idempotencyKey) {
+        return undefined;
+    }
+    const headers = new Headers(options.headers);
+    if (options.idempotencyKey) {
+        headers.set("Idempotency-Key", options.idempotencyKey);
+    }
+    return headers;
+}
+function extractErrorMessage(status, statusText, body) {
+    if (typeof body === "object" && body !== null && "error" in body) {
+        const err = body.error;
+        if (typeof err === "string")
+            return err;
+        if (typeof err === "object" && err !== null && "message" in err) {
+            return String(err.message);
+        }
+    }
+    return `Voyant storefront API error: ${status} ${statusText}`;
+}
+async function safeJson(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function joinUrl(baseUrl, path) {
+    const trimmedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    const trimmedPath = path.startsWith("/") ? path : `/${path}`;
+    return `${trimmedBase}${trimmedPath}`;
+}

package/dist/engine-state.d.ts

@@ -0,0 +1,21 @@
+import type { PublicBookingSessionRecord } from "./schemas.js";
+export declare const bookingEngineStates: readonly ["draft", "reserved", "billing_completed", "travelers_completed", "terms_accepted", "ready_for_payment", "payment_started", "payment_pending", "confirmed", "completed", "expired", "cancelled"];
+export type BookingEngineState = (typeof bookingEngineStates)[number];
+export declare const bookingEngineActions: readonly ["create_session", "reserve", "update_billing", "update_travelers", "reprice", "accept_terms", "start_payment", "poll_payment", "confirm", "expire", "clear_session"];
+export type BookingEngineAction = (typeof bookingEngineActions)[number];
+export interface BookingEngineSnapshot {
+    sessionId: string;
+    bookingNumber: string;
+    state: BookingEngineState;
+    bookingStatus: PublicBookingSessionRecord["status"];
+    currentStep: string | null;
+    completedSteps: string[];
+    holdExpiresAt: string | null;
+    readyForConfirmation: boolean;
+    allowedActions: BookingEngineAction[];
+}
+export declare function deriveBookingEngineState(session: PublicBookingSessionRecord): BookingEngineState;
+export declare function getAllowedBookingEngineActions(state: BookingEngineState): BookingEngineAction[];
+export declare function canRunBookingEngineAction(state: BookingEngineState, action: BookingEngineAction): boolean;
+export declare function createBookingEngineSnapshot(session: PublicBookingSessionRecord): BookingEngineSnapshot;
+//# sourceMappingURL=engine-state.d.ts.map

package/dist/engine-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-state.d.ts","sourceRoot":"","sources":["../src/engine-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAE9D,eAAO,MAAM,mBAAmB,2MAatB,CAAA;AAEV,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAErE,eAAO,MAAM,oBAAoB,gLAYvB,CAAA;AAEV,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEvE,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,kBAAkB,CAAA;IACzB,aAAa,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAA;IACnD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,oBAAoB,EAAE,OAAO,CAAA;IAC7B,cAAc,EAAE,mBAAmB,EAAE,CAAA;CACtC;AAWD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,0BAA0B,GAAG,kBAAkB,CAmChG;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,EAAE,CAoC/F;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAET;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,0BAA0B,GAClC,qBAAqB,CAavB"}

package/dist/engine-state.js

@@ -0,0 +1,124 @@
+export const bookingEngineStates = [
+    "draft",
+    "reserved",
+    "billing_completed",
+    "travelers_completed",
+    "terms_accepted",
+    "ready_for_payment",
+    "payment_started",
+    "payment_pending",
+    "confirmed",
+    "completed",
+    "expired",
+    "cancelled",
+];
+export const bookingEngineActions = [
+    "create_session",
+    "reserve",
+    "update_billing",
+    "update_travelers",
+    "reprice",
+    "accept_terms",
+    "start_payment",
+    "poll_payment",
+    "confirm",
+    "expire",
+    "clear_session",
+];
+const completedStateByStep = [
+    ["payment", "payment_started"],
+    ["terms", "terms_accepted"],
+    ["contract", "terms_accepted"],
+    ["travelers", "travelers_completed"],
+    ["passengers", "travelers_completed"],
+    ["billing", "billing_completed"],
+];
+export function deriveBookingEngineState(session) {
+    switch (session.status) {
+        case "cancelled":
+            return "cancelled";
+        case "completed":
+            return "completed";
+        case "expired":
+            return "expired";
+        case "confirmed":
+        case "in_progress":
+            return "confirmed";
+        case "awaiting_payment":
+            return "payment_pending";
+        case "on_hold":
+            break;
+        case "draft":
+            return "draft";
+    }
+    const completedSteps = new Set(session.state?.completedSteps ?? []);
+    if (session.checklist.readyForConfirmation && completedSteps.has("payment")) {
+        return "payment_started";
+    }
+    if (session.checklist.readyForConfirmation && hasTermsAccepted(completedSteps)) {
+        return "ready_for_payment";
+    }
+    for (const [step, state] of completedStateByStep) {
+        if (completedSteps.has(step)) {
+            return state;
+        }
+    }
+    return "reserved";
+}
+export function getAllowedBookingEngineActions(state) {
+    switch (state) {
+        case "draft":
+            return ["create_session", "reserve", "clear_session"];
+        case "reserved":
+        case "billing_completed":
+        case "travelers_completed":
+            return [
+                "update_billing",
+                "update_travelers",
+                "reprice",
+                "accept_terms",
+                "expire",
+                "clear_session",
+            ];
+        case "terms_accepted":
+        case "ready_for_payment":
+            return [
+                "update_billing",
+                "update_travelers",
+                "reprice",
+                "start_payment",
+                "confirm",
+                "expire",
+                "clear_session",
+            ];
+        case "payment_started":
+        case "payment_pending":
+            return ["poll_payment", "confirm", "clear_session"];
+        case "confirmed":
+        case "completed":
+            return ["clear_session"];
+        case "expired":
+        case "cancelled":
+            return ["clear_session"];
+    }
+}
+export function canRunBookingEngineAction(state, action) {
+    return getAllowedBookingEngineActions(state).includes(action);
+}
+export function createBookingEngineSnapshot(session) {
+    const state = deriveBookingEngineState(session);
+    return {
+        sessionId: session.sessionId,
+        bookingNumber: session.bookingNumber,
+        state,
+        bookingStatus: session.status,
+        currentStep: session.state?.currentStep ?? null,
+        completedSteps: session.state?.completedSteps ?? [],
+        holdExpiresAt: session.holdExpiresAt,
+        readyForConfirmation: session.checklist.readyForConfirmation,
+        allowedActions: getAllowedBookingEngineActions(state),
+    };
+}
+function hasTermsAccepted(completedSteps) {
+    return completedSteps.has("terms") || completedSteps.has("contract");
+}