lynkow 3.8.77 → 3.8.78

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
@@ -350,12 +350,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 +399,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 +1137,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.
      */
@@ -1784,12 +1785,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 +1814,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 +2539,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 +2855,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 +4059,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 +5535,7 @@ declare class ConsentService {
     private resolveTheme;
     private resolveColors;
     private contrastColor;
+    private injectBannerStylesOnce;
     private createBannerHTML;
     private createPreferencesHTML;
     private attachBannerEvents;
@@ -5781,11 +5795,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 +5816,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 +5857,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 +5881,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 +5906,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 +5919,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

package/dist/index.d.ts

@@ -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.
      */
@@ -1784,12 +1785,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 +1814,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 +2539,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 +2855,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 +4059,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 +5535,7 @@ declare class ConsentService {
     private resolveTheme;
     private resolveColors;
     private contrastColor;
+    private injectBannerStylesOnce;
     private createBannerHTML;
     private createPreferencesHTML;
     private attachBannerEvents;
@@ -5781,11 +5795,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 +5816,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 +5857,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 +5881,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 +5906,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 +5919,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