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 <token> 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 <head> (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 <html>, <body> 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 <html>. 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).