lynkow 3.8.75 → 3.8.77

package/dist/index.d.mts

@@ -154,9 +154,21 @@ declare class ContentsService extends BaseService {
      */
     getBySlug(slug: string, options?: BaseRequestOptions): Promise<Content>;
     /**
-     * Invalidates all cached content responses (lists and single articles).
-     * Call this after knowing content has been updated to force fresh data
-     * on the next request.
+     * Invalidate every cached response produced by this service (list
+     * queries, slug lookups, single-content fetches). Call after an admin
+     * mutation or on receipt of a `content.*` webhook so the next public
+     * request bypasses the 5-minute SWR cache and hits the origin.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * // In a Next.js route handler receiving a Lynkow webhook:
+     * if (event.type === 'content.updated') {
+     *   lynkow.contents.clearCache()
+     * }
+     * ```
      */
     clearCache(): void;
 }
@@ -251,9 +263,19 @@ declare class CategoriesService extends BaseService {
      */
     getBySlug(slug: string, options?: CategoryOptions & BaseRequestOptions): Promise<CategoryDetailResponse>;
     /**
-     * Invalidates all cached category responses (lists, tree, and detail views).
-     * Call this after knowing categories have been updated to force fresh data
-     * on the next request.
+     * Invalidate every cached category response (flat list, hierarchy
+     * tree, detail views with paginated contents). Call after an admin
+     * mutation or on receipt of a `category.*` webhook so the next public
+     * request bypasses the 30-minute SWR cache.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * // On category restructuring:
+     * lynkow.categories.clearCache()
+     * ```
      */
     clearCache(): void;
 }
@@ -287,9 +309,17 @@ declare class TagsService extends BaseService {
      */
     list(options?: BaseRequestOptions): Promise<TagsListResponse>;
     /**
-     * Invalidates all cached tag responses.
-     * Call this after knowing tags have been updated to force fresh data
-     * on the next request.
+     * Invalidate every cached tag response (lists, tag-filtered contents).
+     * Call after an admin mutation or on receipt of a `tag.*` webhook so
+     * the next public request bypasses the SWR cache.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * lynkow.tags.clearCache()
+     * ```
      */
     clearCache(): void;
 }
@@ -298,7 +328,14 @@ declare class TagsService extends BaseService {
  * Options for listing pages
  */
 interface PagesListOptions extends BaseRequestOptions {
-    /** Filter pages by tag (e.g., 'legal' for legal documents) */
+    /**
+     * Restrict results to pages carrying this tag slug (e.g. `'legal'` to
+     * list Privacy Policy + Terms of Service). Tags are declared on each
+     * page in the admin under SEO / Organization and used mainly for
+     * grouping unrelated pages that share a purpose.
+     *
+     * Omit to return every published page for the site.
+     */
     tag?: string;
 }
 /**
@@ -403,9 +440,19 @@ declare class PagesService extends BaseService {
      */
     getJsonLd(slug: string, options?: BaseRequestOptions): Promise<Record<string, unknown>>;
     /**
-     * Invalidates all cached page responses (lists, slug lookups, path lookups,
-     * and JSON-LD data). Call this after knowing pages have been updated to
-     * force fresh data on the next request.
+     * Invalidate every cached page response (lists, slug lookups, path
+     * lookups, and the JSON-LD endpoint). Call after an admin mutation or
+     * on receipt of a `page.*` webhook so the next public request bypasses
+     * the SWR cache and re-materializes the resolved data (including
+     * `structuredData.graph`).
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * lynkow.pages.clearCache()
+     * ```
      */
     clearCache(): void;
 }
@@ -479,6 +526,9 @@ declare class BlocksService extends BaseService {
      * @param slug - The block slug
      * @param options - Request options
      * @returns The resolved global block
+     * @throws {LynkowError} With code `'NOT_FOUND'` when the slug does not
+     *   match any global block for the site, `'NETWORK_ERROR'` on transport
+     *   failure. Same surface as {@link getBySlug}.
      *
      * @example
      * ```typescript
@@ -488,9 +538,18 @@ declare class BlocksService extends BaseService {
      */
     global(slug: string, options?: BaseRequestOptions): Promise<GlobalBlockResponse>;
     /**
-     * Invalidates all cached global block responses (site config and individual blocks).
-     * Call this after knowing global blocks have been updated to force fresh data
-     * on the next request.
+     * Invalidate every cached global block response (site config payload
+     * and per-slug lookups). Call after an admin mutation or on receipt of
+     * a `globalBlock.updated` webhook so the next public request hits the
+     * origin and re-resolves any referenced variables.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * lynkow.globals.clearCache()
+     * ```
      */
     clearCache(): void;
 }
@@ -586,8 +645,20 @@ declare class FormsService extends BaseService {
      */
     submit(slug: string, data: FormSubmitData, options?: SubmitOptions & BaseRequestOptions): Promise<FormSubmitResponse>;
     /**
-     * Invalidates all cached form schema responses. Call this if you know
-     * a form definition has changed and want to fetch the latest schema.
+     * Invalidate every cached form schema response. Call after an admin
+     * mutation or on receipt of a `form.*` webhook so the next public
+     * request re-fetches the latest field definitions (required fields,
+     * validators, spam settings).
+     *
+     * Does not affect form submissions, which are never cached.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * lynkow.forms.clearCache()
+     * ```
      */
     clearCache(): void;
 }
