@foir/sdk 0.4.0 → 0.7.0

package/dist/index.d.ts

@@ -1,394 +1,10 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
-
-/**
- * Public type definitions for the Editor SDK.
- */
-
-/** Data provided by the host when the editor initializes. */
-interface EditorInit {
-    values: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-    modelKey: string;
-    recordId: string;
-    naturalKey?: string;
-    versionId: string | null;
-    variantKey: string | null;
-    locale: string | null;
-    schema: unknown;
-    mode: 'edit' | 'readonly';
-    theme: 'light' | 'dark';
-    /** Secret API key for public API access. */
-    apiKey: string;
-    /** Public API GraphQL endpoint URL (provided by host). */
-    apiUrl: string;
-    /** Config connection domain (e.g. my-store.myshopify.com) */
-    connectionDomain?: string;
-    /** How this editor is rendered in the admin UI. */
-    configMode?: 'editor' | 'sidebar';
-    /** Currently selected field keys (sidebar mode). */
-    selectedFieldKeys?: string[];
-    /** Available fields for selection (sidebar mode). */
-    selectableFields?: Array<{
-        key: string;
-        label: string;
-        type: string;
-    }>;
-    /** Locale context (sidebar mode). */
-    localeContext?: LocaleContext | null;
-}
-/** Locale context passed by the host for sidebar editors. */
-interface LocaleContext {
-    currentLocale: string;
-    sourceLocale: string;
-    isTranslating: boolean;
-    locales: Array<{
-        code: string;
-        displayName: string;
-        isDefault: boolean;
-    }>;
-}
-/** Value exposed by the EditorProvider context. */
-interface EditorContextValue {
-    /** Whether the editor has received init data from the host. */
-    isReady: boolean;
-    /** Initial data from the host (available after init). */
-    init: EditorInit | null;
-    /** Current host theme. */
-    theme: 'light' | 'dark';
-    /** Platform GraphQL client (available after init). */
-    client: PlatformClient;
-    /** Send complete form values to the host (full replacement). */
-    updateValues: (values: Record<string, unknown>) => void;
-    /** Send a single field update to the host. */
-    updateField: (path: string, value: unknown) => void;
-    /** Request the host to save the current values. */
-    requestSave: () => void;
-    /** Request the host to publish the current version. */
-    requestPublish: () => void;
-    /** Report iframe height for auto-resize. */
-    resize: (height: number) => void;
-    /** Report dirty state (unsaved changes). */
-    setDirty: (isDirty: boolean) => void;
-    /** Request the host to navigate to an admin path. */
-    requestNavigate: (path: string) => void;
-    /** Request the host to execute a platform operation. Returns the result.
-     * `mode` controls whether the platform waits for the operation to complete
-     * ('sync') or returns immediately after queueing ('async'). Defaults to 'sync'. */
-    requestOperation: (operationKey: string, input?: Record<string, unknown>, options?: {
-        mode?: 'sync' | 'async';
-    }) => Promise<{
-        success: boolean;
-        result?: unknown;
-        error?: {
-            code: string;
-            message: string;
-        };
-    }>;
-    /** Editor mode ('editor' or 'sidebar'). */
-    configMode: 'editor' | 'sidebar';
-    /** Currently selected field keys (sidebar mode). */
-    selectedFieldKeys: string[];
-    /** Available fields for selection (sidebar mode). */
-    selectableFields: Array<{
-        key: string;
-        label: string;
-        type: string;
-    }>;
-    /** Locale context (sidebar mode). */
-    localeContext: LocaleContext | null;
-}
-/** Options for creating a PlatformClient. */
-interface PlatformClientOptions {
-    /** GraphQL endpoint URL. */
-    apiUrl: string;
-    /** API key for authentication. */
-    apiKey: string;
-}
-/** A minimal GraphQL error shape. */
-interface GraphQLError {
-    message: string;
-    locations?: Array<{
-        line: number;
-        column: number;
-    }>;
-    path?: Array<string | number>;
-    extensions?: Record<string, unknown>;
-}
-/** Response shape from a GraphQL query/mutation. */
-interface GraphQLResponse<T = Record<string, unknown>> {
-    data: T | null;
-    errors?: GraphQLError[];
-}
-/** Fetch-based GraphQL client for platform API calls. */
-interface PlatformClient {
-    /** Execute a GraphQL query or mutation. */
-    query<T = Record<string, unknown>>(query: string, variables?: Record<string, unknown>): Promise<GraphQLResponse<T>>;
-}
-
-interface EditorProviderProps {
-    children: ReactNode;
-    /**
-     * Parent window origin for postMessage validation.
-     * Must be an explicit origin (e.g., 'https://admin.example.com').
-     * Falls back to VITE_PARENT_ORIGIN or NEXT_PUBLIC_PARENT_ORIGIN env var.
-     */
-    parentOrigin?: string;
-    /**
-     * Platform API URL for GraphQL requests.
-     * Falls back to VITE_API_URL or NEXT_PUBLIC_API_URL env var.
-     */
-    apiUrl?: string;
-    onInit?: (init: EditorInit) => void;
-    onValuesChanged?: (values: Record<string, unknown>) => void;
-    onVariantChanged?: (variantKey: string, values: Record<string, unknown>) => void;
-    onSaveResult?: (success: boolean, error?: string, versionId?: string) => void;
-    onPublishResult?: (success: boolean, error?: string) => void;
-    onThemeChanged?: (theme: 'light' | 'dark') => void;
-    onSelectionChanged?: (keys: string[], fields: Array<{
-        key: string;
-        label: string;
-        type: string;
-    }>) => void;
-    onLocaleChanged?: (locale: LocaleContext) => void;
-}
-declare function EditorProvider({ children, parentOrigin: parentOriginProp, apiUrl: apiUrlProp, onInit, onValuesChanged, onVariantChanged, onSaveResult, onPublishResult, onThemeChanged, onSelectionChanged, onLocaleChanged, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Access the Foir editor context.
- *
- * Must be used inside an `<EditorProvider>`.
- *
- * @example
- * ```tsx
- * function MyEditor() {
- *   const { isReady, init, client, updateField, setDirty } = useEditor();
- *   if (!isReady) return <p>Loading...</p>;
- *   return <form>...</form>;
- * }
- * ```
- */
-declare function useEditor(): EditorContextValue;
-
-interface UseAutoResizeOptions {
-    /** Minimum height to report (prevents too-small iframes). @default 400 */
-    minHeight?: number;
-    /** Debounce delay in milliseconds. @default 100 */
-    debounce?: number;
-    /** Whether auto-resize is enabled. @default true */
-    enabled?: boolean;
-}
-/**
- * Automatically resize the host iframe based on content height.
- *
- * @returns A callback ref to attach to your root container element.
- *
- * @example
- * ```tsx
- * function MyEditor() {
- *   const containerRef = useAutoResize({ minHeight: 600 });
- *   return <div ref={containerRef}>...</div>;
- * }
- * ```
- */
-declare function useAutoResize(options?: UseAutoResizeOptions): (node: HTMLDivElement | null) => void;
-
-/**
- * Fetch-based GraphQL client for the EIDE platform API.
- *
- * Zero dependencies — uses the native Fetch API.
- */
-
-/** Error thrown when a platform API request fails. */
-declare class PlatformClientError extends Error {
-    status?: number | undefined;
-    response?: unknown | undefined;
-    constructor(message: string, status?: number | undefined, response?: unknown | undefined);
-}
-/**
- * Create a PlatformClient instance.
- *
- * @example
- * ```ts
- * const client = createPlatformClient({
- *   apiUrl: 'https://api.example.com/graphql',
- *   apiKey: 'sk_test_...',
- * });
- *
- * const { data } = await client.query(
- *   `query GetProduct($id: ID!) { product(id: $id) { title } }`,
- *   { id: '123' }
- * );
- * ```
- */
-declare function createPlatformClient(options: PlatformClientOptions): PlatformClient;
-
-/**
- * PostMessage protocol types between EIDE platform host and extension iframes.
- *
- * Inlined from the platform protocol to keep the SDK zero-dep.
- */
-/**
- * Messages sent FROM the platform host TO the iframe extension.
- */
-type HostToEditorMessage = {
-    type: 'init';
-    payload: {
-        values: Record<string, unknown>;
-        metadata?: Record<string, unknown>;
-        modelKey: string;
-        recordId: string;
-        naturalKey?: string;
-        versionId: string | null;
-        variantKey: string | null;
-        locale: string | null;
-        schema: unknown;
-        mode: 'edit' | 'readonly';
-        theme: 'light' | 'dark';
-        apiKey: string;
-        apiUrl: string;
-        connectionDomain?: string;
-        configMode?: 'editor' | 'sidebar';
-        selectedFieldKeys?: string[];
-        selectableFields?: Array<{
-            key: string;
-            label: string;
-            type: string;
-        }>;
-        localeContext?: {
-            currentLocale: string;
-            sourceLocale: string;
-            isTranslating: boolean;
-            locales: Array<{
-                code: string;
-                displayName: string;
-                isDefault: boolean;
-            }>;
-        };
-    };
-} | {
-    type: 'values-changed';
-    payload: {
-        values: Record<string, unknown>;
-        source: 'remote';
-    };
-} | {
-    type: 'variant-changed';
-    payload: {
-        variantKey: string;
-        values: Record<string, unknown>;
-    };
-} | {
-    type: 'save-result';
-    payload: {
-        success: boolean;
-        error?: string;
-        versionId?: string;
-    };
-} | {
-    type: 'publish-result';
-    payload: {
-        success: boolean;
-        error?: string;
-    };
-} | {
-    type: 'theme-changed';
-    payload: {
-        theme: 'light' | 'dark';
-    };
-} | {
-    type: 'selection-changed';
-    payload: {
-        selectedFieldKeys: string[];
-        fields: Array<{
-            key: string;
-            label: string;
-            type: string;
-        }>;
-    };
-} | {
-    type: 'locale-changed';
-    payload: {
-        currentLocale: string;
-        sourceLocale: string;
-        isTranslating: boolean;
-        locales: Array<{
-            code: string;
-            displayName: string;
-            isDefault: boolean;
-        }>;
-    };
-} | {
-    type: 'operation-result';
-    payload: {
-        requestId: string;
-        success: boolean;
-        result?: unknown;
-        error?: {
-            code: string;
-            message: string;
-        };
-    };
-};
-/**
- * Messages sent FROM the iframe extension TO the platform host.
- */
-type EditorToHostMessage = {
-    type: 'ready';
-    payload: Record<string, never>;
-} | {
-    type: 'update-values';
-    payload: {
-        values: Record<string, unknown>;
-    };
-} | {
-    type: 'update-field';
-    payload: {
-        path: string;
-        value: unknown;
-    };
-} | {
-    type: 'request-save';
-    payload: Record<string, never>;
-} | {
-    type: 'request-publish';
-    payload: Record<string, never>;
-} | {
-    type: 'resize';
-    payload: {
-        height: number;
-    };
-} | {
-    type: 'dirty';
-    payload: {
-        isDirty: boolean;
-    };
-} | {
-    type: 'request-navigate';
-    payload: {
-        path: string;
-    };
-} | {
-    type: 'request-operation';
-    payload: {
-        operationKey: string;
-        input?: Record<string, unknown>;
-        requestId: string;
-        /** Execution mode: 'sync' waits for completion, 'async' queues and returns. */
-        mode?: 'sync' | 'async';
-    };
-};
-
-/**
- * Runtime validation for postMessage payloads.
- */
-
-/** Validate an incoming message from a custom editor iframe (editor -> host). */
-declare function isValidEditorMessage(data: unknown): data is EditorToHostMessage;
-/** Validate an incoming message from the platform host (host -> editor). */
-declare function isValidHostMessage(data: unknown): data is HostToEditorMessage;
-
-/** Protocol version for compatibility checks. */
-declare const PROTOCOL_VERSION = "1.0";
-
-export { type EditorContextValue, type EditorInit, EditorProvider, type EditorProviderProps, type EditorToHostMessage, type GraphQLError, type GraphQLResponse, type HostToEditorMessage, type LocaleContext, PROTOCOL_VERSION, type PlatformClient, PlatformClientError, type PlatformClientOptions, type UseAutoResizeOptions, createPlatformClient, isValidEditorMessage, isValidHostMessage, useAutoResize, useEditor };
+export { EditorProvider } from './components/EditorProvider';
+export type { EditorProviderProps } from './components/EditorProvider';
+export { useEditor } from './hooks/useEditor';
+export { useAutoResize } from './hooks/useAutoResize';
+export type { UseAutoResizeOptions } from './hooks/useAutoResize';
+export { createPlatformClient, PlatformClientError, } from './client/platform-client';
+export type { EditorInit, EditorContextValue, LocaleContext, PlatformClient, PlatformClientOptions, GraphQLResponse, GraphQLError, } from './types';
+export type { HostToEditorMessage, EditorToHostMessage, } from './protocol/messages';
+export { isValidEditorMessage, isValidHostMessage, } from './protocol/validation';
+export { PROTOCOL_VERSION } from './protocol/constants';

package/dist/media/BlurhashCanvas.d.ts

@@ -0,0 +1,10 @@
+export interface BlurhashCanvasProps {
+    hash: string;
+    className?: string;
+}
+/**
+ * Decodes a BlurHash string to a 32×32 canvas. `blurhash` is an optional peer
+ * dependency loaded via dynamic import — if it isn't installed the canvas
+ * stays blank rather than throwing.
+ */
+export declare function BlurhashCanvas({ hash, className }: BlurhashCanvasProps): import("react/jsx-runtime").JSX.Element;

package/dist/media/ProgressiveMedia.d.ts

@@ -0,0 +1,56 @@
+import type { ProgressiveImageSource, ProgressiveVideoSource, VariantTierKey } from './media';
+export interface ProgressiveMediaProps {
+    image?: ProgressiveImageSource;
+    video?: ProgressiveVideoSource;
+    alt?: string;
+    className?: string;
+    /** Fill the parent container instead of using intrinsic aspect ratio. */
+    fill?: boolean;
+    /**
+     * Object-fit for fill mode. Defaults to 'cover'. Has no effect when `fill`
+     * is false (the image renders at its intrinsic aspect ratio).
+     */
+    fit?: 'cover' | 'contain';
+    /**
+     * Solid-colour placeholder mode. When neither image nor video is provided,
+     * render a flat coloured div. `aspectRatio` defaults to 16/10.
+     */
+    placeholder?: {
+        color: string;
+        aspectRatio?: number;
+    };
+    /** Video playback — autoplay on mount. Default true. */
+    autoplay?: boolean;
+    /** Video playback — muted. Default true (required for autoplay). */
+    muted?: boolean;
+    /** Video playback — loop on end. Default true. */
+    loop?: boolean;
+    /**
+     * When false, skip loading the full media layer (no `<video>`/full `<img>`
+     * mount, no HLS attach, no full-image preload). The lower layers — colour,
+     * blurhash, thumbnail — still render. Used by responsive dual-render so the
+     * CSS-hidden branch doesn't download its full asset. Default true.
+     */
+    active?: boolean;
+    /**
+     * `sizes` attribute applied to the full `<img>` — tells the browser how
+     * wide the image renders so it can pick the right `srcset` entry. Default
+     * `"100vw"`. Has no effect on video sources.
+     */
+    sizes?: string;
+    /**
+     * When true, treat this media as the page's LCP candidate: thumbnail and
+     * full `<img>` get `fetchpriority="high"` + `loading="eager"`, and any
+     * `<video>` mounts immediately. When false (default) below-fold behaviour:
+     * `loading="lazy"` on `<img>`, and `<video>` is gated by an
+     * IntersectionObserver so its `src`/HLS only attaches near the viewport.
+     */
+    priority?: boolean;
+    /**
+     * Tier order, smallest→largest, used to build the `srcset` from a
+     * `VariantSet`. Defaults to {@link DEFAULT_VARIANT_TIERS}; override when a
+     * project curates a different tier set.
+     */
+    variantTiers?: readonly VariantTierKey[];
+}
+export declare function ProgressiveMedia({ image, video, alt, className, fill, fit, placeholder, autoplay, muted, loop, active, sizes, priority, variantTiers, }: ProgressiveMediaProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/media/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@foir/sdk/media` — progressive media components + Foir media adapters.
+ *
+ * `react` is a peer dependency; `hls.js` and `blurhash` are optional peers
+ * loaded lazily (video/blurhash gracefully no-op when absent).
+ */
+export { ProgressiveMedia } from './ProgressiveMedia';
+export type { ProgressiveMediaProps } from './ProgressiveMedia';
+export { BlurhashCanvas } from './BlurhashCanvas';
+export type { BlurhashCanvasProps } from './BlurhashCanvas';
+export { useProgressiveLoad } from './useProgressiveLoad';
+export type { LoadStage, UseProgressiveLoadOptions } from './useProgressiveLoad';
+export { toProgressiveImage, toProgressiveVideo, effectiveImageDimensions, cropAspectRatio, DEFAULT_VARIANT_TIERS, } from './media';
+export type { VariantTier, VariantSet, VariantTierKey, ProgressiveImageSource, ProgressiveVideoSource, FoirImageInput, FoirVideoInput, } from './media';

package/dist/media/media.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Foir media types + adapters.
+ *
+ * Framework-agnostic plumbing for rendering Foir image/video fields with
+ * `<ProgressiveMedia>`: the canonical source shapes, GraphQL-value → source
+ * adapters (crop normalization, per-format variant sets, HLS URL
+ * absolutising), and crop-aware dimension maths for CLS-free layout.
+ *
+ * HLS manifest URLs are absolutised via the shared `absolutiseFoirMediaUrl`
+ * from the client transport — not re-implemented here.
+ */
+/** One rendered tier: a URL + its TRUE (crop-aware) dims (for srcset `w` + CLS). */
+export interface VariantTier {
+    url: string;
+    width?: number | null;
+    height?: number | null;
+}
+/** Curated tier set in one format (Foir `ImageVariantSet`). */
+export interface VariantSet {
+    thumbnail?: VariantTier | null;
+    small?: VariantTier | null;
+    medium?: VariantTier | null;
+    large?: VariantTier | null;
+    xlarge?: VariantTier | null;
+    _2xl?: VariantTier | null;
+    _3xl?: VariantTier | null;
+    _4xl?: VariantTier | null;
+}
+/** A `VariantSet` tier name. */
+export type VariantTierKey = keyof VariantSet;
+/**
+ * Default tier order, smallest→largest, for walking a `VariantSet`
+ * deterministically when building a `srcset`. Override per `<ProgressiveMedia>`
+ * via the `variantTiers` prop when a project curates a different tier set.
+ */
+export declare const DEFAULT_VARIANT_TIERS: readonly VariantTierKey[];
+/** Image source with progressive loading data. */
+export interface ProgressiveImageSource {
+    url: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    blurhash?: string;
+    dominantColor?: string;
+    thumbnailUrl?: string;
+    /** Per-format tier sets (WebP universal; AVIF preferred via `<picture>`). */
+    webp?: VariantSet | null;
+    avif?: VariantSet | null;
+    /**
+     * Optional crop rectangle expressed as percentages of the source image
+     * (`{x, y, width, height}` in 0–100). Foir's image pipeline serves the
+     * cropped file at the cropped dimensions, so consumers need this to compute
+     * correct `width`/`height` attrs for CLS-free rendering.
+     */
+    crop?: {
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+    };
+}
+/** Video source with progressive loading data + optional HLS. */
+export interface ProgressiveVideoSource {
+    url: string;
+    width?: number;
+    height?: number;
+    blurhash?: string;
+    dominantColor?: string;
+    thumbnailUrl?: string;
+    previewUrl?: string;
+    hlsUrl?: string;
+    duration?: number;
+}
+/**
+ * Foir GraphQL `ImageValue`-like input — the shape a consumer's codegen
+ * produces for an image field (intrinsic dims + per-format variant sets +
+ * crop as opaque JSON). Structurally compatible with the generated type.
+ */
+export interface FoirImageInput {
+    url?: string | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+    blurhash?: string | null;
+    dominantColor?: string | null;
+    webp?: VariantSet | null;
+    avif?: VariantSet | null;
+    crop?: {
+        [key: string]: unknown;
+    } | null;
+}
+/** Foir GraphQL `VideoValue`-like input. */
+export interface FoirVideoInput {
+    url?: string | null;
+    width?: number | null;
+    height?: number | null;
+    hlsManifestUrl?: string | null;
+    thumbnailUrl?: string | null;
+    previewUrl?: string | null;
+    blurhash?: string | null;
+    dominantColor?: string | null;
+}
+/**
+ * Adapt a Foir image field to the `ProgressiveImageSource` consumed by
+ * `<ProgressiveMedia>`. Returns `undefined` when the field is empty (the
+ * caller falls back to a placeholder). Narrows the JSON-typed `crop` to the
+ * numeric keys; out-of-range values are filtered in `effectiveImageDimensions`.
+ */
+export declare function toProgressiveImage(img: FoirImageInput | null | undefined): ProgressiveImageSource | undefined;
+/**
+ * Adapt a Foir video field to the `ProgressiveVideoSource` consumed by
+ * `<ProgressiveMedia>`. Absolutises the HLS manifest URL (Foir returns it
+ * relative to its media proxy). Returns `undefined` when the field is empty.
+ */
+export declare function toProgressiveVideo(v: FoirVideoInput | null | undefined): ProgressiveVideoSource | undefined;
+/**
+ * Resolve the dimensions of the file Foir's pipeline will actually serve,
+ * applying any crop percentages to the source's intrinsic size. Returns null
+ * when the source has no width/height. Drives both the wrapper aspect-ratio
+ * and the `<img>` `width`/`height` attrs.
+ */
+export declare function effectiveImageDimensions(image: {
+    width?: number | null;
+    height?: number | null;
+    crop?: unknown;
+} | null | undefined): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * Compute a CSS `aspect-ratio` string from a Foir image's natural dimensions
+ * and optional crop. When a usable crop is set the cropped rectangle's aspect
+ * wins; otherwise the intrinsic width/height; otherwise `null`.
+ */
+export declare function cropAspectRatio(image: {
+    width?: number | null;
+    height?: number | null;
+    crop?: unknown;
+} | null | undefined): string | null;

package/dist/media/useProgressiveLoad.d.ts

@@ -0,0 +1,23 @@
+export type LoadStage = 'color' | 'blurhash' | 'thumbnail' | 'full';
+export interface UseProgressiveLoadOptions {
+    blurhash?: string;
+    thumbnailUrl?: string;
+    fullUrl?: string;
+    /**
+     * Optional srcset + sizes — when provided to image sources, the preloader
+     * matches the variant the visible `<img>` will pick, so the browser dedupes
+     * the fetch instead of downloading two sizes.
+     */
+    fullSrcSet?: string;
+    fullSizes?: string;
+    isVideo?: boolean;
+}
+/**
+ * State machine for progressive media loading.
+ * Stages advance forward only: color → blurhash → thumbnail → full.
+ * Skips stages when data is missing. Never regresses.
+ */
+export declare function useProgressiveLoad({ blurhash, thumbnailUrl, fullUrl, fullSrcSet, fullSizes, isVideo, }: UseProgressiveLoadOptions): {
+    stage: LoadStage;
+    onFullReady: () => void;
+};

package/dist/media.js

@@ -2,7 +2,12 @@
 import { useRef as useRef2, useState as useState2, useCallback as useCallback2, useEffect as useEffect3 } from "react";
 
 // src/graphql/foir-request.ts
+import { print as print2 } from "graphql";
+
+// src/graphql/cdn-route.ts
 import { print } from "graphql";
+
+// src/graphql/foir-request.ts
 var FOIR_CDN_BASE = "https://cdn.foir.dev/";
 function absolutiseFoirMediaUrl(url, cdnBase = FOIR_CDN_BASE) {
   if (!url) return void 0;

package/dist/next/cookieAdapter.d.ts

@@ -0,0 +1,26 @@
+import type { SessionAdapter } from '../auth';
+/**
+ * The minimal cookie-store shape this adapter needs. It's satisfied by Next's
+ * `cookies()` (route handlers / server actions — `await cookies()` on Next 15),
+ * and by `NextResponse.cookies` in middleware. Kept structural on purpose so the
+ * SDK doesn't import (or pin a version of) `next/headers`.
+ */
+export interface FoirCookieStore {
+    get(name: string): {
+        value: string;
+    } | undefined;
+    set(name: string, value: string, options?: Record<string, unknown>): void;
+    delete(name: string): void;
+}
+export interface CookieAdapterOptions {
+    /** Cookie attributes for writes, merged over the secure defaults. */
+    cookieOptions?: Record<string, unknown>;
+}
+export declare function foirCookieName(key: string): string;
+/**
+ * A {@link SessionAdapter} backed by an HttpOnly cookie store — the seam for
+ * server-side (BFF) Foir sessions in Next.js. Pass the cookie store from a route
+ * handler / server action (`await cookies()`) for reads and writes; a Server
+ * Component's `cookies()` is read-only, so use it only for reads there.
+ */
+export declare function createFoirCookieAdapter(store: FoirCookieStore, opts?: CookieAdapterOptions): SessionAdapter;