> For the complete Lynkow documentation index in agent-friendly format, see [llms.txt](/llms.txt). # SDK Reference **Publié le** : 2026-08-20 **Catégorie** : SDK Reference # Lynkow SDK Reference Version: `1.51.2` ## Installation ```bash npm install @lynkow/sdk ``` ## Quick Start ```typescript import { createClient } from '@lynkow/sdk' const lynkow = createClient({ siteId: 'your-site-id', apiUrl: 'https://api.lynkow.com' }) const posts = await lynkow.contents.list() ``` ## Available Services - **AnalyticsService** — Service for client-side analytics tracking via the Lynkow tracker.js script. Accessible via `lynkow.analytics`. This is a **browser-only** service -- all methods are no-ops when called on the server (SSR/Node.js). The service lazily loads the `tracker.js` script from the API, which auto-initializes using the site ID. The tracker automatically captures pageviews; use `trackPageview()` for manual SPA navigation tracking and `trackEvent()` for custom events. The service respects the site's consent mode: if consent mode is `'opt-in'`, tracking only starts after consent is granted. The consent state is read from `localStorage` (`_lkw_consent_mode` key). - **BlocksService** — Service for retrieving global site blocks (header, footer, navigation, etc.). Accessible via `lynkow.globals` (aliased from `lynkow.blocks`). Global blocks are reusable, schema-driven content components shared across all pages of the site. They are resolved server-side with DataSources. Responses are cached for 10 minutes (MEDIUM TTL) since global blocks change infrequently. - **BrandingService** — Service for displaying the "Powered by Lynkow" branding badge. Accessible via `lynkow.branding`. This is a **browser-only** service -- all methods are no-ops on the server. The badge HTML and CSS are fetched from the API (cached for 30 minutes, LONG TTL) so they can be updated server-side without SDK changes. The badge automatically adapts to the site's light/dark theme via a MutationObserver. The badge is shown for sites on the free plan (`siteConfig.showBranding === true`). It fails silently if the fetch fails (the badge is not critical). - **CategoriesService** — Service for retrieving content categories and their hierarchical structure. Accessible via `lynkow.categories`. Categories organize blog articles and can be nested (parent/child). Each category includes a content count and optional image. Responses are cached for 5 minutes (SHORT TTL) when a cache adapter is configured. - **ConsentService** — High-level consent management service with built-in banner UI and preferences modal. Accessible via `lynkow.consent`. This is a hybrid service: - **API methods** (`getConfig`, `logConsent`) work everywhere (server + browser) - **UI methods** (`show`, `hide`, `acceptAll`, `rejectAll`, `showPreferences`, etc.) only work in the browser and are no-ops on the server Consent choices are persisted in `localStorage` under the `_lkw_consent` key (compatible with tracker.js) and expire after 365 days. When consent is granted for a category, any third-party scripts configured for that category are automatically injected into the page. Emits a `'consent-changed'` event (via the SDK event emitter) and a `'lynkow:consent:update'` CustomEvent on `document` whenever consent changes. - **ContentsService** — Service for retrieving published blog articles (contents). Accessible via `lynkow.contents`. All methods return only published content visible to the public API. Responses are cached in-memory for 5 minutes (SHORT TTL) when a cache adapter is configured on the client. - **CookiesService** — Low-level service for cookie consent API interactions. Accessible via `lynkow.cookies`. Provides raw API methods for fetching consent configuration and logging user preferences. For a higher-level experience with built-in banner UI and preferences modal, use the `consent` service (`lynkow.consent`) instead. Responses are cached for 10 minutes (MEDIUM TTL). - **CustomersService** — Service for the storefront buyer-authentication surface: register, log in, read the current buyer and their bookings, manage their address book, reset a forgotten password, and manage marketing consent. Accessible via `lynkow.customers`. Requires a publishable key: pass `publishableKey` to `createClient(...)` so every request carries it (customer routes reject calls without a valid key). The customer session token is a SEPARATE identity track: `activation.confirm` and `login` return it and write it to shared in-memory client state. Authenticated customer methods attach it as `Authorization: Bearer ` ALONGSIDE the publishable key, and signed-in reservation creation reads the same state so a new booking appears in `me()` right away. `logout` clears the shared value. Persist the token in your own storage (for example a cookie) and seed it back via `createClient({ customerToken })` to keep the buyer signed in across a reload or SSR. The SDK never persists or logs it. Signing up is TWO steps and no session exists between them: `register` only asks for an activation link to be sent, and `activation.confirm` (called from the page that link lands on) sets the password and returns the session. - **EnhancementsService** — Service for adding interactive features to content rendered from the Lynkow API. Accessible via `lynkow.enhancements`. This is a **browser-only** service: all methods are no-ops on the server. Currently provides: - **Copy button** for code blocks (elements with `[data-copy-code]` attribute) - **Script activation** for inline scripts injected via `dangerouslySetInnerHTML` - **Widget iframe auto-resize** for embedded Lynkow widgets - **CSS normalization** to ensure content renders correctly with CSS frameworks (Tailwind, etc.) A `MutationObserver` automatically detects new content added to the DOM and applies enhancements, making it compatible with SPA frameworks like React/Next.js. Script clones are appended to `` (not inline) to avoid React DOM reconciliation issues. ## Code-block theming Code-block CSS is driven by CSS custom properties (`--lynkow-code-bg`, `--lynkow-code-fg`, `--lynkow-code-border`, `--lynkow-code-muted-fg`, `--lynkow-code-copy-fg-hover`, `--lynkow-code-copy-bg-hover`). The light variant is triggered by any of the common theming conventions on ``, `` or the `.code-block` element itself: `.light` class, `data-theme~="light"`, `data-mode~="light"`, `data-color-scheme~="light"`. `prefers-color-scheme: light` is kept as an OS-level fallback that only applies when no explicit dark signal is present on ``. Override any variable in your own stylesheet to customise without `!important`. Pass `init({ codeBlocks: false })` if you handle code-block rendering yourself; the SDK will skip code-block CSS injection and copy-button binding. - **FormsService** — Service for retrieving form schemas and submitting form data. Accessible via `lynkow.forms`. Forms are dynamic, CMS-managed forms with configurable fields, validation rules, and spam protection. The service automatically handles honeypot anti-spam fields on submissions. Form schemas are cached for 10 minutes (MEDIUM TTL). - **LegalService** — Service for accessing legal documents (privacy policy, terms of service, etc.). Accessible via `lynkow.legal`. Legal documents are regular pages tagged with `'legal'`. This service provides convenience methods to access them, but is deprecated in favor of the `pages` service. Responses are cached for 5 minutes (SHORT TTL). - **MediaHelperService** — Service for building optimized image URLs backed by the Lynkow image transformation service. Accessible via `lynkow.media`. This is a pure utility service (no API calls, no caching) that constructs CDN transformation URLs from Lynkow media URLs. Works on both server and browser. Handles both original URLs (`/sites/...`) and already-transformed URLs, re-extracting the original path when needed. - **PagesService** — Service for retrieving published pages (Site Blocks of type "page"). Accessible via `lynkow.pages`. Pages are CMS-managed, schema-driven content blocks (e.g. "About", "Contact", legal pages). Unlike blog articles, pages use DataSource-resolved data instead of a rich text body. Responses are cached for 5 minutes (SHORT TTL) when a cache adapter is configured. - **PathsService** — Service for URL path resolution and static site generation (SSG). Accessible via `lynkow.paths`. Provides methods to list all available paths for static generation, resolve a URL path to its content or category, and check for configured redirects. Cached for 5 minutes (SHORT TTL). - **ProductCategoriesService** — Service for reading a site's storefront product category tree. Accessible via `lynkow.productCategories`. Only categories the merchant made visible appear, with nesting represented by each node's `children`. Requires a publishable key: pass `publishableKey` to `createClient(...)` so every request carries it (commerce routes reject calls without a valid key). Responses are cached in-memory for 5 minutes (SHORT TTL) when a cache adapter is configured on the client. - **ProductCollectionsService** — Service for reading a site's storefront product collections. Accessible via `lynkow.productCollections`. Returns only collections the merchant made visible. Requires a publishable key: pass `publishableKey` to `createClient(...)` so every request carries it (commerce routes reject calls without a valid key). Responses are cached in-memory for 5 minutes (SHORT TTL) when a cache adapter is configured on the client. - **ProductsService** — Service for reading a site's published product catalogue. Accessible via `lynkow.products`. Returns only PUBLISHED products. Requires a publishable key: pass `publishableKey` to `createClient(...)` so every request carries it (commerce routes reject calls without a valid key). Responses are cached in-memory for 5 minutes (SHORT TTL) when a cache adapter is configured on the client. - **ReservationsService** — Service for reading a bookable product's availability and creating guest or signed-in buyer reservations. Accessible via `lynkow.reservations`. Requires a publishable key: pass `publishableKey` to `createClient(...)` so every request carries it. Reservation routes reject calls without a valid key. A product without an online deposit is `confirmed` immediately. Use book for a deposit-aware result: a required deposit returns a `pending` reservation plus an opaque hosted-checkout URL, and refreshPayment confirms the status after the buyer returns. Anti-spam honeypot fields are injected automatically on `book` and `bookings.create`; on reCAPTCHA-protected storefronts pass `options.recaptchaToken`. When the same client has a customer session from `customers.activation.confirm()` / `customers.login()` or a `customerToken` seed, booking creation automatically attaches it as `Authorization: Bearer`; the booking then appears in `customers.me()` immediately. Guest requests remain unchanged when no customer token is present. Availability and reservation offerings are not cached: availability changes on every booking, while a merchant can change or archive an offering at any time. - **ReviewsService** — Service for retrieving and submitting customer reviews. Accessible via `lynkow.reviews`. Only reviews with status `'approved'` are returned by the public API. New submissions go through moderation if `requireApproval` is enabled in the review settings. Anti-spam honeypot fields are injected automatically on submissions. Responses are cached for 5 minutes (SHORT TTL). - **SearchService** — Lynkow Instant Search service. Accessible via `lynkow.search`. Provides full-text search with typo tolerance across all published content. Results are not cached (search queries are dynamic by nature). Search must be enabled in the admin dashboard (**Settings > SEO > Search**) before it can be used. When disabled, all methods return a 503 error. - **SeoService** — Service for retrieving SEO-related files (sitemap, robots.txt, LLM-optimized content, and individual Markdown exports). Accessible via `lynkow.seo`. All methods return plain text (XML, TXT, or Markdown) and are NOT cached by the SDK since they are typically served as route handlers with their own HTTP caching headers. - **SiteService** — Service for retrieving the public site configuration. Accessible via `lynkow.site`. Provides site-level metadata such as name, domain, locales, timezone, branding settings, and analytics consent mode. Cached for 10 minutes (MEDIUM TTL) since site configuration rarely changes. - **TagsService** — Service for retrieving content tags. Accessible via `lynkow.tags`. Tags are lightweight labels attached to blog articles for cross-cutting classification (unlike categories which are hierarchical). Responses are cached for 5 minutes (SHORT TTL).