lynkow 1.34.0 → 1.40.0

package/dist/index.d.mts

@@ -29,6 +29,8 @@ type Cache = ReturnType<typeof createCache>;
 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 */
@@ -1800,11 +1802,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.
@@ -2382,13 +2395,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 +2414,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 +2491,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 +2518,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 +2851,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 +2870,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 +2930,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 +3200,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 +3241,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 +3300,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 +3717,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 +3739,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 +3860,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 +3927,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 +3996,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 +4809,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 +5100,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 +5113,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 +5208,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 {

package/dist/index.d.ts

@@ -29,6 +29,8 @@ type Cache = ReturnType<typeof createCache>;
 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 */
@@ -1800,11 +1802,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.
@@ -2382,13 +2395,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 +2414,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 +2491,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 +2518,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 +2851,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 +2870,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 +2930,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 +3200,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 +3241,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 +3300,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 +3717,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 +3739,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 +3860,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 +3927,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 +3996,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 +4809,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 +5100,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 +5113,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 +5208,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 {