@@ -696,6 +767,9 @@ declare class ReviewsService extends BaseService {
      *   // Render email field as required
      * }
      * ```
+     *
+     * @throws {LynkowError} With code `'NETWORK_ERROR'` on transport
+     *   failure, `'NOT_FOUND'` if the site does not exist.
      */
     settings(): Promise<ReviewSettings>;
     /**
@@ -734,9 +808,19 @@ declare class ReviewsService extends BaseService {
      */
     submit(data: ReviewSubmitData, options?: SubmitOptions & BaseRequestOptions): Promise<ReviewSubmitResponse>;
     /**
-     * Invalidates all cached review responses (lists, individual reviews, and settings).
-     * This is called automatically after a successful `submit()`, but can also be
-     * called manually if needed.
+     * Invalidate every cached review response (lists, individual reviews,
+     * settings). Automatically invoked after a successful {@link submit};
+     * call it manually after an admin moderation action or on receipt of a
+     * `review.*` webhook to keep public listings in sync.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * // After an admin approved a pending review:
+     * lynkow.reviews.clearCache()
+     * ```
      */
     clearCache(): void;
 }
@@ -782,9 +866,20 @@ declare class SiteService extends BaseService {
      */
     getConfig(): Promise<SiteConfig>;
     /**
-     * Invalidates the cached site configuration. Call this if you know the
-     * site settings have changed (e.g. after a locale is added) and want to
-     * force a fresh fetch on the next `getConfig()` call.
+     * Invalidate the cached site configuration. Call after a settings
+     * change on the admin (branding, enabled locales, default author,
+     * search config) or on receipt of a `site.updated` webhook so the next
+     * `getConfig()` fetches fresh values.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * // After enabling a new locale in the admin:
+     * lynkow.site.clearCache()
+     * const fresh = await lynkow.site.getConfig()
+     * ```
      */
     clearCache(): void;
 }
@@ -854,9 +949,20 @@ declare class LegalService extends BaseService {
      */
     getBySlug(slug: string, options?: BaseRequestOptions): Promise<LegalDocument>;
     /**
-     * Invalidates all cached legal document responses.
+     * Invalidate every cached legal document response. Kept for
+     * backwards compatibility with sites that still reference the legacy
+     * `/legal/*` surface.
+     *
+     * @deprecated This service is deprecated. Use `lynkow.pages` instead,
+     *   which covers legal pages along with every other page type and is
+     *   actively maintained.
+     * @returns void
+     * @throws Never throws.
      *
-     * @deprecated This service is deprecated. Use `lynkow.pages` instead.
+     * @example
+     * ```typescript
+     * lynkow.legal.clearCache() // Deprecated; prefer lynkow.pages.clearCache()
+     * ```
      */
     clearCache(): void;
 }
@@ -932,9 +1038,19 @@ declare class CookiesService extends BaseService {
      */
     logConsent(preferences: CookiePreferences, options?: BaseRequestOptions): Promise<ConsentLogResponse>;
     /**
-     * Invalidates the cached cookie consent configuration. Call this if you
-     * know the consent settings have changed and want to force a fresh fetch
-     * on the next `getConfig()` call.
+     * Invalidate the cached cookie consent configuration (categories,
+     * scripts, banner appearance). Call after a settings change on the
+     * admin or on receipt of a `cookies.updated` webhook so the next
+     * `getConfig()` returns the updated categories and the consent banner
+     * reflects the new policy.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * lynkow.cookies.clearCache()
+     * ```
      */
     clearCache(): void;
 }
@@ -969,6 +1085,8 @@ declare class SeoService extends BaseService {
      *
      * @param options - Request options (custom fetch options)
      * @returns The sitemap XML content as a raw string
+     * @throws {LynkowError} With code `'NETWORK_ERROR'` on transport
+     *   failure, `'NOT_FOUND'` if the site has sitemap generation disabled.
      *
      * @example
      * ```typescript
@@ -1011,6 +1129,8 @@ declare class SeoService extends BaseService {
      *
      * @param options - Request options (custom fetch options)
      * @returns The robots.txt content as a raw string
+     * @throws {LynkowError} With code `'NETWORK_ERROR'` on transport
+     *   failure, `'NOT_FOUND'` if the site has robots.txt disabled.
      *
      * @example
      * ```typescript
@@ -1035,6 +1155,9 @@ declare class SeoService extends BaseService {
      *     When set, the API returns `/{locale}/llms.txt`. When omitted, returns
      *     the default locale version.
      * @returns The llms.txt Markdown content as a raw string
+     * @throws {LynkowError} With code `'NETWORK_ERROR'` on transport
+     *   failure, `'NOT_FOUND'` if `llmsTxtEnabled` is `false` on the site's
+     *   SEO settings or the locale has no llms.txt.
      *
      * @example
      * ```typescript
@@ -1061,6 +1184,9 @@ declare class SeoService extends BaseService {
      *   - `locale` — fetch the full content for a specific locale (e.g. `'en'`).
      *     When set, only content in that locale is included.
      * @returns The full Markdown content of all published articles and pages as a raw string
+     * @throws {LynkowError} With code `'NETWORK_ERROR'` on transport
+     *   failure, `'NOT_FOUND'` if `llmsTxtEnabled` is `false` on the site's
+     *   SEO settings.
      *
      * @example
      * ```typescript
@@ -1071,6 +1197,9 @@ declare class SeoService extends BaseService {
      *     headers: { 'Content-Type': 'text/plain; charset=utf-8' }
      *   })
      * }
