lynkow 1.33.0 → 1.40.0

package/README.md

@@ -39,7 +39,7 @@ const lynkow = createClient({
 // Fetch blog posts
 const { data: posts, meta } = await lynkow.contents.list({
   page: 1,
-  perPage: 10,
+  limit: 10,
   category: 'tech',
 })
 
@@ -153,7 +153,7 @@ The SDK is isomorphic and works on both browser and server environments. Some fe
 // List contents with filters
 const { data, meta } = await lynkow.contents.list({
   page: 1,
-  perPage: 10,
+  limit: 10,
   category: 'tech',
   tag: 'javascript',
   search: 'tutorial',
@@ -169,15 +169,15 @@ const content = await lynkow.contents.getBySlug('my-article')
 
 ```typescript
 // List all categories
-const { data } = await lynkow.categories.list()
+const { categories } = await lynkow.categories.list()
 
 // Get category tree (nested)
-const { data: tree } = await lynkow.categories.tree()
+const { tree } = await lynkow.categories.tree()
 
 // Get category with its contents
 const { category, contents } = await lynkow.categories.getBySlug('tech', {
   page: 1,
-  perPage: 10,
+  limit: 10,
 })
 ```
 
@@ -248,7 +248,7 @@ const result = await lynkow.forms.submit(
 // List approved reviews
 const { data, meta } = await lynkow.reviews.list({
   minRating: 4,
-  perPage: 10,
+  limit: 10,
 })
 
 // Get review settings

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 */
@@ -105,7 +107,7 @@ declare class ContentsService extends BaseService {
      * 5 minutes per unique filter combination.
      *
      * @param filters - Optional filters to narrow down results:
-     *   - `page` / `limit` — pagination (defaults to page 1, 15 items)
+     *   - `page` / `limit` - pagination (defaults to page 1, 20 items)
      *   - `category` — filter by category slug (e.g. `'tech'`, `'news'`)
      *   - `tag` — filter by tag slug (e.g. `'featured'`)
      *   - `search` — full-text search across title and body
@@ -185,10 +187,10 @@ declare class ContentsService extends BaseService {
  * const lynkow = createClient({ siteId: '...' })
  *
  * // Flat list with content counts
- * const { data } = await lynkow.categories.list()
+ * const { categories } = await lynkow.categories.list()
  *
  * // Hierarchical tree
- * const { data } = await lynkow.categories.tree()
+ * const { tree } = await lynkow.categories.tree()
  *
  * // Category detail with paginated articles
  * const { category, contents } = await lynkow.categories.getBySlug('tech')
@@ -201,13 +203,13 @@ declare class CategoriesService extends BaseService {
      * Cached for 5 minutes per locale.
      *
      * @param options - Request options; use `locale` to fetch localized category names
-     * @returns An object containing `data` (array of `CategoryWithCount` with name, slug, path,
+     * @returns An object containing `categories` (array of `CategoryWithCount` with name, slug, path,
      *   contentCount, image, description), `blogUrlMode` (`'flat'` or `'nested'`), and `locale`
      *
      * @example
      * ```typescript
-     * const { data, blogUrlMode } = await lynkow.categories.list()
-     * data.forEach(cat => {
+     * const { categories, blogUrlMode } = await lynkow.categories.list()
+     * categories.forEach(cat => {
      *   console.log(`${cat.name} (${cat.contentCount} articles)`)
      * })
      * ```
@@ -220,14 +222,14 @@ declare class CategoriesService extends BaseService {
      * hierarchical navigation or breadcrumbs. Cached for 5 minutes per locale.
      *
      * @param options - Request options; use `locale` to fetch localized category names
-     * @returns An object containing `data` (array of `CategoryTreeNode`, each with a
+     * @returns An object containing `tree` (array of `CategoryTreeNode`, each with a
      *   `children` array of nested subcategories), `blogUrlMode`, and `locale`
      *
      * @example
      * ```typescript
-     * const { data } = await lynkow.categories.tree()
+     * const { tree } = await lynkow.categories.tree()
      * // Iterate root categories and their children
-     * data.forEach(root => {
+     * tree.forEach(root => {
      *   console.log(root.name)
      *   root.children.forEach(child => {
      *     console.log(`  - ${child.name}`)
@@ -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.
@@ -2356,10 +2369,11 @@ interface JsonLdGraphConfig {
  */
 interface Category {
     /**
-     * Unique numeric category ID. Auto-incremented.
-     * Use this for API calls like `GET /public/categories/:id`.
+     * Unique category ID (UUID, e.g. `'550e8400-e29b-41d4-a716-446655440000'`).
+     * Stable across renames and slug changes, so it is safe to use as a cache
+     * or list key. Public category endpoints are addressed by slug, not by ID.
      */
-    id: number;
+    id: string;
     /**
      * Category display name in the requested locale (e.g. `'Technology'`, `'Tutorials'`).
      * Max 255 characters.
@@ -2381,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.
@@ -2400,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.
@@ -2436,6 +2450,13 @@ interface CategoryWithCount extends Category {
      * Does not include content from child categories — each category counts independently.
      */
     contentCount: number;
+    /**
+     * Manual sort position configured in the admin. Defaults to `0`.
+     * List and tree endpoints return categories sorted alphabetically by name;
+     * use this value to apply the admin-defined ordering client-side
+     * (lower values first).
+     */
+    displayOrder: number;
     /**
      * CDN-optimized image variants of the category image at multiple preset sizes.
      * `undefined` when no image is set or the site has no image transformations configured.
@@ -2470,18 +2491,18 @@ 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.
  */
 interface CategoryDetail extends CategoryWithCount {
     /**
-     * ID of the parent category, or `null` for root-level categories.
+     * UUID of the parent category, or `null` for root-level categories.
      * Use this to build breadcrumbs or reconstruct the category tree.
      * Categories support unlimited nesting depth.
      */
-    parentId: number | null;
+    parentId: string | null;
     /**
      * Category-level JSON-LD cascade nodes. Inherited by every content
      * attached to the category. Merged server-side into the content's
@@ -2497,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.
@@ -2830,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;
     /**
@@ -2849,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;
     /**
@@ -2909,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.
  */
@@ -3179,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;
     /**
@@ -3220,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.
@@ -3279,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?: {
@@ -3696,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`
@@ -3718,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;
     /**
@@ -3839,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;
     /**
@@ -3906,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
@@ -3975,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.
@@ -4709,7 +4730,7 @@ interface CategoriesListResponse {
      * Flat array of all categories with their published content count.
      * Not paginated -- all categories are returned in a single response.
      */
-    data: CategoryWithCount[];
+    categories: CategoryWithCount[];
     /**
      * How blog content URLs are constructed for this site:
      * - `'flat'`: URLs use slug only, e.g. `/blog/my-article`
@@ -4734,7 +4755,7 @@ interface CategoryTreeResponse {
      * Root-level category nodes, each containing nested `children` arrays.
      * Categories with a `parentId` appear as children of their parent node.
      */
-    data: CategoryTreeNode[];
+    tree: CategoryTreeNode[];
     /**
      * How blog content URLs are constructed for this site:
      * - `'flat'`: URLs use slug only, e.g. `/blog/my-article`
@@ -4788,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 {
     /**
@@ -5079,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 {
     /**
@@ -5092,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;
@@ -5187,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 {