lynkow 1.40.1 → 1.41.0

package/dist/index.d.mts

@@ -5152,6 +5152,134 @@ interface CategoryResolveResponse {
  */
 type ResolveResponse = ContentResolveResponse | CategoryResolveResponse;
 
+/**
+ * A published product on the storefront catalogue. Mirrors the API's public
+ * whitelist: only buyer-facing fields are present, and `id` is a wire-encoded
+ * prefixed id (never a raw database identifier).
+ */
+interface Product {
+    /** The product id as a prefixed wire id (e.g. `'prod_...'`). Stable; safe to store and link. */
+    id: string;
+    /** URL-friendly unique slug. Use it to build a product page URL or to address the product in `products.getBySlug()`. */
+    slug: string;
+    /** Product title in the requested locale. Always non-empty for a published product. */
+    title: string;
+    /** Long product description, or `null` when the merchant left it empty. */
+    description: string | null;
+    /** Price in the smallest currency unit (cents). Divide by 100 to display. */
+    priceCents: number;
+    /** ISO 4217 currency code (e.g. `'EUR'`). */
+    currency: string;
+    /** Optional strikethrough "was" price in cents, or `null` when there is no comparison price. */
+    compareAtPriceCents: number | null;
+    /** Ordered public image URLs, or an empty array when the product has no images. */
+    images: string[];
+    /** The primary image URL (mirror of `images[0]`), or `null` when there are no images. */
+    thumbnail: string | null;
+    /** `'standard'` for a normal product, `'bookable'` for a reservation product (route it to the slot UI and {@link https://www.lynkow.com/docs reservations}). */
+    kind: 'standard' | 'bookable';
+    /** SEO title override, or `null` when unset (fall back to `title`). */
+    seoTitle: string | null;
+    /** SEO meta description, or `null` when unset. */
+    seoDescription: string | null;
+    /** Catalogue SKU, or `null` when unset. */
+    sku: string | null;
+    /** Product variants. Reserved for a later release: always an empty array in this version. */
+    variants: [];
+}
+/** Filters for a storefront product listing. All optional. */
+interface ProductsFilters {
+    /** Page number (1-based). Defaults to 1. */
+    page?: number;
+    /** Items per page. Defaults to 20, max 100. */
+    limit?: number;
+    /** Full-text search across title and slug. */
+    search?: string;
+    /** Restrict to a product kind: `'standard'` or `'bookable'`. */
+    kind?: 'standard' | 'bookable';
+    /** Sort field: `'title'`, `'price_cents'`, or `'created_at'`. Defaults to `'created_at'`. */
+    sortBy?: 'title' | 'price_cents' | 'created_at';
+    /** Sort direction: `'asc'` or `'desc'`. Defaults to `'desc'`. */
+    sortOrder?: 'asc' | 'desc';
+}
+/** Paginated product list response: the products on the page plus pagination metadata. */
+interface ProductsListResponse {
+    /** The published products on this page. */
+    data: Product[];
+    /** Pagination info (total, currentPage, lastPage, perPage, hasMorePages). */
+    meta: PaginationMeta;
+}
+
+/** A single computed bookable slot for a reservation product. */
+interface AvailabilitySlot {
+    /** Slot start as an ISO 8601 datetime (e.g. `'2026-07-10T18:00:00.000Z'`). */
+    startsAt: string;
+    /** Slot end as an ISO 8601 datetime. Derived from the resource slot duration. */
+    endsAt: string;
+    /** `true` when at least one seat is free for this slot. */
+    available: boolean;
+    /** Seats still free for this slot (capacity minus confirmed bookings). Non-negative: floored at 0. */
+    seatsRemaining: number;
+}
+/** The effective date window the returned availability slots cover. */
+interface AvailabilityWindow {
+    /** Window start as a calendar date `'YYYY-MM-DD'`, echoing the requested `from`. */
+    from: string;
+    /** Window end as a calendar date `'YYYY-MM-DD'`. May be earlier than the requested `to` when the server clamps an over-wide span. */
+    to: string;
+}
+/** Filters for a reservation availability query. */
+interface AvailabilityFilters {
+    /** Range start (inclusive) as a calendar date `'YYYY-MM-DD'`. Required. */
+    from: string;
+    /** Range end (inclusive) as a calendar date `'YYYY-MM-DD'`. Must not precede `from`. An over-wide span is clamped server-side. Required. */
+    to: string;
+    /** Optional party-size hint (1 to 50). Accepted for forward-compatibility; v1 does not filter slots by it (read each slot's `seatsRemaining` instead). */
+    partySize?: number;
+}
+/** The availability read response for a bookable product. */
+interface AvailabilityResponse {
+    /** The computed open slots across the effective window, in chronological order. */
+    slots: AvailabilitySlot[];
+    /** IANA timezone the slots are expressed in for display (e.g. `'Europe/Paris'`). */
+    timezone: string;
+    /** The effective window the slots cover. Its `to` may be earlier than requested when the span was clamped server-side. */
+    window: AvailabilityWindow;
+}
+/** Guest contact plus the chosen slot, for creating a reservation. No account needed. */
+interface BookingCreateData {
+    /** The chosen slot start, copied from an {@link AvailabilitySlot} `startsAt`. Full ISO 8601 datetime. */
+    startsAt: string;
+    /** Number of guests. Integer from 1 to 50; must fit the slot's `seatsRemaining`. */
+    partySize: number;
+    /** Guest full name. 1 to 200 chars. */
+    guestName: string;
+    /** Guest email. A valid address, max 320 chars. The confirmation echoes it. */
+    guestEmail: string;
+    /** Optional guest phone number. 3 to 40 chars when provided. */
+    guestPhone?: string;
+}
+/** A confirmed reservation returned after a successful booking. */
+interface Booking {
+    /** Guest-safe reservation reference (opaque `'bkg_...'` id) for the buyer's records. */
+    reference: string;
+    /**
+     * Reservation status. Always `'confirmed'` in v1: a storefront booking is
+     * confirmed immediately because payment is taken on-site, never charged online.
+     */
+    status: 'confirmed';
+    /** The booked slot start as an ISO 8601 datetime. */
+    startsAt: string;
+    /** The booked slot end as an ISO 8601 datetime, derived from the resource slot duration. */
+    endsAt: string;
+    /** Number of guests on the reservation. */
+    partySize: number;
+    /** The guest name as submitted, echoed for the receipt. */
+    guestName: string;
+    /** The guest email as submitted, echoed for the receipt. */
+    guestEmail: string;
+}
+
 /**
  * Base request options available on every SDK method.
  * These override the defaults set in {@link LynkowConfig}.
@@ -5797,18 +5925,26 @@ declare class ConsentService {
     private configCache;
     private injectedScriptIds;
     private themeCleanup;
+    private retry;
     constructor(config: InternalConfig, events: EventEmitter);
     /**
      * Fetches the cookie consent configuration from the API. The result is
      * cached in memory for the lifetime of the service instance (not TTL-based).
      * Works on both server and browser.
      *
+     * Transient failures (HTTP 429, HTTP 503, and network errors) are
+     * automatically retried with backoff, according to the client `retry`
+     * config (enabled by default; disable with `retry: false` in
+     * `createClient`).
+     *
      * @returns A `CookieConfig` object with banner settings, categories, texts,
      *   theming options, and third-party script definitions.
-     * @throws {Error} If the API request fails (non-2xx response). The SDK
-     *   does not wrap this in a {@link LynkowError} for this endpoint,
-     *   since consent config is fetched via a raw `fetch` call rather than
-     *   the shared request pipeline.
+     * @throws {Error} If the API responds with a non-2xx status, the call
+     *   rejects with a plain `Error` (NOT a {@link LynkowError}): this endpoint
+     *   reads the response body directly rather than going through the shared
+     *   request pipeline. However, once retries are exhausted, a persistent
+     *   network failure surfaces as a {@link LynkowError} with code
+     *   `NETWORK_ERROR`.
      *
      * @example
      * ```typescript
@@ -6480,6 +6616,167 @@ declare class MediaHelperService {
     private parseImageUrl;
 }
 
+/**
+ * Service for reading a site's published product catalogue.
+ *
+ * Accessible via `lynkow.products`. Returns only PUBLISHED products. Requires a
+ * publishable key: pass `publishableKey` to `createClient(...)` so every request
+ * carries it (commerce routes reject calls without a valid key). Responses are
+ * cached in-memory for 5 minutes (SHORT TTL) when a cache adapter is configured
+ * on the client.
+ *
+ * @example
+ * ```typescript
+ * const lynkow = createClient({ siteId: '...', publishableKey: 'lkw_pk_...' })
+ *
+ * // List published products
+ * const { data, meta } = await lynkow.products.list({ limit: 12, kind: 'bookable' })
+ *
+ * // Read a single product by slug or `prod_` wire id
+ * const product = await lynkow.products.getBySlug('sunset-dinner-cruise')
+ * ```
+ */
+declare class ProductsService extends BaseService {
+    /**
+     * Retrieves a paginated list of published products, sorted by creation date
+     * (newest first by default). Cached for 5 minutes per unique filter combination.
+     *
+     * @param filters - Optional {@link ProductsFilters}: `page`/`limit`, `search`, `kind`, `sortBy`/`sortOrder`.
+     * @param options - Base request options (locale override, custom fetch options).
+     * @returns A {@link ProductsListResponse} with `data` (published {@link Product}[]) and `meta` (pagination info).
+     * @throws {LynkowError} With code `'UNAUTHORIZED'` if no valid publishable key is set.
+     *
+     * @example
+     * ```typescript
+     * const { data, meta } = await lynkow.products.list({ page: 1, limit: 12, kind: 'bookable' })
+     * ```
+     */
+    list(filters?: ProductsFilters, options?: BaseRequestOptions): Promise<ProductsListResponse>;
+    /**
+     * Retrieves a single published product by its `prod_...` wire id or its slug.
+     * Cached for 5 minutes per id/slug.
+     *
+     * Named `getBySlug` (not `get`) to match the SDK convention: `BaseService`
+     * reserves a protected `get()` that the shared caching path dispatches to, so a
+     * public `get()` on a service would hijack it. Mirrors `contents.getBySlug` and
+     * `reviews.getBySlug`, both of which also accept an id or a slug.
+     *
+     * @param idOrSlug - The product's `prod_...` wire id or its URL slug.
+     * @param options - Base request options (locale override, custom fetch options).
+     * @returns The {@link Product}.
+     * @throws {LynkowError} With code `'NOT_FOUND'` if the product is missing, draft, or archived.
+     *
+     * @example
+     * ```typescript
+     * const product = await lynkow.products.getBySlug('sunset-dinner-cruise')
+     * console.log(`${(product.priceCents / 100).toFixed(2)} ${product.currency}`)
+     * ```
+     */
+    getBySlug(idOrSlug: string, options?: BaseRequestOptions): Promise<Product>;
+}
+
+/**
+ * Service for reading a bookable product's availability and creating guest
+ * reservations. Accessible via `lynkow.reservations`.
+ *
+ * Requires a publishable key: pass `publishableKey` to `createClient(...)` so
+ * every request carries it. Reservation routes reject calls without a valid key.
+ * Payment is taken on-site: a successful booking is `confirmed` immediately,
+ * never charged online. Anti-spam honeypot fields are injected automatically on
+ * `bookings.create`; on reCAPTCHA-protected storefronts pass
+ * `options.recaptchaToken`. Availability is not cached (it changes on every booking).
+ *
+ * @example
+ * ```typescript
+ * const lynkow = createClient({ siteId: '...', publishableKey: 'lkw_pk_...' })
+ *
+ * const { slots, timezone } = await lynkow.reservations.availability('sunset-dinner-cruise', {
+ *   from: '2026-07-10',
+ *   to: '2026-07-17',
+ * })
+ *
+ * const booking = await lynkow.reservations.bookings.create('sunset-dinner-cruise', {
+ *   startsAt: slots[0].startsAt,
+ *   partySize: 2,
+ *   guestName: 'Alice Martin',
+ *   guestEmail: 'alice@example.com',
+ * })
+ * ```
+ */
+declare class ReservationsService extends BaseService {
+    /**
+     * Client-creation timestamp anchoring the anti-spam timing window on
+     * `bookings.create`. The server rejects a submission whose age (`Date.now()`
+     * minus this value) is below its minimum fill time (too fast, likely a bot)
+     * or above its maximum form lifetime (stale). Captured once at client
+     * creation, so a very long-lived client eventually drifts past the maximum
+     * window.
+     */
+    private sessionStartTime;
+    constructor(config: InternalConfig);
+    /** Nested booking-write surface: `lynkow.reservations.bookings.create(...)`. */
+    readonly bookings: {
+        create: (productIdOrSlug: string, data: BookingCreateData, options?: SubmitOptions & BaseRequestOptions) => Promise<Booking>;
+    };
+    /**
+     * Retrieves the computed open slots for a bookable product across a date range.
+     * Not cached: availability changes as other buyers book.
+     *
+     * @param productIdOrSlug - The bookable product's `prod_...` wire id or its slug.
+     * @param filters - {@link AvailabilityFilters}: `from` and `to` (calendar dates `YYYY-MM-DD`, required, `to` not before `from`) and an optional `partySize`.
+     * @returns An {@link AvailabilityResponse} with `slots` (chronological {@link AvailabilitySlot}[]), the display `timezone`, and the effective `window`.
+     * @throws {LynkowError} With code `'NOT_FOUND'` if the product is missing or not bookable; `'UNAUTHORIZED'` if no valid publishable key is set.
+     *
+     * @example
+     * ```typescript
+     * const { slots, timezone } = await lynkow.reservations.availability('sunset-dinner-cruise', {
+     *   from: '2026-07-10',
+     *   to: '2026-07-17',
+     *   partySize: 2,
+     * })
+     * ```
+     */
+    availability(productIdOrSlug: string, filters: AvailabilityFilters): Promise<AvailabilityResponse>;
+    /**
+     * Creates a guest reservation for a chosen slot. No account required. Tuned
+     * for the in-browser guest flow: the client is created around page load and
+     * the buyer books moments later.
+     *
+     * Anti-spam honeypot + timestamp fields are injected automatically. The
+     * honeypot is always empty, so the honeypot/content silent-acknowledgement
+     * path (HTTP 200, no error) is unreachable through the SDK. The timestamp
+     * check, however, is a real thrown-error window relative to client creation:
+     * a booking sent sooner than the server's minimum fill time (default 3s)
+     * after `createClient(...)` is rejected `TOO_MANY_REQUESTS` (HTTP 429), and
+     * one sent later than the server's maximum form lifetime (default ~1h) is
+     * rejected `BAD_REQUEST` (HTTP 400, "form expired"). Handle both when driving
+     * this from a long-lived or non-browser client.
+     *
+     * If the storefront enforces reCAPTCHA (rather than the default honeypot),
+     * pass `options.recaptchaToken`; without it the server rejects the booking
+     * `BAD_REQUEST` (HTTP 400, "reCAPTCHA required"). Mirrors `reviews.submit`.
+     *
+     * @param productIdOrSlug - The bookable product's `prod_...` wire id or its slug.
+     * @param data - {@link BookingCreateData}: chosen `startsAt`, `partySize`, and guest `guestName`/`guestEmail`/optional `guestPhone`.
+     * @param options - Optional {@link SubmitOptions} + request options: `recaptchaToken` (required on reCAPTCHA-protected storefronts), a `locale` override, and `fetchOptions` (e.g. an `AbortSignal`).
+     * @returns The created {@link Booking} (reference, status, slot instants, party size, echoed name/email).
+     * @throws {LynkowError} With code `'VALIDATION_ERROR'` (HTTP 422) on bad input or a filled/unavailable slot; `'NOT_FOUND'` if not a bookable product; `'UNAUTHORIZED'` if no valid publishable key is set; `'TOO_MANY_REQUESTS'` (HTTP 429) if sent within the server's minimum fill time after client creation (anti-spam too-fast); `'BAD_REQUEST'` (HTTP 400) if sent past the server's maximum form lifetime after client creation (anti-spam expired) or if reCAPTCHA is enforced and no `recaptchaToken` is supplied.
+     *
+     * @example
+     * ```typescript
+     * const booking = await lynkow.reservations.bookings.create('sunset-dinner-cruise', {
+     *   startsAt: '2026-07-10T18:00:00.000Z',
+     *   partySize: 2,
+     *   guestName: 'Alice Martin',
+     *   guestEmail: 'alice@example.com',
+     *   guestPhone: '+33 6 12 34 56 78',
+     * })
+     * console.log(`Reservation ${booking.reference} is ${booking.status}. Pay on-site.`)
+     * ```
+     */
+    private createBooking;
+}
+
 /**
  * Lynkow SDK Client
  * Main entry point for the SDK
@@ -6590,6 +6887,18 @@ interface Client extends LynkowClient {
      * Lynkow Instant Search service
      */
     search: SearchService;
+    /**
+     * Storefront product catalogue service (commerce).
+     * Provides `list()` and `getBySlug()` for published products.
+     * Requires a `publishableKey` on the client.
+     */
+    products: ProductsService;
+    /**
+     * Storefront reservations service (commerce).
+     * Provides `availability()` and the nested `bookings.create()` for bookable products.
+     * Requires a `publishableKey` on the client.
+     */
+    reservations: ReservationsService;
 }
 /**
  * Creates a Lynkow client instance (SDK v3)