@foir/sdk 0.5.0 → 0.7.0

package/dist/client.js

@@ -1,13 +1,15 @@
 // src/graphql/foir-request.ts
+import { print as print2 } from "graphql";
+
+// src/graphql/cdn-route.ts
 import { print } from "graphql";
+
+// src/transport/foir-http.ts
 function isFoirPreview(env) {
   return env.FOIR_PREVIEW === "true";
 }
-var FOIR_CDN_BASE = "https://cdn.foir.dev/";
-function absolutiseFoirMediaUrl(url, cdnBase = FOIR_CDN_BASE) {
-  if (!url) return void 0;
-  if (/^https?:\/\//i.test(url)) return url;
-  return cdnBase + url.replace(/^\/+/, "");
+function resolveFoirApiKey(env) {
+  return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
 }
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
@@ -22,41 +24,95 @@ var FoirRequestError = class extends Error {
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
   }
+  /**
+   * The code of the first error, if the response carried one.
+   *
+   * A getter rather than a stored field so it stays correct for an error
+   * constructed anywhere, including by a caller in a test.
+   */
+  get code() {
+    return this.graphQLErrors?.[0]?.extensions?.code;
+  }
+  /** The correlation id, if the response carried one. */
+  get requestId() {
+    return this.graphQLErrors?.[0]?.extensions?.requestId;
+  }
+  /**
+   * Whether retrying this request could succeed.
+   *
+   * The 429 is the one that has to be in here and is easy to leave out: it sits
+   * among the 4xx statuses that are otherwise permanent, so a policy written as
+   * "retry 5xx, never retry 4xx" excludes exactly the failure that clears on its
+   * own. A storefront wrote that policy, its key saturated, and every read
+   * failed on the first attempt for an hour.
+   */
+  get retryable() {
+    if (this.status === void 0) return true;
+    if (this.status === 429 || this.code === "RATE_LIMITED") return true;
+    if (this.status >= 500) return true;
+    return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+  }
+  /**
+   * How long to wait before retrying, in milliseconds, when the server said.
+   * Undefined when it did not, which means the caller picks its own backoff.
+   */
+  get retryAfterMs() {
+    const seconds = this.graphQLErrors?.[0]?.extensions?.retryAfter;
+    return typeof seconds === "number" && seconds > 0 ? seconds * 1e3 : void 0;
+  }
 };
-async function foirRequest(env, document, variables, options) {
-  const endpoint = env.PLATFORM_API_URL;
-  const apiKey = isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
-  if (!endpoint || !apiKey) {
-    throw new FoirRequestError(
-      "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
-    );
+function isFoirRateLimited(err) {
+  return err instanceof FoirRequestError && (err.status === 429 || err.code === "RATE_LIMITED");
+}
+function isFoirUnauthenticated(err) {
+  return err instanceof FoirRequestError && (err.status === 401 || err.code === "UNAUTHENTICATED");
+}
+function isFoirForbidden(err) {
+  return err instanceof FoirRequestError && (err.status === 403 || err.code === "PERMISSION_DENIED");
+}
+function isFoirNotFound(err) {
+  return err instanceof FoirRequestError && err.code === "NOT_FOUND";
+}
+function readFoirRateLimit(headers) {
+  const raw = {
+    limit: headers.get("X-RateLimit-Limit"),
+    remaining: headers.get("X-RateLimit-Remaining"),
+    resetAt: headers.get("X-RateLimit-Reset")
+  };
+  if (raw.limit === null || raw.remaining === null || raw.resetAt === null) {
+    return void 0;
   }
+  const limit = Number(raw.limit);
+  const remaining = Number(raw.remaining);
+  const resetAt = Number(raw.resetAt);
+  if (!Number.isFinite(limit) || !Number.isFinite(remaining) || !Number.isFinite(resetAt)) {
+    return void 0;
+  }
+  return { limit, remaining, resetAt };
+}
+function readFoirRetryAfterMs(headers) {
+  const seconds = Number(headers.get("Retry-After"));
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
+}
+function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json",
-    "x-api-key": apiKey
+    "x-api-key": input.apiKey
   };
-  if (isFoirPreview(env)) {
+  if (input.draftChannel) {
     headers["X-Foir-Schema-Channel"] = "draft";
   }
-  if (options?.bearerToken) {
-    headers["Authorization"] = `Bearer ${options.bearerToken}`;
+  if (input.bearerToken) {
+    headers["Authorization"] = `Bearer ${input.bearerToken}`;
   }
-  let res;
-  try {
-    res = await fetch(endpoint, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ query: print(document), variables })
-    });
-  } catch (err) {
-    throw new FoirRequestError("[foir] network error", { cause: err });
-  }
-  if (!res.ok) {
-    throw new FoirRequestError(`[foir] HTTP ${res.status} ${res.statusText}`, {
-      status: res.status
-    });
+  if (input.extra) {
+    for (const [key, value] of Object.entries(input.extra)) {
+      headers[key] = value;
+    }
   }
-  const json = await res.json();
+  return headers;
+}
+function readFoirEnvelope(json) {
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
     if (json.data) {
@@ -73,15 +129,196 @@ async function foirRequest(env, document, variables, options) {
   return json.data;
 }
 
+// src/graphql/cdn-route.ts
+var CDN_PATH = "/cdn/graphql";
+function isCdnEligible(env, documentText, bearerToken) {
+  if (bearerToken) return false;
+  if (isFoirPreview(env)) return false;
+  const apiKey = resolveFoirApiKey(env);
+  if (!apiKey?.startsWith("pk_")) return false;
+  return !/\bmutation\b/.test(documentText);
+}
+function buildCdnUrl(endpoint, apiKey, hash, variables) {
+  const url = new URL(endpoint);
+  url.pathname = url.pathname.replace(/\/graphql\/?$/, "") + CDN_PATH;
+  url.searchParams.set("key", apiKey);
+  url.searchParams.set("extensions", JSON.stringify(persistedQueryExtension(hash)));
+  if (variables && Object.keys(variables).length > 0) {
+    url.searchParams.set("variables", JSON.stringify(variables));
+  }
+  return url.toString();
+}
+function persistedQueryExtension(hash) {
+  return { persistedQuery: { version: 1, sha256Hash: hash } };
+}
+async function documentHash(documentText) {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(documentText)
+  );
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var PERSISTED_QUERY_NOT_FOUND = "PERSISTED_QUERY_NOT_FOUND";
+var NOT_SHAREABLE = "NOT_SHAREABLE";
+
+// src/transport/retry.ts
+var DEFAULT_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 200;
+var DEFAULT_MAX_DELAY_MS = 2e4;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function foirRetryDelayMs(error, attempt, policy = {}) {
+  if (!(error instanceof FoirRequestError) || !error.retryable) return null;
+  const max = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const stated = error.retryAfterMs;
+  if (stated !== void 0) return Math.min(stated, max);
+  const base = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  return Math.min(base * 2 ** (attempt - 1), max);
+}
+async function withFoirRetry(fn, policy = {}) {
+  const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
+  const sleep = policy.sleep ?? defaultSleep;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      const delayMs = attempt >= attempts ? null : foirRetryDelayMs(error, attempt, policy);
+      if (delayMs === null) throw error;
+      policy.onRetry?.({ attempt, delayMs, error });
+      await sleep(delayMs);
+    }
+  }
+}
+
+// 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;
+  if (/^https?:\/\//i.test(url)) return url;
+  return cdnBase + url.replace(/^\/+/, "");
+}
+async function foirRequest(env, document, variables, options) {
+  const endpoint = env.PLATFORM_API_URL;
+  const apiKey = resolveFoirApiKey(env);
+  if (!endpoint || !apiKey) {
+    throw new FoirRequestError(
+      "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
+    );
+  }
+  const headers = buildFoirHeaders({
+    apiKey,
+    draftChannel: isFoirPreview(env),
+    bearerToken: options?.bearerToken
+  });
+  const documentText = print2(document);
+  let res;
+  try {
+    if (isCdnEligible(env, documentText, options?.bearerToken)) {
+      const hash = await documentHash(documentText);
+      let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
+        method: "GET",
+        headers
+      });
+      if (await isPersistedQueryMiss(shared)) {
+        shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            query: documentText,
+            variables,
+            extensions: persistedQueryExtension(hash)
+          })
+        });
+      }
+      if (await isSharedRefusal(shared)) {
+        res = await fetch(endpoint, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ query: documentText, variables })
+        });
+      } else {
+        res = shared;
+      }
+    } else {
+      res = await fetch(endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query: documentText, variables })
+      });
+    }
+  } catch (err) {
+    throw new FoirRequestError("[foir] network error", { cause: err });
+  }
+  options?.onRateLimit?.(readFoirRateLimit(res.headers));
+  if (!res.ok) {
+    const errors = await readErrorEnvelope(res);
+    const first = errors?.[0]?.message;
+    throw new FoirRequestError(
+      first ? `[foir] HTTP ${res.status} ${res.statusText}: ${first}` : `[foir] HTTP ${res.status} ${res.statusText}`,
+      { status: res.status, graphQLErrors: errors }
+    );
+  }
+  const json = await res.json();
+  return readFoirEnvelope(json);
+}
+async function readErrorEnvelope(res) {
+  let errors;
+  try {
+    const body = await res.json();
+    errors = body.errors;
+  } catch {
+    errors = void 0;
+  }
+  const headerRetryMs = readFoirRetryAfterMs(res.headers);
+  if (headerRetryMs === void 0) return errors;
+  const seconds = Math.round(headerRetryMs / 1e3);
+  if (!errors?.length) {
+    return [
+      {
+        message: res.statusText || `HTTP ${res.status}`,
+        extensions: { code: "RATE_LIMITED", retryAfter: seconds }
+      }
+    ];
+  }
+  if (errors[0].extensions?.retryAfter === void 0) {
+    errors[0] = {
+      ...errors[0],
+      extensions: { ...errors[0].extensions, retryAfter: seconds }
+    };
+  }
+  return errors;
+}
+async function isSharedRefusal(res) {
+  if (res.ok) return false;
+  try {
+    const body = await res.clone().json();
+    return body.errors?.some((e) => e.extensions?.code === NOT_SHAREABLE) ?? false;
+  } catch {
+    return false;
+  }
+}
+async function isPersistedQueryMiss(res) {
+  try {
+    const body = await res.clone().json();
+    return body.errors?.some(
+      (e) => e.extensions?.code === PERSISTED_QUERY_NOT_FOUND
+    ) ?? false;
+  } catch {
+    return false;
+  }
+}
+
 // src/graphql/content-client.ts
 function createFoirContentClient(config) {
   return {
     async request(document, variables, options) {
-      const bound = config.getToken ? await config.getToken() : null;
-      return foirRequest(config.env, document, variables, {
-        ...options,
-        bearerToken: options?.bearerToken ?? bound ?? void 0
-      });
+      return withFoirRetry(async () => {
+        const bound = config.getToken ? await config.getToken() : null;
+        return foirRequest(config.env, document, variables, {
+          ...options,
+          bearerToken: options?.bearerToken ?? bound ?? void 0,
+          onRateLimit: options?.onRateLimit ?? config.onRateLimit
+        });
+      }, config.retry);
     }
   };
 }