+     *
+     * // Fetch the French version
+     * const md = await lynkow.seo.llmsFullTxt({ locale: 'fr' })
      * ```
      */
     llmsFullTxt(options?: BaseRequestOptions): Promise<string>;
@@ -1231,35 +1360,68 @@ declare class PathsService extends BaseService {
  * Only published content appears in search results.
  */
 interface SearchHit {
-    /** Content UUID */
+    /** Content UUID. Matches `id` on `Content` / `ContentSummary`. */
     id: string;
-    /** Article title */
+    /**
+     * Content title in the searched locale. Never empty (the indexer skips
+     * untitled drafts). May contain `<em>` markers when highlighting is
+     * enabled; see `_formatted.title` for the highlighted variant.
+     */
     title: string;
-    /** URL slug */
+    /** URL-safe slug. Unique within the site + locale combination. */
     slug: string;
-    /** Short summary / excerpt */
+    /**
+     * Short text summary shown in the search dropdown. Taken from the
+     * content's `excerpt` field, or generated from the first paragraph
+     * when `excerpt` is empty. Always non-null in search results.
+     */
     excerpt: string;
-    /** SEO meta title */
+    /**
+     * SEO meta title. Falls back to {@link title} when the content has no
+     * override. Max ~255 characters, generally kept under 60 for search
+     * result listings.
+     */
     metaTitle: string;
-    /** SEO meta description */
+    /**
+     * SEO meta description. Falls back to {@link excerpt} when the content
+     * has no override. Max ~500 characters, typically under 160 for
+     * search snippets.
+     */
     metaDescription: string;
     /** Content locale code (e.g. `'fr'`, `'en'`) */
     locale: string;
     /** Full URL path including locale and category prefix (e.g. `'/fr/guides/forms'`) */
     path: string;
-    /** Content type (e.g. `'post'`) */
+    /**
+     * Content type slug. Currently always `'post'`; the value is exposed
+     * to support future content types (product, event, etc.) without a
+     * breaking schema change.
+     */
     type: string;
-    /** Categories assigned to this content */
+    /**
+     * Categories assigned to this content as minimal `{ name, slug }`
+     * projections. Empty array when the content has no category. Use the
+     * `slug` to build category URLs and pass to
+     * {@link CategoriesService.getBySlug} for full detail.
+     */
     categories: Array<{
         name: string;
         slug: string;
     }>;
-    /** Tags assigned to this content */
+    /**
+     * Tags assigned to this content as minimal `{ name, slug }`
+     * projections. Empty array when the content has no tag. Use the
+     * `slug` for tag-filtered listings.
+     */
     tags: Array<{
         name: string;
         slug: string;
     }>;
-    /** Full name of the content author */
+    /**
+     * Full name of the content author (or the site's default author
+     * when the content has no explicit author). Always non-empty because
+     * the indexer requires a tokenizable value.
+     */
     authorName: string;
     /** Featured image URL, or `null` if none */
     featuredImage: string | null;
@@ -1285,19 +1447,42 @@ interface SearchHit {
  * Contains an array of matching articles and pagination metadata.
  */
 interface SearchResponse {
-    /** Array of matching articles, ordered by relevance */
+    /**
+     * Matching articles for the current page of results, already ordered
+     * by relevance. Empty array when the query matches nothing.
+     */
     data: SearchHit[];
-    /** Pagination and query metadata */
+    /**
+     * Pagination and query metadata for rendering controls like "N results
+     * in 42 ms" or a paginator. Uses snake-free naming (`page`,
+     * `totalPages`, `perPage`) that differs from the standard
+     * {@link PaginationMeta} because the search engine response predates
+     * the common pagination type.
+     */
     meta: {
-        /** Total number of matching results across all pages */
+        /**
+         * Total number of matching results across every page. Useful for
+         * "Showing 1-10 of 142" UI. Capped at the search engine's
+         * configured upper bound (50_000 by default).
+         */
         total: number;
         /** Current page number (1-based) */
         page: number;
-        /** Total number of pages */
+        /**
+         * Total number of pages for the current query + `perPage`. `1` when
+         * results fit on one page, `0` when `total === 0`.
+         */
         totalPages: number;
-        /** Number of results per page */
+        /**
+         * Number of results per page as actually applied by the search
+         * engine (the request's `limit` clamped to 1-100).
+         */
         perPage: number;
-        /** The search query as received */
+        /**
+         * The search query echoed back from the server, useful for
+         * debouncing UIs that drop late responses when the input has
+         * changed. Whitespace is preserved as-sent.
+         */
         query: string;
         /** Search engine processing time in milliseconds */
         processingTimeMs: number;
@@ -1329,11 +1514,19 @@ interface SearchOptions extends BaseRequestOptions {
  * round-tripping through your server.
  */
 interface SearchConfig {
-    /** Public search host URL (e.g. `'https://search.lynkow.com'`) */
+    /**
+     * Public search engine host URL (e.g. `'https://search.lynkow.com'`).
+     * Use as the `host` when instantiating a Meilisearch-compatible
+     * browser client. Does not include a trailing slash.
+     */
     host: string;
     /** Short-lived tenant token (JWT, 1-hour expiry) scoped to your site's index */
     apiKey: string;
-    /** Your site's search index name */
+    /**
+     * Meilisearch index name for this site, of the form
+     * `site-<siteId>_<locale>` or `site-<siteId>` for single-locale sites.
+     * Pass verbatim as the `index` parameter in browser search queries.
+     */
     indexName: string;
 }
 /**
@@ -1889,9 +2082,13 @@ interface ContentSchema {
  * array; no client-side cascade logic is needed.
  *
  * Reserved ids beginning with `auto:` identify the implicit nodes Lynkow
- * injects automatically (Article, FAQPage, BreadcrumbList, Organization,
- * WebPage). They may appear in `jsonLdExclusions` to opt out of the
- * corresponding auto-node, but MUST NOT be used as user-provided ids.
+ * injects automatically (Article, FAQPage, BreadcrumbList, WebPage). They
+ * may appear in `jsonLdExclusions` to opt out of the corresponding
+ * auto-node, but MUST NOT be used as user-provided ids.
+ *
+ * Organization is no longer auto-injected. Declare it explicitly at the
+ * site level via `seo_settings.jsonLdGraph` (from the admin UI or the
+ * `update_seo_settings` MCP tool).
  */
 /**
  * Source of a JSON-LD node.
@@ -1914,25 +2111,57 @@ type JsonLdNodeSource = 'preset' | 'custom';
  */
 interface JsonLdNode {
     /**
-     * Stable node identifier. Auto-generated when the caller does not provide
-     * one. Never starts with the reserved `auto:` prefix.
+     * Stable `@id` for this node. Server-generated (pattern `own-<8hex>`) when
+     * the caller omits it on create. Safe to treat as an opaque string; the
+     * public API rewrites it to an absolute URL (`<pageUrl>#<id>`) in the
+     * resolved graph. Never starts with the reserved `auto:` prefix, which is
+     * reserved for nodes Lynkow injects automatically.
      */
     id: string;
