lynkow 1.34.0 → 1.40.1

package/README.md

@@ -69,6 +69,12 @@ interface ClientConfig {
   // Optional: Enable SDK in-memory cache (default: false)
   // Set to true for browser SPAs that benefit from localStorage caching
   cache?: boolean
+
+  // Optional: Auto-retry transient failures on reads (default: true)
+  // Retries 429/503/network errors with exponential backoff, honoring the
+  // server's Retry-After header. Submissions (POST) are never retried.
+  // Set to false to disable, or tune with { retries, backoffMs, maxDelayMs }
+  retry?: RetryConfig | boolean
 }
 ```
 

package/dist/index.d.mts

@@ -23,16 +23,27 @@ declare function createCache(config?: CacheConfig): {
 };
 type Cache = ReturnType<typeof createCache>;
 
+/** Resolved (fully-defaulted) retry policy used by the fetch layer. */
+interface ResolvedRetry {
+    retries: number;
+    backoffMs: number;
+    maxDelayMs: number;
+}
+
 /**
  * Normalized internal configuration
  */
 interface InternalConfig {
     siteId: string;
     baseUrl: string;
+    /** Optional publishable key sent as the `X-Lynkow-Pk` header on every storefront API request. */
+    publishableKey?: string;
     locale?: string;
     fetchOptions: RequestInit;
     /** Optional cache manager for caching responses */
     cache?: Cache;
+    /** Optional retry policy for transient failures; normalized once in the service constructor. */
+    retry?: RetryConfig | boolean;
 }
 /**
  * Base service that all specific services inherit from
@@ -40,6 +51,7 @@ interface InternalConfig {
 declare abstract class BaseService {
     protected config: InternalConfig;
     protected cache?: Cache;
+    protected retry: ResolvedRetry;
     constructor(config: InternalConfig);
     /**
      * Builds the full URL for an endpoint
@@ -1782,6 +1794,56 @@ interface SearchProfilePublic {
     maxLimit: number;
 }
 
+/**
+ * Automatic retry policy for transient failures.
+ *
+ * The SDK retries a request when it fails in a way that is likely to succeed on
+ * a second attempt, using exponential backoff and honoring the server's
+ * `Retry-After` header when present. Retries are enabled by default, which keeps
+ * large static-site builds (SSG/ISR prerender fires many requests at once) from
+ * failing the whole build on a short-lived rate limit.
+ *
+ * Only reads are retried: `GET` requests and text endpoints (sitemap, robots,
+ * llms.txt, markdown) are retried on HTTP 429, HTTP 503, and network errors.
+ * Submissions (`POST`, e.g. form and review submits) are never retried, so a
+ * request that may have been processed is not sent twice.
+ *
+ * Pass `retry: false` to disable retries entirely.
+ *
+ * @example
+ * ```typescript
+ * // Tune the retry policy
+ * createClient({ siteId, retry: { retries: 5, backoffMs: 250, maxDelayMs: 10000 } })
+ *
+ * // Disable retries
+ * createClient({ siteId, retry: false })
+ * ```
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts after the initial request.
+     * Set to `0` to disable retries (equivalent to `retry: false`).
+     *
+     * @default 3
+     */
+    retries?: number;
+    /**
+     * Base delay in milliseconds for exponential backoff, used when the response
+     * carries no `Retry-After` header. The nth retry (0-indexed) waits about
+     * `backoffMs * 2^n` plus a small random jitter, capped by `maxDelayMs`.
+     *
+     * @default 500
+     */
+    backoffMs?: number;
+    /**
+     * Upper bound in milliseconds for any single wait between attempts. Also caps
+     * a large `Retry-After` value, so one rate-limited request can never stall a
+     * build indefinitely.
+     *
+     * @default 20000
+     */
+    maxDelayMs?: number;
+}
 /**
  * Configuration for creating a Lynkow client instance.
  * Only `siteId` is required; all other options have sensible defaults.
@@ -1800,11 +1862,22 @@ interface LynkowConfig {
      * UUID of the Lynkow site to connect to.
      * Found in the admin dashboard under Site Settings.
      * Must be a valid UUID v4 format (lowercase hex with dashes).
-     * Sent as the `X-Site-Id` header on every API request.
+     * Interpolated into the path of every request (`/storefront/:siteId/...`)
+     * to identify the tenant. It is not sent as a header.
      *
      * @example '550e8400-e29b-41d4-a716-446655440000'
      */
     siteId: string;
+    /**
+     * Optional publishable key that identifies this client to the Lynkow
+     * storefront API. Copied from the admin dashboard under Site Settings.
+     * It has the form `lkw_pk_` followed by 24 characters.
+     * When set, it is sent as the `X-Lynkow-Pk` header on every storefront API request the client makes.
+     * Optional on CMS content routes; required on future commerce routes.
+     *
+     * @example 'lkw_pk_9f8g7h6j5k4w3m2n1p0qrstv'
+     */
+    publishableKey?: string;
     /**
      * Base URL of the Lynkow API.
      * Must not include a trailing slash.
@@ -1839,6 +1912,25 @@ interface LynkowConfig {
      * ```
      */
     fetchOptions?: RequestInit;