@@ -91,5 +328,12 @@ export {
   absolutiseFoirMediaUrl,
   createFoirContentClient,
   foirRequest,
-  isFoirPreview
+  foirRetryDelayMs,
+  isFoirForbidden,
+  isFoirNotFound,
+  isFoirPreview,
+  isFoirRateLimited,
+  isFoirUnauthenticated,
+  readFoirRateLimit,
+  withFoirRetry
 };

package/dist/codegen/block-registry.d.ts

@@ -1,6 +1,3 @@
-import { GraphQLSchema } from 'graphql';
-import { B as BlockPluginConfig } from '../shared-DkWlEd2Z.js';
-
 /**
  * `@foir/sdk/codegen/block-registry` — a graphql-codegen plugin.
  *
@@ -16,12 +13,11 @@ import { B as BlockPluginConfig } from '../shared-DkWlEd2Z.js';
  * types from the codegen output (`./graphql`) and `BlockComponent` from
  * `@foir/sdk/content`, so it pairs directly with `createContentRenderer`.
  */
-
-interface BlockRegistryConfig extends BlockPluginConfig {
+import type { GraphQLSchema } from 'graphql';
+import { type BlockPluginConfig } from './shared';
+export interface BlockRegistryConfig extends BlockPluginConfig {
     /** Name of the generated registry type. Default `BlockRegistry`. */
     registryName?: string;
 }
 /** graphql-codegen plugin entrypoint. */
-declare const plugin: (schema: GraphQLSchema, _documents: unknown, config?: BlockRegistryConfig) => string;
-
-export { type BlockRegistryConfig, plugin };
+export declare const plugin: (schema: GraphQLSchema, _documents: unknown, config?: BlockRegistryConfig) => string;

package/dist/codegen/block-scaffold.d.ts

@@ -1,6 +1,3 @@
-import { GraphQLSchema } from 'graphql';
-import { B as BlockPluginConfig } from '../shared-DkWlEd2Z.js';
-
 /**
  * `@foir/sdk/codegen/block-scaffold` — a one-shot graphql-codegen plugin.
  *
@@ -13,8 +10,9 @@ import { B as BlockPluginConfig } from '../shared-DkWlEd2Z.js';
  * in. Adding a new block type later surfaces as a compile error on
  * `blockRegistry` (via the regenerated `BlockRegistry` type), not here.
  */
-
-interface BlockScaffoldConfig extends BlockPluginConfig {
+import type { GraphQLSchema } from 'graphql';
+import { type BlockPluginConfig } from './shared';
+export interface BlockScaffoldConfig extends BlockPluginConfig {
     /** Import path for the generated registry type. Default `./block-registry`. */
     registryImport?: string;
     /** Render-context type name threaded to every component. Default `unknown`. */
@@ -23,6 +21,4 @@ interface BlockScaffoldConfig extends BlockPluginConfig {
     ctxImport?: string;
 }
 /** graphql-codegen plugin entrypoint. */
-declare const plugin: (schema: GraphQLSchema, _documents: unknown, config?: BlockScaffoldConfig) => string;
-
-export { type BlockScaffoldConfig, plugin };
+export declare const plugin: (schema: GraphQLSchema, _documents: unknown, config?: BlockScaffoldConfig) => string;

package/dist/codegen/index.d.ts

@@ -1,65 +1,11 @@
-import { CodegenConfig } from '@graphql-codegen/cli';
-export { B as BlockPluginConfig } from '../shared-DkWlEd2Z.js';
-
 /**
- * `@foir/sdk/codegen` — the Foir graphql-codegen preset.
+ * `@foir/sdk/codegen` — Foir graphql-codegen preset + block-registry plugin.
  *
- * `foirCodegen()` returns a complete `@graphql-codegen/client-preset` config so
- * a consumer's `codegen.ts` is ~3 lines instead of the ~109 every storefront
- * hand-copies. It standardizes the Foir conventions (custom scalars,
- * `enumValues: 'keep'`, the `X-Foir-Schema-Channel: draft` introspection header)
- * AND wires the block-registry plugin so the exhaustive `BlockRegistry` type is
- * regenerated alongside the typed documents.
- *
- * `foirScaffold()` is the separate one-shot that writes the ContentRenderer
- * shell (run once; the dev owns the output).
- */
-
-interface FoirCodegenOptions {
-    /** Foir public API GraphQL endpoint. */
-    apiUrl: string;
-    /**
-     * Public (`pk_`) API key. Reads the published schema. Used as the fallback
-     * when no preview key is set.
-     */
-    apiKey?: string;
-    /**
-     * Preview (`sk_`) key with `drafts:read`. Reads the DRAFT schema channel so
-     * freshly pushed (un-promoted) model changes are visible to codegen.
-     * Strongly preferred — a `pk_` key only sees the published schema.
-     */
-    previewKey?: string;
-    /** Output directory for the generated client types. Default `./app/gql/foir/`. */
-    outputDir?: string;
-    /** Operation document glob(s). Default `app/graphql/foir/**\/*.graphql`. */
-    documents?: string | string[];
-    /** Block union name(s) for the registry. Default `['Block']`. */
-    blockUnions?: string[];
-    /** Generated registry file path. Default `<outputDir>block-registry.ts`. */
-    registryFile?: string;
-    /** Extra/override custom scalars merged onto the Foir defaults. */
-    scalars?: Record<string, unknown>;
-}
-/**
- * Build the continuous Foir codegen config: typed documents + the exhaustive
- * block registry. Drop it into `codegen.ts` and run `graphql-codegen`.
- */
-declare function foirCodegen(options: FoirCodegenOptions): CodegenConfig;
-interface FoirScaffoldOptions extends FoirCodegenOptions {
-    /** Output path for the scaffold. Default `<outputDir>ContentRenderer.tsx`. */
-    scaffoldFile?: string;
-    /** Render-context type threaded to every block component. Default `unknown`. */
-    ctxType?: string;
-    /** Optional ctx-type import line, e.g. `import type { Ctx } from '~/ctx'`. */
-    ctxImport?: string;
-    /** Import path for the generated registry type. Default `./block-registry`. */
-    registryImport?: string;
-}
-/**
- * Build the one-shot scaffold config — writes a ContentRenderer shell with a
- * typed stub per block type. Run once (`graphql-codegen --config scaffold.ts`),
- * then own and implement the output.
+ * Build-time only. `@graphql-codegen/cli` + `@graphql-codegen/client-preset`
+ * are optional peer dependencies (the consumer's devDeps). The block-registry
+ * and block-scaffold plugins are wired by the preset and also available at
+ * `@foir/sdk/codegen/block-registry` / `@foir/sdk/codegen/block-scaffold`.
  */
-declare function foirScaffold(options: FoirScaffoldOptions): CodegenConfig;
-
-export { type FoirCodegenOptions, type FoirScaffoldOptions, foirCodegen, foirScaffold };
+export { foirCodegen, foirScaffold } from './preset';
+export type { FoirCodegenOptions, FoirScaffoldOptions } from './preset';
+export type { BlockPluginConfig } from './shared';

package/dist/codegen/preset.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `@foir/sdk/codegen` — the Foir graphql-codegen preset.
+ *
+ * `foirCodegen()` returns a complete `@graphql-codegen/client-preset` config so
+ * a consumer's `codegen.ts` is ~3 lines instead of the ~109 every storefront
+ * hand-copies. It standardizes the Foir conventions (custom scalars,
+ * `enumValues: 'keep'`, the `X-Foir-Schema-Channel: draft` introspection header)
+ * AND wires the block-registry plugin so the exhaustive `BlockRegistry` type is
+ * regenerated alongside the typed documents.
+ *
+ * `foirScaffold()` is the separate one-shot that writes the ContentRenderer
+ * shell (run once; the dev owns the output).
+ */
+import type { CodegenConfig } from '@graphql-codegen/cli';
+export interface FoirCodegenOptions {
+    /** Foir public API GraphQL endpoint. */
+    apiUrl: string;
+    /**
+     * Public (`pk_`) API key. Reads the published schema. Used as the fallback
+     * when no preview key is set.
+     */
+    apiKey?: string;
+    /**
+     * Preview (`sk_`) key with `drafts:read`. Reads the DRAFT schema channel so
+     * freshly pushed (un-promoted) model changes are visible to codegen.
+     * Strongly preferred — a `pk_` key only sees the published schema.
+     */
+    previewKey?: string;
+    /** Output directory for the generated client types. Default `./app/gql/foir/`. */
+    outputDir?: string;
+    /** Operation document glob(s). Default `app/graphql/foir/**\/*.graphql`. */
+    documents?: string | string[];
+    /** Block union name(s) for the registry. Default `['Block']`. */
+    blockUnions?: string[];
+    /** Generated registry file path. Default `<outputDir>block-registry.ts`. */
+    registryFile?: string;
+    /** Extra/override custom scalars merged onto the Foir defaults. */
+    scalars?: Record<string, unknown>;
+}
+/**
+ * Build the continuous Foir codegen config: typed documents + the exhaustive
+ * block registry. Drop it into `codegen.ts` and run `graphql-codegen`.
+ */
+export declare function foirCodegen(options: FoirCodegenOptions): CodegenConfig;
+export interface FoirScaffoldOptions extends FoirCodegenOptions {
+    /** Output path for the scaffold. Default `<outputDir>ContentRenderer.tsx`. */
+    scaffoldFile?: string;
+    /** Render-context type threaded to every block component. Default `unknown`. */
+    ctxType?: string;
+    /** Optional ctx-type import line, e.g. `import type { Ctx } from '~/ctx'`. */
+    ctxImport?: string;
+    /** Import path for the generated registry type. Default `./block-registry`. */
+    registryImport?: string;
+}
+/**
+ * Build the one-shot scaffold config — writes a ContentRenderer shell with a
+ * typed stub per block type. Run once (`graphql-codegen --config scaffold.ts`),
+ * then own and implement the output.
+ */
+export declare function foirScaffold(options: FoirScaffoldOptions): CodegenConfig;

package/dist/codegen/shared.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared introspection helpers for the Foir codegen plugins.
+ */
+import { type GraphQLSchema } from 'graphql';
+export interface BlockPluginConfig {
+    /**
+     * Union type name(s) to collect block members from. Defaults to `['Block']`
+     * (the canonical Foir block union). A project with a distinct content-field
+     * segment union lists it here too.
+     */
+    unions?: string[];
+    /** Import path for the codegen-generated types. Default `./graphql`. */
+    graphqlImport?: string;
+    /** Import path for the SDK content primitives. Default `@foir/sdk/content`. */
+    sdkImport?: string;
+}
+export declare const DEFAULT_UNIONS: string[];
+export declare const DEFAULT_GRAPHQL_IMPORT = "./graphql";
+export declare const DEFAULT_SDK_IMPORT = "@foir/sdk/content";
+/**
+ * Collect the deduped, sorted set of object-type member names across the named
+ * union(s). Throws when none of the unions resolve to members — that almost
+ * always means a misconfigured union name or a schema that hasn't been pushed.
+ */
+export declare function collectBlockMembers(schema: GraphQLSchema, unionNames: string[]): string[];

package/dist/components/EditorProvider.d.ts

@@ -0,0 +1,36 @@
+/**
+ * EditorProvider - React context provider for Foir editor iframes.
+ *
+ * Wraps your editor root to handle postMessage lifecycle, theme sync,
+ * and provide the platform client via context.
+ */
+import { type ReactNode } from 'react';
+import type { EditorInit, EditorContextValue, LocaleContext } from '../types';
+export declare const EditorContext: import("react").Context<EditorContextValue | null>;
+export 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;
+}
+export declare function EditorProvider({ children, parentOrigin: parentOriginProp, apiUrl: apiUrlProp, onInit, onValuesChanged, onVariantChanged, onSaveResult, onPublishResult, onThemeChanged, onSelectionChanged, onLocaleChanged, }: EditorProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/content/content-renderer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * createContentRenderer — the generic content-dispatch primitive.
+ *
+ * It does NOT know any concrete block types. Given a registry that maps each
+ * block `__typename` to a component, it renders a `flexible` field's block
+ * array: looks each block up by `__typename`, renders unknown types as null,
+ * keys by the block `_id`, assigns LCP `priority` to the first block that
+ * actually renders, and threads a consumer-defined `Ctx` to every component.
+ *
+ * The "switch" is a typed object lookup. Exhaustiveness is enforced where the
+ * registry is BUILT — against the exhaustive `BlockRegistry` type the codegen
+ * plugin (EID-92) generates per project, so omitting a block type is a compile
+ * error there, not a runtime surprise here. The consumer can supply different
+ * registries per surface (e.g. web vs email).
+ */
+import { type ReactNode } from 'react';
+/** Minimal shape every block in a `flexible` field carries. */
+export interface BlockLike {
+    __typename: string;
+    _id?: string | null;
+}
+/** Props a block component receives from the content renderer. */
+export interface BlockComponentProps<TBlock, TCtx = unknown> {
+    block: TBlock;
+    /** Consumer-defined render context (host product, locale, etc.). */
+    ctx: TCtx;
+    /** True only for the first block that renders — the LCP candidate. */
+    priority: boolean;
+}
+/** A component that renders one block type. */
+export type BlockComponent<TBlock, TCtx = unknown> = (props: BlockComponentProps<TBlock, TCtx>) => ReactNode;
+/**
+ * A registry mapping `__typename` → block component. In practice this is the
+ * exhaustive `BlockRegistry` type the codegen plugin emits for the project;
+ * here it's the structural lower bound the renderer needs.
+ */
+export type BlockRegistry<TCtx = unknown> = Record<string, BlockComponent<any, TCtx>>;
+export interface ContentRendererProps<TCtx> {
+    blocks: readonly BlockLike[] | null | undefined;
+    /** Consumer-defined context passed to every block component. */
+    ctx: TCtx;
+}
+/**
+ * Build a `<ContentRenderer>` bound to a block registry. Returns a component
+ * that takes the `flexible` field's `blocks` array plus a `ctx`.
+ */
+export declare function createContentRenderer<TCtx = unknown>(registry: BlockRegistry<TCtx>): (props: ContentRendererProps<TCtx>) => ReactNode;

package/dist/content/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@foir/sdk/content` — generic content-rendering primitives.
+ *
+ * Ships ONLY the framework-agnostic primitives: the block-dispatch renderer
+ * and a Lexical richtext renderer with injected typography tokens. Concrete
+ * block components, host/Shopify context, and layout systems stay app-side.
+ * `react` is a peer dependency.
+ */
+export { createContentRenderer } from './content-renderer';
+export type { BlockLike, BlockComponent, BlockComponentProps, BlockRegistry, ContentRendererProps, } from './content-renderer';
+export { RichTextRenderer, RichTextTypographyProvider, useRichTextTypography, } from './richtext';
+export type { RichTextRendererProps, TypographyToken, } from './richtext';