-    /** schema.org `@type` string (e.g. "Organization", "LocalBusiness"). */
+    /**
+     * schema.org `@type` identifier (e.g. `"Organization"`, `"LocalBusiness"`,
+     * `"Product"`). Any schema.org type is accepted; 27 first-class presets
+     * get typed field mapping server-side, unknown types pass through via
+     * `source: 'custom'`.
+     */
     type: string;
-    /** Node payload. For presets, only the preset-documented fields. */
+    /**
+     * Node payload. The accepted shape depends on {@link source}:
+     *
+     * - `preset`: only the fields documented for the matching preset
+     *   (e.g. `name`, `address`, `geo` for `LocalBusiness`). Unknown keys are
+     *   ignored. Missing context fields (url, inLanguage, etc.) are filled
+     *   from the page context at render time.
+     * - `custom`: the full schema.org object, minus `@context` and `@id`
+     *   which the server injects. Passed through verbatim after basic sanity
+     *   checks (non-empty `@type`, no prototype-pollution keys).
+     */
     data: Record<string, unknown>;
-    /** Whether the node was created from a preset or a raw custom JSON-LD. */
+    /** Whether the node was created from a Lynkow typed preset or from raw JSON-LD. */
     source: JsonLdNodeSource;
 }
 /**
  * Cascade configuration stored at any level (site, category, page, content).
  *
- * `graph` carries the nodes declared at this level; `exclusions` lists the
- * parent node ids this level opts out of.
+ * This is the wire shape persisted in the Lynkow database. The public API
+ * exposes the already-resolved graph on `structuredData.graph`; SDK consumers
+ * normally read that resolved array rather than reconstructing one from the
+ * raw configs at each level.
  */
 interface JsonLdGraphConfig {
+    /**
+     * Nodes declared at this cascade level. Order is preserved in the emitted
+     * `@graph` but is not semantically significant for schema.org consumers.
+     * Empty array when no nodes are declared.
+     */
     graph: JsonLdNode[];
+    /**
+     * Parent-level `@id` values this level opts out of. Accepts both
+     * user-provided ids (e.g. `"site-org"`) and the reserved
+     * `auto:article` / `auto:faqpage` / `auto:breadcrumb` / `auto:webpage`
+     * identifiers to suppress Lynkow's implicit nodes. Empty array when no
+     * parent node is excluded.
+     */
     exclusions: string[];
 }
 
@@ -2852,19 +3081,24 @@ interface Page extends PageSummary {
      */
     _warnings?: string[];
     /**
-     * Resolved JSON-LD cascade for the page.
-     *
-     * `graph` contains the `@graph` array merged by the server from the site
-     * level plus this page's own nodes plus the auto-nodes (WebPage,
-     * BreadcrumbList, Organization when configured). Use
-     * {@link renderJsonLdGraph} from the helpers to serialize it as a single
-     * `<script type="application/ld+json">` tag.
+     * Resolved JSON-LD cascade for the page. Server-merged and ready to
+     * render; no client-side cascade logic required.
      *
      * `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.
+     * `/public/:siteId/pages/:slug/json-ld` endpoint which always returns
+     * the array directly under `data`.
      */
     structuredData?: {
+        /**
+         * The resolved `@graph` array: site-level nodes + this page's own
+         * nodes + auto-nodes (WebPage, BreadcrumbList, Organization when
+         * configured), minus any excluded ids. Each entry is a fully-formed
+         * schema.org object with `@context`, `@id`, and `@type`. Use
+         * {@link renderJsonLdGraph} to serialize the whole array as a single
+         * `<script type="application/ld+json">` tag. Empty array when nothing
+         * is declared and all auto-nodes are excluded.
+         */
         graph: object[];
     };
 }