+    /**
+     * Automatic retry policy for transient failures (HTTP 429, HTTP 503, and
+     * network errors on read requests). Enabled by default with sensible backoff
+     * that honors the server's `Retry-After` header. Pass `false` to disable, or a
+     * {@link RetryConfig} object to tune it. See {@link RetryConfig} for the full
+     * behavior and defaults.
+     *
+     * @default true
+     *
+     * @example
+     * ```typescript
+     * // Disable retries
+     * { retry: false }
+     *
+     * // Tune retries
+     * { retry: { retries: 5, backoffMs: 250, maxDelayMs: 10000 } }
+     * ```
+     */
+    retry?: RetryConfig | boolean;
 }
 /**
  * Lynkow Client interface -- the main SDK entry point.
@@ -2382,13 +2474,13 @@ interface Category {
      * - `'standard'`: articles use the TipTap rich text editor (stored in `Content.body`)
      * - `'structured'`: articles use custom fields defined by the category's schema (stored in `Content.customData`)
      *
-     * Only present in detail responses (`GET /public/categories/:id`), not in lightweight
+     * Only present in detail responses (`GET /storefront/categories/:id`), not in lightweight
      * list projections (e.g. when categories are embedded in content responses).
      */
     contentMode?: 'standard' | 'structured';
     /**
      * Parent category in the hierarchy. Present when the API eagerly loads
-     * the parent relation (e.g. `GET /public/contents/slug/:slug` returns
+     * the parent relation (e.g. `GET /storefront/contents/slug/:slug` returns
      * each category's parent so consumers can build a breadcrumb in a single
      * request). `null` for root-level categories. `undefined` when the
      * endpoint did not include parent data.
@@ -2401,7 +2493,7 @@ interface Category {
 }
 /**
  * Category with URL path, description, image, and content count.
- * Returned by list endpoints (`GET /public/categories`).
+ * Returned by list endpoints (`GET /storefront/categories`).
  *
  * Extends {@link Category} with display-oriented fields useful for rendering
  * category listing pages, navigation menus, and sidebar widgets.
@@ -2478,7 +2570,7 @@ interface CategoryWithCount extends Category {
 }
 /**
  * Full category detail with parent relationship.
- * Returned by single-category endpoints (`GET /public/categories/:id`).
+ * Returned by single-category endpoints (`GET /storefront/categories/:id`).
  *
  * Extends {@link CategoryWithCount} with the parent category reference,
  * enabling you to reconstruct the category hierarchy.
@@ -2505,7 +2597,7 @@ interface CategoryDetail extends CategoryWithCount {
     jsonLdExclusions?: string[];
 }
 /**
- * Recursive category tree node, returned by the tree endpoint (`GET /public/categories/tree`).
+ * Recursive category tree node, returned by the tree endpoint (`GET /storefront/categories/tree`).
  *
  * Each node contains its full {@link CategoryWithCount} data plus a `children` array
  * of nested sub-categories. The tree is pre-sorted by the API.
@@ -2838,15 +2930,15 @@ interface TipTapNode {
 type ContentBody = string;
 /**
  * Lightweight content representation returned in paginated list endpoints
- * (`GET /public/contents`).
+ * (`GET /storefront/contents`).
  *
  * Omits the full body, SEO fields, and relations to minimize payload size.
- * Use `Content` (from `GET /public/contents/:idOrSlug`) for the complete data.
+ * Use `Content` (from `GET /storefront/contents/:idOrSlug`) for the complete data.
  */
 interface ContentSummary {
     /**
      * Unique numeric content ID. Auto-incremented.
-     * Use this for API calls like `GET /public/contents/:id`.
+     * Use this for API calls like `GET /storefront/contents/:id`.
      */
     id: number;
     /**
@@ -2857,7 +2949,7 @@ interface ContentSummary {
     /**
      * URL-friendly slug, unique within the site for this locale.
      * Lowercase, hyphenated (e.g. `'my-article-title'`). Max 500 characters.
-     * Can be used instead of `id` in API calls: `GET /public/contents/:slug`.
+     * Can be used instead of `id` in API calls: `GET /storefront/contents/:slug`.
      */
     slug: string;
     /**
@@ -2917,7 +3009,7 @@ interface ContentSummary {
 }
 /**
  * Full content item with body, SEO metadata, structured data, and relations.
- * Returned by single-content endpoints (`GET /public/contents/:idOrSlug`).
+ * Returned by single-content endpoints (`GET /storefront/contents/:idOrSlug`).
  *
  * Extends {@link ContentSummary} with all the fields omitted from list responses.
  */
@@ -3187,19 +3279,19 @@ interface Alternate {
  * Lightweight page representation returned in list endpoints.
  * Contains basic identification and routing information.
  *
- * Use {@link Page} (from `GET /public/pages/:idOrSlug`) for the full page
+ * Use {@link Page} (from `GET /storefront/pages/:idOrSlug`) for the full page
  * including resolved data, SEO settings, and alternates.
  */
 interface PageSummary {
     /**
      * Unique numeric page ID. Auto-incremented.
-     * Use this for API calls like `GET /public/pages/:id`.
+     * Use this for API calls like `GET /storefront/pages/:id`.
      */
     id: number;
     /**
      * URL-friendly slug, unique within the site for this locale.
      * Lowercase, hyphenated (e.g. `'about-us'`). Max 255 characters.
-     * Can be used instead of `id` in API calls: `GET /public/pages/:slug`.
+     * Can be used instead of `id` in API calls: `GET /storefront/pages/:slug`.
      */
     slug: string;
     /**
@@ -3228,7 +3320,7 @@ interface PageSummary {
 }
 /**
  * Full page with resolved data sources, SEO settings, and locale alternates.
- * Returned by single-page endpoints (`GET /public/pages/:idOrSlug`).
+ * Returned by single-page endpoints (`GET /storefront/pages/:idOrSlug`).
  *
  * Pages are layout-driven containers whose content comes from **DataSources** —
  * configurable queries that fetch content, categories, forms, or other data.
@@ -3287,7 +3379,7 @@ interface Page extends PageSummary {
      *
      * `undefined` on responses from older API versions that do not populate
      * the cascade; in that case, fall back to the dedicated
-     * `/public/:siteId/pages/:slug/json-ld` endpoint which always returns
+     * `/storefront/:siteId/pages/:slug/json-ld` endpoint which always returns
      * the array directly under `data`.
      */
     structuredData?: {
@@ -3704,7 +3796,7 @@ interface FormSchema {
 }
 /**
  * A public form available for submission.
- * Returned by `GET /public/{siteId}/forms/{slug}` and unwrapped from the
+ * Returned by `GET /storefront/{siteId}/forms/{slug}` and unwrapped from the
  * `{ data }` envelope by `forms.getBySlug()`.
  *
  * Use `schema.fields` to dynamically render the form fields, `schema.settings`
@@ -3726,8 +3818,8 @@ interface Form {
     /**
      * URL-friendly slug, unique within the site.
      * Lowercase, hyphenated (e.g. `'contact-us'`). Max 255 characters.
-     * Used to fetch the form: `GET /public/{siteId}/forms/{slug}`.
-     * Also used as the submission endpoint: `POST /public/{siteId}/forms/{slug}/submissions`.
+     * Used to fetch the form: `GET /storefront/{siteId}/forms/{slug}`.
+     * Also used as the submission endpoint: `POST /storefront/{siteId}/forms/{slug}/submissions`.
      */
     slug: string;
     /**
@@ -3847,7 +3939,7 @@ interface ReviewResponse {
 interface Review {
     /**
      * Unique numeric review ID. Auto-incremented.
-     * Use this for API calls like `GET /public/reviews/:id`.
+     * Use this for API calls like `GET /storefront/reviews/:id`.
      */
     id: number;
     /**
@@ -3914,7 +4006,7 @@ interface Review {
 }
 /**
  * Public review settings for a site.
- * Returned by `GET /public/reviews/settings`.
+ * Returned by `GET /storefront/reviews/settings`.
  *
  * Use these settings to:
  * - Check if reviews are enabled before rendering a review form
@@ -3983,7 +4075,7 @@ interface ReviewSettings {
     };
 }
 /**
- * Data payload for submitting a new review via `POST /public/reviews`.
+ * Data payload for submitting a new review via `POST /storefront/reviews`.
  *
  * Required fields: `authorName`, `rating`, `content`.
  * Optional fields depend on `ReviewSettings.fields` configuration.
@@ -4796,7 +4888,7 @@ interface CategoryDetailResponse {
  * Response from `tags.list()`.
  * Paginated since SDK 1.32.2 (the wire was already returning `meta`; the SDK
  * type now exposes it). Server-side default is 20 items per page on
- * `/v1/tags` and `/public/.../tags`, with `maxLimit=100` (ADR-0022 D3).
+ * `/v1/tags` and `/storefront/.../tags`, with `maxLimit=100` (ADR-0022 D3).
  */
 interface TagsListResponse {
     /**
@@ -5087,9 +5179,9 @@ interface BaseRequestOptions {
  * Pagination options for list endpoints.
  *
  * All values are 1-based integers. The server default is 20 items per page
- * on public-tier endpoints (`/public`, `/v1`) and 50 on admin-tier
+ * on public-tier endpoints (`/storefront`, `/v1`) and 50 on admin-tier
  * endpoints (`/api`, `/admin`), per ADR-0022 D3. Documented exceptions:
- * SSG endpoints like `/public/.../categories/:slug` default to 500.
+ * SSG endpoints like `/storefront/.../categories/:slug` default to 500.
  */
 interface PaginationOptions {
     /**
@@ -5100,9 +5192,9 @@ interface PaginationOptions {
     page?: number;
     /**
      * Maximum number of items per page.
-     * Server default is 20 on public-tier endpoints (`/public`, `/v1`).
+     * Server default is 20 on public-tier endpoints (`/storefront`, `/v1`).
      * Maximum allowed value is 100 (except documented SSG exceptions like
-     * `/public/.../categories/:slug` which permit up to 500).
+     * `/storefront/.../categories/:slug` which permit up to 500).
      * Values above the per-endpoint maximum are silently capped by the API.
      */
     limit?: number;
@@ -5195,7 +5287,7 @@ interface CategoryOptions extends PaginationOptions {
  *
  * Pagination + locale. The public `/v1/tags` endpoint does not expose
  * search or sort on its public surface. `limit` defaults to 20 server-side
- * on the public-tier mounts (`/public/.../tags`, `/v1/tags`) per
+ * on the public-tier mounts (`/storefront/.../tags`, `/v1/tags`) per
  * ADR-0022 D3, with `maxLimit=100`.
  */
 interface TagsListFilters extends PaginationOptions {
@@ -6902,4 +6994,4 @@ declare function renderJsonLdGraph(nodes: object[] | null | undefined): string;
  */
 declare function mergeIntoGraph(server: object[] | null | undefined, custom: object[] | null | undefined): object[];
 
-export { type Alternate, AnalyticsService, type ApiErrorDetail, type Author, type BaseRequestOptions, BlocksService, BrandingService, type CategoriesListResponse, CategoriesService, type Category, type CategoryDetail, type CategoryDetailResponse, type CategoryOptions, type CategoryResolveResponse, type CategoryTreeNode, type CategoryTreeResponse, type CategoryWithCount, type Client, type ClientConfig, type ConsentCategories, type ConsentLogResponse, ConsentService, type Content, type ContentBody, type ContentResolveResponse, type ContentSchema, type ContentSummary, type ContentsFilters, type ContentsListResponse, ContentsService, type CookieCategory, type CookieConfig, type CookiePreferences, type CookieTexts, CookiesService, type EnhancementsInitOptions, EnhancementsService, type ErrorCode, type EventData, type EventName, type Form, type FormCondition, type FormField, type FormFieldOption, type FormFieldPhoneOptions, type FormFieldType, type FormFieldValidation, type FormPage, type FormSchema, type FormSchemaSettings, type FormSettings, type FormSubmitData, type FormSubmitResponse, FormsService, type GlobalBlock, type GlobalBlockResponse, type ImageVariants, type JsonLdGraphConfig, type JsonLdNode, type JsonLdNodeSource, type LegalDocument, LegalService, type LynkowClient, type LynkowConfig, LynkowError, type LynkowEvents, MediaHelperService, type Page, type PageSeo, type PageSummary, type PagesListResponse, PagesService, type PageviewData, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type Path, type PathsListResponse, PathsService, type Redirect, type ResolveResponse, type Review, type ReviewResponse, type ReviewSettings, type ReviewSubmitData, type ReviewSubmitResponse, type ReviewsFilters, type ReviewsListResponse, ReviewsService, type SchemaField, type SchemaFieldOption, type SchemaFieldType, type SchemaFieldValidation, type SearchConfig, type SearchHit, type SearchOptions, type SearchProfilePublic, type SearchResponse, SearchService, SeoService, type SiteConfig, type SiteConfigResponse, SiteService, type SortOptions, type SrcsetOptions, type SubmitOptions, type Tag, type TagsListFilters, type TagsListResponse, TagsService, type TipTapMark, type TipTapNode, type TransformOptions, browserOnly, browserOnlyAsync, createClient, createLynkowClient, detectSiteTheme, isBrowser, isCategoryResolve, isContentResolve, isLynkowError, isServer, mergeIntoGraph, onSiteThemeChange, renderJsonLdGraph };
+export { type Alternate, AnalyticsService, type ApiErrorDetail, type Author, type BaseRequestOptions, BlocksService, BrandingService, type CategoriesListResponse, CategoriesService, type Category, type CategoryDetail, type CategoryDetailResponse, type CategoryOptions, type CategoryResolveResponse, type CategoryTreeNode, type CategoryTreeResponse, type CategoryWithCount, type Client, type ClientConfig, type ConsentCategories, type ConsentLogResponse, ConsentService, type Content, type ContentBody, type ContentResolveResponse, type ContentSchema, type ContentSummary, type ContentsFilters, type ContentsListResponse, ContentsService, type CookieCategory, type CookieConfig, type CookiePreferences, type CookieTexts, CookiesService, type EnhancementsInitOptions, EnhancementsService, type ErrorCode, type EventData, type EventName, type Form, type FormCondition, type FormField, type FormFieldOption, type FormFieldPhoneOptions, type FormFieldType, type FormFieldValidation, type FormPage, type FormSchema, type FormSchemaSettings, type FormSettings, type FormSubmitData, type FormSubmitResponse, FormsService, type GlobalBlock, type GlobalBlockResponse, type ImageVariants, type JsonLdGraphConfig, type JsonLdNode, type JsonLdNodeSource, type LegalDocument, LegalService, type LynkowClient, type LynkowConfig, LynkowError, type LynkowEvents, MediaHelperService, type Page, type PageSeo, type PageSummary, type PagesListResponse, PagesService, type PageviewData, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type Path, type PathsListResponse, PathsService, type Redirect, type ResolveResponse, type RetryConfig, type Review, type ReviewResponse, type ReviewSettings, type ReviewSubmitData, type ReviewSubmitResponse, type ReviewsFilters, type ReviewsListResponse, ReviewsService, type SchemaField, type SchemaFieldOption, type SchemaFieldType, type SchemaFieldValidation, type SearchConfig, type SearchHit, type SearchOptions, type SearchProfilePublic, type SearchResponse, SearchService, SeoService, type SiteConfig, type SiteConfigResponse, SiteService, type SortOptions, type SrcsetOptions, type SubmitOptions, type Tag, type TagsListFilters, type TagsListResponse, TagsService, type TipTapMark, type TipTapNode, type TransformOptions, browserOnly, browserOnlyAsync, createClient, createLynkowClient, detectSiteTheme, isBrowser, isCategoryResolve, isContentResolve, isLynkowError, isServer, mergeIntoGraph, onSiteThemeChange, renderJsonLdGraph };