lynkow 3.8.77 → 3.8.79

package/README.md

@@ -11,7 +11,7 @@ Official TypeScript SDK for [Lynkow](https://lynkow.com) Headless CMS.
 - **Framework-agnostic** - Works with Next.js, Nuxt, Astro, SvelteKit, etc.
 - **Tree-shakeable** - Only import what you need
 - **Isomorphic** - Works on both browser and server (Node.js, Deno, Bun)
-- **Image Transformations** - Cloudflare CDN srcset and responsive image helpers
+- **Image Transformations** - Lynkow CDN srcset and responsive image helpers
 - **Built-in Analytics** - Page views, events, and funnel tracking
 - **Cookie Consent** - GDPR-compliant consent banner with preferences
 - **Spam protection** - Built-in honeypot fields for form submissions
@@ -262,6 +262,36 @@ const result = await lynkow.reviews.submit({
 })
 ```
 
+### Search
+
+Lynkow Instant Search exposes a full-text search backed by typo tolerance.
+Site administrators define a single index configuration (which fields are
+indexed, synonyms, stop words, ranking) and one or more named **search
+profiles** that scope the search to a slice of the content (a category, a
+set of tags, a path prefix, etc.) with their own searchable/displayed
+fields, sort, facets and limits.
+
+```typescript
+// Search the site default profile
+const { data, meta } = await lynkow.search.search('pagination', {
+  locale: 'en',
+  limit: 10,
+})
+
+// Search a specific profile by slug (e.g. one per docs space)
+const { data: apiHits } = await lynkow.search.searchByProfile('api-docs', 'contents')
+
+// Discover the public profiles configured for the site
+const profiles = await lynkow.search.listProfiles()
+profiles.forEach((p) => console.log(p.slug, p.name))
+
+// Browser-side instant search (e.g. for a ⌘K palette)
+const { host, apiKey, indexName } = await lynkow.search.getConfig()
+```
+
+Search must be enabled in **Settings > SEO > Search** before any of these
+methods work. When disabled, every method returns a 503.
+
 ### Site Configuration
 
 ```typescript
@@ -350,12 +380,12 @@ if (redirect) {
 
 ### Media (Image Transformations)
 
-Build optimized image URLs using Cloudflare Image Transformations.
+Build optimized image URLs backed by the Lynkow image transformation service.
 
 ```typescript
 // Build a srcset for responsive images
 const srcset = lynkow.media.srcset(content.featuredImage)
-// => "https://cdn.../cdn-cgi/image/w=400,.../photo.jpg 400w, ...800w, ...1200w, ...1920w"
+// => "https://cdn.../image/w=400,.../photo.jpg 400w, ...800w, ...1200w, ...1920w"
 
 // Custom widths and options
 const srcset = lynkow.media.srcset(content.featuredImage, {
@@ -399,7 +429,7 @@ The API automatically includes pre-computed image variants:
 
 | Field | Available on | Presets |
 |-------|-------------|---------|
-| `featuredImageVariants` | Content | `thumbnail`, `card`, `hero`, `og` |
+| `featuredImageVariants` | Content | `thumbnail`, `card`, `medium`, `content`, `hero`, `og` |
 | `ogImageVariants` | Content | `og` |
 | `imageVariants` | Category | `thumbnail`, `card`, `og` |
 
@@ -1137,7 +1167,7 @@ import type {
 
 ### New in v3.7
 
-- **Image Transformations**: New `lynkow.media` service with `srcset()` and `transform()` helpers for Cloudflare Image Transformations
+- **Image Transformations**: New `lynkow.media` service with `srcset()` and `transform()` helpers backed by the Lynkow image transformation service
 - **ImageVariants type**: API responses now include pre-computed `featuredImageVariants`, `ogImageVariants`, and `imageVariants` fields
 - **Body HTML srcset**: Content body images automatically include `srcset`, `loading="lazy"`, and `decoding="async"` attributes
 

package/dist/index.d.mts

@@ -1515,15 +1515,16 @@ interface SearchOptions extends BaseRequestOptions {
  */
 interface SearchConfig {
     /**
-     * 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.
+     * Public Lynkow search host URL (e.g. `'https://search.lynkow.com'`).
+     * Pass verbatim as the `host` when instantiating a search client in
+     * the browser (for example the `meilisearch-js` npm package, which
+     * speaks the same protocol). Does not include a trailing slash.
      */
     host: string;
     /** Short-lived tenant token (JWT, 1-hour expiry) scoped to your site's index */
     apiKey: string;
     /**
-     * Meilisearch index name for this site, of the form
+     * Lynkow search 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.
      */
@@ -1625,6 +1626,106 @@ declare class SearchService extends BaseService {
      * ```
      */
     getConfig(options?: BaseRequestOptions): Promise<SearchConfig>;
+    /**
+     * List the public search profiles configured for the site.
+     *
+     * Site administrators can create multiple "search profiles", each scoped
+     * to a slice of the content (a category, a set of tags, a path prefix,
+     * etc.) with its own searchable/displayed fields and result limits. Use
+     * this method to render a profile selector or to drive a tabbed search
+     * experience (e.g. one tab per documentation space). Only profiles
+     * marked as public are returned; private profiles remain accessible via
+     * authenticated routes only.
+     *
+     * @param options - Base request options (custom fetch options)
+     * @returns A list of `SearchProfilePublic` (slug, name, description,
+     *   facets, defaultLimit, maxLimit). Internal scope details are not
+     *   exposed.
+     * @throws {LynkowError} With status `503` if search is not enabled for this site
+     *
+     * @example
+     * ```typescript
+     * const profiles = await lynkow.search.listProfiles()
+     * for (const profile of profiles) {
+     *   console.log(profile.slug, profile.name)
+     * }
+     * ```
+     */
+    listProfiles(options?: BaseRequestOptions): Promise<SearchProfilePublic[]>;
+    /**
+     * Search a specific profile.
+     *
+     * Equivalent to `search()` but targets a named profile slug instead of
+     * the site default. The profile's scope, searchable subset, displayed
+     * subset, sort, facets, and limits are applied server-side. Use this
+     * to power per-section search experiences (API docs, marketing, help,
+     * etc.) without re-implementing scoping in the client.
+     *
+     * @param profileSlug - The profile's slug (e.g. `'api-docs'`).
+     *   Must reference a public profile.
+     * @param query - The search query string. Typos are handled automatically.
+     * @param options - Optional locale/category/tag overrides plus pagination.
+     *   These are applied as additional AND filters on top of the profile scope.
+     * @returns A `SearchResponse` containing matched hits and pagination meta.
+     *   When the profile defines `featured` content IDs, those appear first
+     *   on page 1 with `_isFeatured: true`. `boosted` IDs follow with
+     *   `_isBoosted: true`.
+     * @throws {LynkowError} With status `404` if the profile does not exist
+     * @throws {LynkowError} With status `403` if the profile is not public
+     * @throws {LynkowError} With status `503` if search is not enabled for this site
+     *
+     * @example
+     * ```typescript
+     * const results = await lynkow.search.searchByProfile('api-docs', 'pagination', {
+     *   limit: 10,
+     * })
+     * ```
+     */
+    searchByProfile(profileSlug: string, query: string, options?: SearchOptions): Promise<SearchResponse>;
+}
+/**
+ * A public-facing search profile descriptor.
+ *
+ * Returned by `lynkow.search.listProfiles()`. Profiles let site admins
+ * create scoped search experiences (e.g. "API docs", "Marketing", "Help")
+ * each with its own facets and result shape, while sharing a single
+ * underlying search index per site.
+ */
+interface SearchProfilePublic {
+    /**
+     * URL-safe identifier for the profile (e.g. `'default'`, `'api-docs'`).
+     * Pass this value to `lynkow.search.searchByProfile()` to query the
+     * profile. Stable for the lifetime of the profile; renaming the slug
+     * via the admin breaks any URL or bookmark referencing it.
+     */
+    slug: string;
+    /**
+     * Human-readable label shown in profile selectors. Localized to the
+     * site's default locale at the time the profile was last edited.
+     */
+    name: string;
+    /**
+     * Optional admin-authored description explaining what the profile
+     * covers. `null` when the admin did not provide one.
+     */
+    description: string | null;
+    /**
+     * Field names available for facet aggregation when querying this
+     * profile. Pass these to a UI that renders facet checkboxes (e.g.
+     * `categories.slug`, `tags.slug`, `type`, `locale`). Empty array when
+     * the admin did not enable any facet.
+     */
+    facets: string[];
+    /**
+     * Default page size applied when the request omits `limit`. Always
+     * positive; admins set it between 1 and 100.
+     */
+    defaultLimit: number;
+    /**
+     * Upper bound on `limit` accepted by the search endpoint. Requests
+     * with a higher limit are clamped to this value. Always positive.
+     */
+    maxLimit: number;
 }
 
 /**
@@ -1784,12 +1885,18 @@ interface LynkowClient {
 }
 
 /**
- * CDN image variant URLs generated by Cloudflare Image Transformations.
+ * CDN image variant URLs generated by the Lynkow image transformation service.
  *
  * Each property is a pre-generated URL for a specific size/crop preset.
- * All URLs point to Cloudflare's CDN and support WebP/AVIF auto-negotiation
- * via the `Accept` header. Properties are `undefined` when the original image
- * is smaller than the preset dimensions (no upscaling is performed).
+ * All URLs are served through the Lynkow CDN and support WebP/AVIF
+ * auto-negotiation via the `Accept` header. A property is `undefined` only
+ * when the endpoint returning this object excludes that preset from its
+ * response (e.g. category images omit `medium`/`content`). For featured
+ * images on content and pages, the six variants `thumbnail`, `card`,
+ * `medium`, `content`, `hero`, and `og` are always present. The CDN uses
+ * a `scale-down` fit that preserves the original size when the source
+ * image is smaller than the target preset, so every URL is safe to use
+ * in `src` or `srcset` regardless of the source dimensions.
  *
  * Use the smallest variant that fits your layout to minimize bandwidth.
  *
@@ -1807,52 +1914,48 @@ interface ImageVariants {
     /**
      * 400x300px, cover crop with sharpening.
      * Use case: list views, grid thumbnails, small cards.
-     * `undefined` when the original image is smaller than 400x300.
      */
     thumbnail?: string;
     /**
      * 600x400px, cover crop.
      * Use case: card layouts, blog post previews, medium-sized list items.
-     * `undefined` when the original image is smaller than 600x400.
      */
     card?: string;
     /**
      * 1200px wide, scaled down proportionally (no crop).
      * Use case: inline images within article body content.
-     * `undefined` when the original image is narrower than 1200px.
+     * Serves the source at its native size when the original is narrower than 1200px.
      */
     content?: string;
     /**
      * 960px wide, scaled down proportionally (no crop).
      * Use case: medium-width displays, sidebar featured images, tablet layouts.
-     * `undefined` when the original image is narrower than 960px.
+     * Serves the source at its native size when the original is narrower than 960px.
      */
     medium?: string;
     /**
      * 1920px wide, scaled down proportionally (no crop).
      * Use case: full-width hero banners, page headers, background images.
-     * `undefined` when the original image is narrower than 1920px.
+     * Serves the source at its native size when the original is narrower than 1920px.
      */
     hero?: string;
     /**
      * 1200x630px, cover crop.
      * Use case: Open Graph images, social media sharing (Facebook, LinkedIn, Twitter).
      * Dimensions follow the recommended OG image ratio (1.91:1).
-     * `undefined` when the original image is smaller than 1200x630.
      */
     og?: string;
     /**
      * 128x128px, cover crop with face detection gravity.
      * Use case: user avatars, author photos, profile pictures.
      * Face detection ensures faces are centered in the crop.
-     * `undefined` when the original image is smaller than 128x128.
      */
     avatar?: string;
     /**
      * 2560px wide, scaled down proportionally (no crop).
      * Use case: full-resolution display, lightbox/zoom views, retina hero images.
-     * This is the largest available variant. `undefined` when the original
-     * image is narrower than 2560px.
+     * This is the largest available variant. Serves the source at its native size
+     * when the original is narrower than 2560px.
      */
     full?: string;
 }