@@ -4166,7 +4400,18 @@ interface CategoryDetailResponse {
      * Supports the same pagination options as `contents.list()`.
      */
     contents: {
+        /**
+         * Current page of matching content summaries, already filtered to
+         * this category + locale. Empty array when the category has no
+         * published content on this page.
+         */
         data: ContentSummary[];
+        /**
+         * Pagination cursors for the paginated list: `total`, `perPage`,
+         * `currentPage`, `lastPage`, `hasMorePages`. Use these to drive
+         * "Load more" or page-number UIs; shape matches the generic
+         * {@link PaginationMeta}.
+         */
         meta: PaginationMeta;
     };
     /**
@@ -4407,7 +4652,16 @@ interface CategoryResolveResponse {
      * Pagination can be controlled via query parameters on the resolve request.
      */
     contents: {
+        /**
+         * Current page of matching content summaries for the resolved
+         * category. Order follows the site's configured content sort
+         * (typically publication date desc).
+         */
         data: ContentSummary[];
+        /**
+         * Pagination cursors. Shape matches {@link PaginationMeta}; use
+         * `hasMorePages` to decide whether to show a "Load more" button.
+         */
         meta: PaginationMeta;
     };
 }
@@ -4623,23 +4877,48 @@ declare function isCategoryResolve(response: ResolveResponse): response is Categ
  */
 
 /**
- * Data for tracking pageviews
+ * Payload accepted by {@link AnalyticsService.trackPageview}. Every field
+ * is optional; unset values fall back to the browser context at call time.
  */
 interface PageviewData {
-    /** Page path (default: window.location.pathname) */
+    /**
+     * URL path to record. Should start with `/`. Query string and hash are
+     * preserved as-is; strip them when they do not identify a distinct
+     * pageview (e.g. tracker-specific UTM parameters). Defaults to
+     * `window.location.pathname` when omitted.
+     */
     path?: string;
-    /** Page title (default: document.title) */
+    /**
+     * Human-readable page title as it appears in the browser tab, used for
+     * the analytics dashboard listing. Defaults to `document.title` when
+     * omitted. Max ~255 characters before server-side truncation.
+     */
     title?: string;
-    /** Referrer URL */
+    /**
+     * Referring URL for this pageview, typically `document.referrer`.
+     * Pass `''` to record "direct" traffic when you want to override the
+     * browser's value. Omit to let the tracker fill it from
+     * `document.referrer`.
+     */
     referrer?: string;
 }
 /**
- * Data for tracking custom events
+ * Payload accepted by {@link AnalyticsService.trackEvent}. `type` is the
+ * only required field; every other key becomes an ad-hoc property on the
+ * event recorded by the tracker.
  */
 interface EventData {
-    /** Event type */
+    /**
+     * Short slug identifying the event (e.g. `'cta_click'`,
+     * `'signup_complete'`). Prefer snake_case so events group cleanly in
+     * the analytics dashboard. Required and must be non-empty.
+     */
     type: string;
-    /** Additional event data */
+    /**
+     * Arbitrary extra properties to attach to the event. Values must be
+     * JSON-serializable. Keys prefixed with `_` are reserved for the
+     * tracker and may be overwritten server-side.
+     */
     [key: string]: unknown;
 }
 /**
@@ -4778,6 +5057,9 @@ declare class AnalyticsService {
      *   }
      * })
      * ```
+     *
+     * @returns void
+     * @throws Never throws.
      */
     enable(): void;
     /**
@@ -4785,6 +5067,9 @@ declare class AnalyticsService {
      * `trackPageview()` calls become no-ops. The tracker script remains loaded;
      * call `destroy()` to fully remove it.
      *
+     * @returns void
+     * @throws Never throws.
+     *
      * @example
      * ```typescript
      * // Disable tracking when the user revokes analytics consent
@@ -4793,25 +5078,56 @@ declare class AnalyticsService {
      */
     disable(): void;
     /**
-     * Returns whether analytics tracking is currently enabled.
+     * Returns whether analytics tracking is currently enabled (i.e. whether
+     * `trackEvent` and `trackPageview` will actually emit). Does not
+     * indicate whether the underlying tracker script has loaded; use
+     * {@link isInitialized} for that.
      *
-     * @returns `true` if tracking is enabled (default), `false` if `disable()` was called
+     * @returns `true` if tracking is enabled (default), `false` after
+     *   {@link disable} has been called.
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * if (lynkow.analytics.isEnabled()) {
+     *   // Safe to track
+     * }
+     * ```
      */
     isEnabled(): boolean;
     /**
      * Returns whether the tracker.js script has been loaded and the
-     * `window.LynkowAnalytics` global is available.
+     * `window.LynkowAnalytics` global is available. Always `false` on the
+     * server.
+     *
+     * @returns `true` if the tracker is fully loaded and ready to accept
+     *   events, `false` otherwise.
+     * @throws Never throws.
      *
-     * @returns `true` if the tracker is fully initialized and ready to track events
+     * @example
+     * ```typescript
+     * if (lynkow.analytics.isInitialized()) {
+     *   lynkow.analytics.trackEvent({ type: 'cta_click' })
+     * }
+     * ```
      */
     isInitialized(): boolean;
     /**
-     * Returns the underlying `window.LynkowAnalytics` global object for advanced
-     * usage when you need direct access to the tracker API beyond what this
-     * service wraps.
+     * Return the underlying `window.LynkowAnalytics` global for advanced
+     * use cases that need direct access to the tracker's lower-level API
+     * (e.g. calling `init` again with different options, or invoking
+     * undocumented tracker internals).
+     *
+     * @returns The `LynkowAnalyticsGlobal` with `init()` and `track()`
+     *   methods, or `undefined` if running on the server or the tracker
+     *   script has not loaded yet.
+     * @throws Never throws.
      *
-     * @returns The `LynkowAnalyticsGlobal` object with `init()` and `track()` methods,
-     *   or `undefined` if running on the server or the tracker is not loaded
+     * @example
+     * ```typescript
+     * const tracker = lynkow.analytics.getTracker()
+     * tracker?.track({ custom: 'payload' })
+     * ```
      */
     getTracker(): LynkowAnalyticsGlobal | undefined;
     /**
@@ -4873,9 +5189,25 @@ type EventName = keyof LynkowEvents;
  */
 type EventListener<T> = (data: T) => void;
 /**
- * Create a new event emitter instance.
- * Returns an object with `on`, `off`, `emit`, `once`, and `removeAllListeners` methods.
- * Each SDK client creates its own emitter; events do not leak between client instances.
+ * Create a new event emitter instance backing the `lynkow.on/off/once`
+ * API of the client. Each SDK client creates its own emitter, so events
+ * do not leak between client instances (e.g. multi-tenant server rendering).
+ *
+ * @returns An {@link EventEmitter} object exposing `on`, `off`, `emit`,
+ *   `once`, and `removeAllListeners`. `on()` and `once()` return an
+ *   unsubscribe closure for convenience.
+ *
+ * @example
+ * ```typescript
+ * import { createEventEmitter } from 'lynkow'
+ *
+ * const events = createEventEmitter()
+ * const unsubscribe = events.on('locale-changed', (locale) => {
+ *   refetchContent(locale)
+ * })
+ * events.emit('locale-changed', 'fr')
+ * unsubscribe()
+ * ```
  */
 declare function createEventEmitter(): {
     on: <K extends EventName>(event: K, listener: EventListener<LynkowEvents[K]>) => () => void;
@@ -4896,16 +5228,38 @@ type EventEmitter = ReturnType<typeof createEventEmitter>;
  */
 
 /**
- * Consent categories
+ * User consent state for each cookie category Lynkow manages. Used as
+ * input to {@link ConsentService.setCategories} and emitted as the payload
+ * of the `'consent-changed'` client event.
+ *
+ * A category set to `false` means the corresponding scripts (from the
+ * site's cookie configuration) MUST NOT be loaded; a category set to
+ * `true` authorises them.
  */
 interface ConsentCategories {
-    /** Always true, not modifiable */
+    /**
+     * Strictly necessary cookies (session, CSRF). Always `true`: users
+     * cannot opt out because the site would be non-functional without them.
+     * Included in the type so consent payloads remain uniform.
+     */
     necessary: boolean;
-    /** Analytics cookies */
+    /**
+     * Consent to first-party and third-party analytics (e.g. the Lynkow
+     * tracker, Google Analytics). When `false`, the analytics service
+     * automatically becomes a no-op.
+     */
     analytics: boolean;
-    /** Marketing cookies */
+    /**
+     * Consent to marketing and advertising cookies (ad networks,
+     * retargeting). Required before loading scripts classified as
+     * `marketing` in the site's cookie config.
+     */
     marketing: boolean;
-    /** Preference cookies */
+    /**
+     * Consent to personalization and preference cookies (theme, language,
+     * non-essential UI state). Required before loading scripts classified
+     * as `preferences` in the site's cookie config.
+     */
     preferences: boolean;
 }
 /**
@@ -4954,8 +5308,19 @@ declare class ConsentService {
      * Works on both server and browser.
      *
      * @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)
+     *   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.
+     *
+     * @example
+     * ```typescript
+     * const config = await lynkow.consent.getConfig()
+     * if (config.enabled) {
+     *   console.log('Categories:', config.categories.map((c) => c.id))
+     * }
+     * ```
      */
     getConfig(): Promise<CookieConfig>;
     /**
@@ -4968,7 +5333,19 @@ declare class ConsentService {
      *   (e.g. `{ necessary: true, analytics: true, marketing: false }`)
      * @param action - Optional explicit action type. If omitted, the action is inferred
      *   from the preferences (all true = `'accept_all'`, all false = `'reject_all'`,
-     *   mixed = `'customize'`)
+     *   mixed = `'customize'`). `'withdraw'` must be passed explicitly.
+     * @returns A promise that resolves once the POST has completed or
+     *   been suppressed on error. Never rejects.
+     * @throws Never throws. Network or server errors are caught and silently
+     *   discarded so the consent UI flow is never interrupted.
+     *
+     * @example
+     * ```typescript
+     * await lynkow.consent.logConsent(
+     *   { necessary: true, analytics: true, marketing: false },
+     *   'customize'
+     * )
+     * ```
      */
     logConsent(preferences: CookiePreferences, action?: 'accept_all' | 'reject_all' | 'customize' | 'withdraw'): Promise<void>;
     private getOrCreateVisitorId;
@@ -4984,6 +5361,9 @@ declare class ConsentService {
      * When theme is `'auto'`, a MutationObserver watches for site theme changes
      * and updates the banner colors in real-time.
      *
+     * @returns void
+     * @throws Never throws. Config-fetch rejections are caught internally.
+     *
      * @example
      * ```typescript
      * // Show the consent banner on page load (skips if already consented)
@@ -4993,15 +5373,37 @@ declare class ConsentService {
      */
     show(): void;
     /**
-     * Hides and removes the consent banner from the DOM. Does not affect stored
-     * consent preferences. No-op on server or if the banner is not shown.
+     * Hide and remove the consent banner from the DOM. Does not affect
+     * stored consent preferences (the user will not be re-prompted on the
+     * next page load if they already chose). No-op on server or if the
+     * banner is not currently shown.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * // Close the banner after the user clicked "Accept all" via custom UI:
+     * lynkow.consent.hide()
+     * ```
      */
     hide(): void;
     /**
-     * Opens the preferences modal, allowing the user to toggle individual
-     * consent categories (analytics, marketing, preferences). The necessary
-     * category is always checked and disabled. Pre-populates checkboxes with
-     * the user's current consent state. No-op on server.
+     * Open the preferences modal so the user can toggle individual consent
+     * categories (analytics, marketing, preferences). The `necessary`
+     * category is always checked and disabled. Pre-populates checkboxes
+     * with the user's current consent state. No-op on server or if the
+     * modal is already mounted.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```tsx
+     * <button onClick={() => lynkow.consent.showPreferences()}>
+     *   Cookie settings
+     * </button>
+     * ```
      */
     showPreferences(): void;
     /**
@@ -5094,6 +5496,9 @@ declare class ConsentService {
      * banner. Useful for providing a "manage cookies" link that lets users
      * change their preferences. No-op on server.
      *
+     * @returns void
+     * @throws Never throws. localStorage errors are silently ignored.
+     *
      * @example
      * ```typescript
      * // Add a "Manage cookies" link in the footer to let users re-choose
@@ -5122,10 +5527,22 @@ declare class ConsentService {
     private attachBannerEvents;
     private attachPreferencesEvents;
     /**
-     * Cleans up all consent UI resources: removes the banner and preferences
-     * modal from the DOM, removes injected third-party scripts, and stops
-     * the theme observer. Call this when unmounting the SDK (e.g. in a
-     * React useEffect cleanup). No-op on server.
+     * Clean up every DOM resource this service owns: removes the banner
+     * and preferences modal, removes injected third-party scripts, and
+     * stops the theme observer. Call when unmounting the SDK (e.g. inside
+     * a React `useEffect` cleanup) so the page can be navigated without
+     * leaking listeners. No-op on server.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```tsx
+     * useEffect(() => {
+     *   lynkow.consent.show()
+     *   return () => lynkow.consent.destroy()
+     * }, [])
+     * ```
      */
     destroy(): void;
 }
@@ -5186,21 +5603,50 @@ declare class BrandingService extends BaseService {
      */
     inject(): Promise<void>;
     /**
-     * Removes the branding badge and its associated styles from the DOM,
-     * and stops the theme observer. No-op on server or if the badge is
-     * not currently injected.
+     * Remove the branding badge and its associated `<style>` block from
+     * the DOM and stop the theme observer. No-op on server or if the
+     * badge is not currently injected.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```typescript
+     * lynkow.branding.remove()
+     * ```
      */
     remove(): void;
     /**
-     * Checks whether the branding badge is currently present in the DOM.
+     * Check whether the branding badge is currently mounted in the DOM.
+     * Useful for conditional logic (e.g. show a custom "Powered by" only
+     * when the badge is not already rendered).
+     *
+     * @returns `true` if the badge container element exists in the
+     *   document, `false` otherwise. Always returns `false` on the server.
+     * @throws Never throws.
      *
-     * @returns `true` if the badge container element exists in the document,
-     *   `false` otherwise. Always returns `false` on the server.
+     * @example
+     * ```typescript
+     * if (!lynkow.branding.isVisible()) {
+     *   // Render our own attribution
+     * }
+     * ```
      */
     isVisible(): boolean;
     /**
-     * Alias for `remove()`. Cleans up the badge, styles, and theme observer.
-     * Use this in cleanup callbacks (e.g. React useEffect cleanup).
+     * Alias for {@link remove}. Cleans up the badge, styles, and theme
+     * observer. Matches the `destroy()` naming used on other lifecycle
+     * services so cleanup code can stay uniform.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```tsx
+     * useEffect(() => {
+     *   return () => lynkow.branding.destroy()
+     * }, [])
+     * ```
      */
     destroy(): void;
 }
@@ -5284,17 +5730,40 @@ declare class EnhancementsService {
      */
     init(): void;
     /**
-     * Checks whether the enhancements service has been initialized.
+     * Check whether the enhancements service has been initialized for the
+     * current page. Returns `false` on the server and after a call to
+     * {@link destroy} (until `init()` is invoked again).
+     *
+     * @returns `true` if `init()` has been called successfully, `false`
+     *   otherwise.
+     * @throws Never throws.
      *
-     * @returns `true` if `init()` has been called successfully, `false` otherwise
+     * @example
+     * ```typescript
+     * if (!lynkow.enhancements.isInitialized()) {
+     *   lynkow.enhancements.init()
+     * }
+     * ```
      */
     isInitialized(): boolean;
     /**
-     * Cleans up all enhancement resources: disconnects the MutationObserver,
-     * removes the widget resize listener, cancels any pending animation frame,
-     * removes injected styles and cloned scripts from `<head>`, and resets
-     * the initialized state. After calling `destroy()`, you can re-initialize
-     * by calling `init()` again. No-op on server.
+     * Clean up every resource the enhancements service owns: disconnect the
+     * MutationObserver, remove the widget resize listener, cancel any
+     * pending animation frame, remove injected styles and cloned scripts
+     * from `<head>`, and reset the initialized state. Safe to call
+     * repeatedly; subsequent calls are no-ops. After `destroy()` you can
+     * re-attach by calling `init()` again. No-op on server.
+     *
+     * @returns void
+     * @throws Never throws.
+     *
+     * @example
+     * ```tsx
+     * useEffect(() => {
+     *   lynkow.enhancements.init()
+     *   return () => lynkow.enhancements.destroy()
+     * }, [])
+     * ```
      */
     destroy(): void;
 }
@@ -5303,32 +5772,74 @@ declare class EnhancementsService {
  * Options for building srcset URLs
  */
 interface SrcsetOptions {
-    /** Image widths to include in srcset (default: [400, 800, 1200, 1920]) */
+    /**
+     * Pixel widths to generate in the srcset, in ascending order. Each
+     * width becomes a `Nw` entry in the returned string. Defaults to
+     * `[400, 800, 1200, 1920]` to cover phone, tablet, desktop, large
+     * desktop. Supply a custom list when you know your layout's
+     * breakpoints to avoid bandwidth waste.
+     */
     widths?: number[];
-    /** Resize fit mode (default: 'scale-down') */
+    /**
+     * Cloudflare resize fit mode. `'scale-down'` (default) preserves
+     * aspect ratio and never upscales; `'cover'` fills the box and crops;
+     * `'contain'` fits inside the box with letterboxing; `'crop'` hard
+     * crops to the exact dimensions. Must pair with `gravity` for
+     * `'cover'` / `'crop'` when the subject is not centered.
+     */
     fit?: 'cover' | 'contain' | 'scale-down' | 'crop';
-    /** Image quality 1-100 (default: 80) */
+    /**
+     * JPEG / WebP quality on a 1-100 scale. Higher values produce larger
+     * files. Default `80` strikes a good balance for photography; drop to
+     * 60-70 for hero images on slow connections.
+     */
     quality?: number;
-    /** Focal point for crop (e.g., '0.5x0.3') */
+    /**
+     * Focal point for `fit: 'cover' | 'crop'` as an `XxY` pair of
+     * fractions (e.g. `'0.5x0.3'` keeps the horizontal center but biases
+     * towards the upper third). Omit to center the crop.
+     */
     gravity?: string;
 }
 /**
- * Options for building a single transformed URL
+ * Options for building a single transformed URL. Matches the Cloudflare
+ * Image Transformations query parameters; omit any value to let the CDN
+ * choose a sensible default.
  */
 interface TransformOptions {
-    /** Target width in pixels */
+    /**
+     * Target width in pixels. When set alone, height is derived from the
+     * image's aspect ratio (unless `fit` requires both).
+     */
     w?: number;
-    /** Target height in pixels */
+    /**
+     * Target height in pixels. When set alone, width is derived from the
+     * image's aspect ratio (unless `fit` requires both).
+     */
     h?: number;
-    /** Resize fit mode */
+    /**
+     * Resize fit mode. See {@link SrcsetOptions.fit} for semantics; the
+     * default here is `'scale-down'` to avoid accidental upscaling.
+     */
     fit?: 'cover' | 'contain' | 'scale-down' | 'crop';
     /** Image quality 1-100 (default: 80) */
     quality?: number;
-    /** Output format (default: 'auto') */
+    /**
+     * Output image format. `'auto'` (default) lets the CDN negotiate
+     * based on `Accept` (WebP on modern browsers, AVIF on the newest).
+     * Force a specific format only when the consumer is known.
+     */
     format?: 'auto' | 'webp' | 'avif' | 'jpeg';
-    /** Focal point for crop */
+    /**
+     * Focal point for `fit: 'cover' | 'crop'` as an `XxY` pair of
+     * fractions (see {@link SrcsetOptions.gravity}). Omit to center.
+     */
     gravity?: string;
-    /** Device Pixel Ratio 1-4 */
+    /**
+     * Device Pixel Ratio multiplier on a `1`-`4` scale. Multiplies the
+     * rendered width/height so a 400px box renders sharp at 2x on
+     * Retina. Prefer using a `srcset` over a hard-coded DPR.
+     */
     dpr?: number;
 }
 /**
@@ -5852,6 +6363,11 @@ declare function onSiteThemeChange(callback: (theme: 'dark' | 'light') => void):
  *                conditional branches.
  * @returns Serialized `<script>` tag string. Empty string when there are
  *          no nodes to render.
+ * @throws Never throws. The function is designed for server components
+ *         and is safe to call with `undefined` or malformed payloads
+ *         (values that cannot be `JSON.stringify`-ed, e.g. circular
+ *         references, will throw from the underlying `JSON.stringify`
+ *         call - caller's responsibility, not a library behaviour).
  *
  * @example
  * ```tsx