@@ -2536,7 +2639,7 @@ interface Author {
     fullName: string;
     /**
      * Absolute URL to the author's avatar image, or `null` if no avatar is set.
-     * When available, points to a Cloudflare R2-hosted image.
+     * When available, points to an image hosted on the Lynkow CDN.
      * Use `ImageVariants.avatar` (128x128) for optimized display if available elsewhere.
      */
     avatarUrl: string | null;
@@ -2852,7 +2955,7 @@ interface SeoImage {
     id: string;
     /**
      * Absolute URL to the image file.
-     * Points to a Cloudflare R2-hosted image. Recommended size: 1200x630px for Open Graph.
+     * Points to an image hosted on the Lynkow CDN. Recommended size: 1200x630px for Open Graph.
      * Use this directly in `<meta property="og:image">` or `<meta name="twitter:image">` tags.
      */
     url: string;
@@ -4056,6 +4159,16 @@ interface CookieConfig {
      * When `false`, only "Accept All" and "Reject All" buttons are shown.
      */
     showCustomizeButton?: boolean;
+    /**
+     * Banner layout orientation.
+     * - `'auto'` (default): row layout on screens at least 600px wide,
+     *   automatically stacked into a column under 600px.
+     * - `'column'`: forced column layout at every screen size.
+     *
+     * In every mode the banner is height-capped to the viewport with internal
+     * scrolling, so it never overflows the screen.
+     */
+    orientation?: 'auto' | 'column';
     /**
      * Per-theme color overrides for light and dark modes.
      * Only relevant when {@link theme} is `'auto'`.
@@ -5522,6 +5635,7 @@ declare class ConsentService {
     private resolveTheme;
     private resolveColors;
     private contrastColor;
+    private injectBannerStylesOnce;
     private createBannerHTML;
     private createPreferencesHTML;
     private attachBannerEvents;
@@ -5781,11 +5895,11 @@ interface SrcsetOptions {
      */
     widths?: number[];
     /**
-     * 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.
+     * 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';
     /**
@@ -5802,9 +5916,9 @@ interface SrcsetOptions {
     gravity?: string;
 }
 /**
- * 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.
+ * Options for building a single transformed URL. Each field maps to a
+ * query parameter understood by the Lynkow image transformation service;
+ * omit any value to let the CDN choose a sensible default.
  */
 interface TransformOptions {
     /**
@@ -5843,13 +5957,13 @@ interface TransformOptions {
     dpr?: number;
 }
 /**
- * Service for building optimized image URLs using Cloudflare Image Transformations.
+ * 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 Cloudflare `/cdn-cgi/image/` URLs from Lynkow media URLs.
+ * 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 (`/cdn-cgi/image/...`), re-extracting the original path
- * when needed.
+ * already-transformed URLs, re-extracting the original path when needed.
  *
  * @example
  * ```typescript
@@ -5867,7 +5981,7 @@ declare class MediaHelperService {
     /**
      * Generates an HTML `srcset` attribute value from a Lynkow image URL, suitable
      * for use in an `<img srcset="...">` or `<source srcset="...">` tag. Produces
-     * one Cloudflare Image Transformation URL per width breakpoint.
+     * one Lynkow CDN transformation URL per width breakpoint.
      *
      * @param imageUrl - Original image URL from the Lynkow API (e.g. `content.featuredImage`).
      *   Accepts `null` or `undefined` safely (returns empty string).
@@ -5892,7 +6006,7 @@ declare class MediaHelperService {
      */
     srcset(imageUrl: string | null | undefined, options?: SrcsetOptions): string;
     /**
-     * Generates a single Cloudflare Image Transformation URL from a Lynkow image URL.
+     * Generates a single Lynkow CDN transformation URL from a Lynkow image URL.
      * Useful for thumbnails, hero images, or any context where you need a specific
      * size/format.
      *
@@ -5905,7 +6019,7 @@ declare class MediaHelperService {
      *   - `format` — output format: `'auto'`, `'webp'`, `'avif'`, or `'jpeg'` (default: `'auto'`)
      *   - `gravity` — focal point for crop mode (e.g. `'0.5x0.3'`)
      *   - `dpr` — device pixel ratio 1-4 for retina displays
-     * @returns The transformed Cloudflare URL, the original URL if transformation is
+     * @returns The transformed Lynkow CDN URL, the original URL if transformation is
      *   not possible (non-Lynkow URL), or an empty string if the URL is null/undefined
      *
      * @example
@@ -6394,4 +6508,4 @@ declare function onSiteThemeChange(callback: (theme: 'dark' | 'light') => void):
  */
 declare function renderJsonLdGraph(nodes: object[] | null | undefined): string;
 
-export { type Alternate, AnalyticsService, type ApiErrorDetail, type Author, type BaseRequestOptions, BlocksService, BrandingService, type CategoriesListResponse, CategoriesService, type Category, type CategoryDetail, type CategoryDetailResponse, type CategoryOptions, type CategoryResolveResponse, type CategoryTreeNode, type CategoryTreeResponse, type CategoryWithCount, type Client, type ClientConfig, type ConsentCategories, type ConsentLogResponse, ConsentService, type Content, type ContentBody, type ContentResolveResponse, type ContentSchema, type ContentSummary, type ContentsFilters, type ContentsListResponse, ContentsService, type CookieCategory, type CookieConfig, type CookiePreferences, type CookieTexts, CookiesService, EnhancementsService, type ErrorCode, type EventData, type EventName, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormSettings, type FormSubmitData, type FormSubmitResponse, FormsService, type GlobalBlock, type GlobalBlockResponse, type ImageVariants, type JsonLdGraphConfig, type JsonLdNode, type JsonLdNodeSource, type LegalDocument, LegalService, type LynkowClient, type LynkowConfig, LynkowError, type LynkowEvents, MediaHelperService, type Page, type PageSeo, type PageSummary, type PagesListResponse, PagesService, type PageviewData, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type Path, type PathsListResponse, PathsService, type Redirect, type ResolveResponse, type Review, type ReviewResponse, type ReviewSettings, type ReviewSubmitData, type ReviewSubmitResponse, type ReviewsFilters, type ReviewsListResponse, ReviewsService, type SchemaField, type SchemaFieldOption, type SchemaFieldType, type SchemaFieldValidation, type SearchConfig, type SearchHit, type SearchOptions, type SearchResponse, SearchService, SeoService, type SiteConfig, type SiteConfigResponse, SiteService, type SortOptions, type SrcsetOptions, type SubmitOptions, type Tag, type TagsListResponse, TagsService, type TipTapMark, type TipTapNode, type TransformOptions, browserOnly, browserOnlyAsync, createClient, createLynkowClient, detectSiteTheme, isBrowser, isCategoryResolve, isContentResolve, isLynkowError, isServer, onSiteThemeChange, renderJsonLdGraph };
+export { type Alternate, AnalyticsService, type ApiErrorDetail, type Author, type BaseRequestOptions, BlocksService, BrandingService, type CategoriesListResponse, CategoriesService, type Category, type CategoryDetail, type CategoryDetailResponse, type CategoryOptions, type CategoryResolveResponse, type CategoryTreeNode, type CategoryTreeResponse, type CategoryWithCount, type Client, type ClientConfig, type ConsentCategories, type ConsentLogResponse, ConsentService, type Content, type ContentBody, type ContentResolveResponse, type ContentSchema, type ContentSummary, type ContentsFilters, type ContentsListResponse, ContentsService, type CookieCategory, type CookieConfig, type CookiePreferences, type CookieTexts, CookiesService, EnhancementsService, type ErrorCode, type EventData, type EventName, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormSettings, type FormSubmitData, type FormSubmitResponse, FormsService, type GlobalBlock, type GlobalBlockResponse, type ImageVariants, type JsonLdGraphConfig, type JsonLdNode, type JsonLdNodeSource, type LegalDocument, LegalService, type LynkowClient, type LynkowConfig, LynkowError, type LynkowEvents, MediaHelperService, type Page, type PageSeo, type PageSummary, type PagesListResponse, PagesService, type PageviewData, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type Path, type PathsListResponse, PathsService, type Redirect, type ResolveResponse, type Review, type ReviewResponse, type ReviewSettings, type ReviewSubmitData, type ReviewSubmitResponse, type ReviewsFilters, type ReviewsListResponse, ReviewsService, type SchemaField, type SchemaFieldOption, type SchemaFieldType, type SchemaFieldValidation, type SearchConfig, type SearchHit, type SearchOptions, type SearchProfilePublic, type SearchResponse, SearchService, SeoService, type SiteConfig, type SiteConfigResponse, SiteService, type SortOptions, type SrcsetOptions, type SubmitOptions, type Tag, type TagsListResponse, TagsService, type TipTapMark, type TipTapNode, type TransformOptions, browserOnly, browserOnlyAsync, createClient, createLynkowClient, detectSiteTheme, isBrowser, isCategoryResolve, isContentResolve, isLynkowError, isServer, onSiteThemeChange, renderJsonLdGraph };