@foir/sdk 0.4.0 → 0.7.0

package/dist/data.js

@@ -0,0 +1,309 @@
+// src/transport/foir-http.ts
+function isFoirPreview(env) {
+  return env.FOIR_PREVIEW === "true";
+}
+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. */
+  status;
+  /** GraphQL errors, when the request failed with a no-data error envelope. */
+  graphQLErrors;
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "FoirRequestError";
+    this.cause = options?.cause;
+    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;
+  }
+};
+function buildFoirHeaders(input) {
+  const headers = {
+    "Content-Type": "application/json",
+    "x-api-key": input.apiKey
+  };
+  if (input.draftChannel) {
+    headers["X-Foir-Schema-Channel"] = "draft";
+  }
+  if (input.bearerToken) {
+    headers["Authorization"] = `Bearer ${input.bearerToken}`;
+  }
+  if (input.extra) {
+    for (const [key, value] of Object.entries(input.extra)) {
+      headers[key] = value;
+    }
+  }
+  return headers;
+}
+function readFoirEnvelope(json) {
+  if (json.errors?.length) {
+    const msg = json.errors.map((e) => e.message).join("; ");
+    if (json.data) {
+      console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
+    } else {
+      throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
+        graphQLErrors: json.errors
+      });
+    }
+  }
+  if (!json.data) {
+    throw new FoirRequestError("[foir] empty GraphQL response");
+  }
+  return json.data;
+}
+
+// src/data/transport.ts
+function foirDataEndpoint(apiUrl, path) {
+  const base = apiUrl.trim().replace(/\/+$/, "").replace(/\/graphql$/i, "");
+  if (!base) {
+    throw new FoirRequestError("[foir] apiUrl is empty \u2014 pass the Foir API origin");
+  }
+  return base + path;
+}
+async function resolveBearerToken(config) {
+  const source = config.bearerToken;
+  if (typeof source === "function") return await source() ?? void 0;
+  return source ?? void 0;
+}
+async function readErrorBody(res) {
+  try {
+    const json = await res.json();
+    return json?.errors?.length ? json.errors : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function postFoirOp(config, body) {
+  const url = foirDataEndpoint(config.apiUrl, "/v1/query");
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const headers = buildFoirHeaders({
+    apiKey: config.apiKey,
+    draftChannel: config.channel === "draft",
+    bearerToken: await resolveBearerToken(config),
+    extra: config.headers
+  });
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      ...config.requestInit
+    });
+  } catch (err) {
+    throw new FoirRequestError("[foir] network error", { cause: err });
+  }
+  if (!res.ok) {
+    const errors = await readErrorBody(res);
+    const detail = errors ? `: ${errors.map((e) => e.message).join("; ")}` : "";
+    throw new FoirRequestError(`[foir] HTTP ${res.status} ${res.statusText}${detail}`, {
+      status: res.status,
+      graphQLErrors: errors
+    });
+  }
+  const json = await res.json();
+  const data = readFoirEnvelope(json);
+  const roots = Object.keys(data);
+  if (roots.length !== 1) {
+    throw new FoirRequestError(
+      `[foir] expected exactly one root field in the /v1/query response, got ${roots.length}` + (roots.length ? ` (${roots.join(", ")})` : "")
+    );
+  }
+  return data[roots[0]];
+}
+
+// src/data/manifest.ts
+async function fetchFoirManifest(config) {
+  const url = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+  const doFetch = config.fetch ?? globalThis.fetch;
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "GET",
+      headers: buildFoirHeaders({
+        apiKey: config.apiKey,
+        draftChannel: config.channel === "draft",
+        bearerToken: await resolveBearerToken(config),
+        extra: config.headers
+      }),
+      ...config.requestInit
+    });
+  } catch (err) {
+    throw new FoirRequestError("[foir] network error", { cause: err });
+  }
+  if (!res.ok) {
+    throw new FoirRequestError(
+      `[foir] GET /v1/manifest failed: HTTP ${res.status} ${res.statusText}`,
+      { status: res.status }
+    );
+  }
+  return await res.json();
+}
+
+// src/data/client.ts
+var NON_MODEL_PROPS = /* @__PURE__ */ new Set([
+  "then",
+  "catch",
+  "finally",
+  "toJSON",
+  "toString",
+  "valueOf",
+  "constructor",
+  "inspect",
+  "asymmetricMatch",
+  "$$typeof",
+  "_isMockFunction",
+  "nodeType"
+]);
+function selectionPaths(value, verb, prefix = "") {
+  if (Array.isArray(value)) return value;
+  if (!value || typeof value !== "object") return [];
+  const out = [];
+  for (const [key, child] of Object.entries(value)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (child === true) {
+      out.push(path);
+      continue;
+    }
+    if (child && typeof child === "object" && verb in child) {
+      out.push(...selectionPaths(child[verb], verb, path));
+    }
+  }
+  return out;
+}
+function splitQuery(query) {
+  const args = {};
+  let include;
+  let omit;
+  let pick;
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value === void 0) continue;
+    if (key === "include") {
+      include = value;
+    } else if (key === "omit") {
+      omit = selectionPaths(value, "omit");
+    } else if (key === "pick") {
+      pick = selectionPaths(value, "pick");
+    } else {
+      args[key] = value;
+    }
+  }
+  return { args, include, omit, pick };
+}
+function createFoirClient(config) {
+  if (!config?.apiUrl || !config?.apiKey) {
+    throw new Error("[foir] createFoirClient needs both apiUrl and apiKey");
+  }
+  let driftChecked = false;
+  const maybeCheckDrift = () => {
+    const generated = config.schemaVersion;
+    if (driftChecked) return;
+    if (generated === void 0) return;
+    if (config.checkSchemaDrift === false) return;
+    driftChecked = true;
+    void fetchFoirManifest(config).then((manifest) => {
+      if (manifest.schemaVersion === generated) return;
+      const drift = {
+        generated,
+        server: manifest.schemaVersion,
+        channel: manifest.channel
+      };
+      if (config.onSchemaDrift) {
+        config.onSchemaDrift(drift);
+        return;
+      }
+      console.warn(
+        `[foir] schema drift: types were generated from schemaVersion ${drift.generated}, the server is serving ${drift.server} (${drift.channel}). Re-run \`foir types\` \u2014 new models and fields will be missing, and removed ones will still type-check.`
+      );
+    }).catch(() => {
+    });
+  };
+  const run = async (body) => {
+    const result = await postFoirOp(config, body);
+    maybeCheckDrift();
+    return result;
+  };
+  const opProxy = (address) => new Proxy({}, {
+    get(_target, op) {
+      if (typeof op !== "string" || NON_MODEL_PROPS.has(op)) return void 0;
+      return (query) => {
+        const { args, include, omit, pick } = splitQuery(query);
+        return run({ ...address, op, args, include, omit, pick });
+      };
+    }
+  });
+  const nsProxy = new Proxy({}, {
+    get(_target, namespace) {
+      if (typeof namespace !== "string" || NON_MODEL_PROPS.has(namespace)) return void 0;
+      return opProxy({ namespace });
+    }
+  });
+  const raw = (op) => run(op);
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (prop === "ns") return nsProxy;
+      if (prop === "raw") return raw;
+      if (typeof prop !== "string" || NON_MODEL_PROPS.has(prop)) return void 0;
+      return opProxy({ model: prop });
+    }
+  });
+}
+function createFoirClientFromEnv(env, overrides) {
+  const apiKey = resolveFoirApiKey(env);
+  if (!env.PLATFORM_API_URL || !apiKey) {
+    throw new FoirRequestError(
+      "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
+    );
+  }
+  return createFoirClient({
+    ...overrides,
+    apiUrl: env.PLATFORM_API_URL,
+    apiKey,
+    channel: isFoirPreview(env) ? "draft" : "published"
+  });
+}
+export {
+  FoirRequestError,
+  createFoirClient,
+  createFoirClientFromEnv,
+  fetchFoirManifest,
+  foirDataEndpoint
+};

package/dist/graphql/cdn-route.d.ts

@@ -0,0 +1,42 @@
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { type FoirEnv } from '../transport/foir-http';
+/**
+ * Whether this read can be served by the shared endpoint.
+ *
+ * These mirror the conditions the server refuses on, so a request that would be
+ * turned away is not sent there in the first place. The server is still the
+ * authority — it refuses rather than falling back, and `foirRequest` retries on
+ * `/graphql` when it does — but every condition checked here is one round trip
+ * saved.
+ */
+export declare function isCdnEligible(env: FoirEnv, documentText: string, bearerToken?: string): boolean;
+/**
+ * Build the shared-endpoint URL for a read.
+ *
+ * The credential goes in the URL deliberately: a shared cache keys on the URL
+ * alone, so a key that rode only in a header would let two callers with
+ * different reach collide on one entry and be served each other's body.
+ */
+export declare function buildCdnUrl(endpoint: string, apiKey: string, hash: string, variables?: unknown): string;
+/** The APQ handshake object, in Apollo's shape because every client uses it. */
+export declare function persistedQueryExtension(hash: string): {
+    persistedQuery: {
+        version: number;
+        sha256Hash: string;
+    };
+};
+/**
+ * SHA-256 of the document text, hex encoded — the identity a persisted query is
+ * stored and retrieved under.
+ *
+ * Web Crypto rather than a bundled implementation: it is present in every
+ * runtime this SDK targets (workers, edge, Node 18+) and adds nothing to the
+ * caller's bundle.
+ */
+export declare function documentHash(documentText: string): Promise<string>;
+/** The code the server answers with when it has never seen this hash. */
+export declare const PERSISTED_QUERY_NOT_FOUND = "PERSISTED_QUERY_NOT_FOUND";
+/** The code the shared endpoint refuses with, so a caller knows to retry. */
+export declare const NOT_SHAREABLE = "NOT_SHAREABLE";
+/** Print a document once, so eligibility and the URL agree on the same text. */
+export declare function printDocument<TData, TVariables>(document: TypedDocumentNode<TData, TVariables>): string;

package/dist/graphql/client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@foir/sdk/client` — client-agnostic GraphQL transport for SSR/edge loaders.
+ *
+ * A thin auth transport, not a GraphQL client: it carries the Foir-specific
+ * `x-api-key` + preview schema channel and runs typed documents via `fetch`.
+ * Consumers that bring their own GraphQL client (Apollo/urql/react-query) use
+ * the generated `TypedDocumentNode`s directly and replicate those two headers.
+ */
+export { foirRequest, isFoirPreview, absolutiseFoirMediaUrl, FOIR_CDN_BASE, FoirRequestError, } from './foir-request';
+export type { FoirEnv, FoirRequestOptions } from './foir-request';
+/**
+ * Failure classification. Branch on these rather than on `err.message`: the
+ * codes are a stable contract, the wording is not.
+ *
+ * The one worth knowing about is `isFoirRateLimited`. It is the only 4xx that
+ * clears on its own, and a client that lumps it in with the rest fails every
+ * read for as long as the key stays saturated — which looks, from the outside,
+ * exactly like a site with no content.
+ */
+export { isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, } from './foir-request';
+export type { FoirErrorCode, FoirErrorExtensions, FoirGraphQLErrorItem, FoirRateLimitSnapshot, } from './foir-request';
+/**
+ * Retry. `createFoirContentClient` applies this for you; these are exported for
+ * a caller running its own loop, so both use one definition of "worth retrying"
+ * rather than two that disagree about the 429.
+ */
+export { withFoirRetry, foirRetryDelayMs } from './foir-request';
+export type { FoirRetryPolicy } from './foir-request';
+export { createFoirContentClient } from './content-client';
+export type { FoirContentClient, FoirContentClientConfig, FoirTokenProvider, } from './content-client';

package/dist/graphql/content-client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Session-bound content client — forwards the customer bearer on every read
+ * when one is available, so auth/segment-targeted variants and customer-scoped
+ * records resolve out of the box, with no per-query wiring to forget.
+ *
+ * Resolution keys off the request's principal (see the platform's two-gate
+ * model): the `x-api-key` alone resolves the *anonymous baseline*
+ * (`context.authStatus = ""`); adding the customer bearer resolves the request
+ * as that customer (`context.authStatus = "authenticated"`, `customer_id` set).
+ *
+ * Caching: an api-key-only read is identical for every anonymous visitor and is
+ * shared-cacheable; a bearer-bearing read resolves per-customer and is not.
+ * Because the bearer only exists once a customer signs in, anonymous traffic
+ * keeps hitting the shared-cacheable baseline — only signed-in reads become
+ * per-customer. Bind this client wherever content is personalized (for most
+ * apps, everywhere the customer may be signed in) and use plain `foirRequest`
+ * for reads that must stay anonymous regardless of session.
+ */
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import type { FoirEnv, FoirRequestOptions } from './foir-request';
+import { type FoirRetryPolicy } from '../transport/retry';
+import type { FoirRateLimitSnapshot } from '../transport/foir-http';
+export type { FoirTokenProvider } from '../transport/foir-http';
+import type { FoirTokenProvider } from '../transport/foir-http';
+export interface FoirContentClientConfig {
+    env: FoirEnv;
+    /**
+     * Resolves the current customer bearer before every request. When it yields a
+     * token the token is forwarded, so `authStatus`/segment targeting and
+     * customer-scoped records resolve as that customer; when it yields
+     * null/undefined the read hits the anonymous baseline. Omit for a client that
+     * is always anonymous (equivalent to calling `foirRequest` directly).
+     */
+    getToken?: FoirTokenProvider;
+    /**
+     * Retry policy for transient failures — no response, 5xx, and 429.
+     *
+     * ON BY DEFAULT, which is the point of it being here. Retry that has to be
+     * opted into is retry each integrator writes for themselves, and the one
+     * detail they get wrong is the 429: it looks like the permanent 4xx family it
+     * sits in, and it is the only failure in that family that clears on its own.
+     * Pass `{ attempts: 1 }` to turn it off.
+     */
+    retry?: FoirRetryPolicy;
+    /**
+     * Called with the `X-RateLimit-*` headers of every response. Wire it to your
+     * logger and you will see a key approaching its ceiling instead of finding
+     * out when it hits one.
+     */
+    onRateLimit?: (snapshot: FoirRateLimitSnapshot | undefined) => void;
+}
+export interface FoirContentClient {
+    /**
+     * Run a typed document, forwarding the bound customer bearer when available.
+     * An explicit `options.bearerToken` still wins, so a single call can override
+     * the bound token (or force anonymous by passing `undefined` — the bound
+     * token only fills in when `options.bearerToken` is not supplied).
+     */
+    request<TData, TVariables>(document: TypedDocumentNode<TData, TVariables>, variables?: TVariables, options?: FoirRequestOptions): Promise<TData>;
+}
+/**
+ * Create a {@link FoirContentClient} bound to an env + token source. Every
+ * `request` forwards the customer bearer when `getToken` yields one, upgrading
+ * that read from the anonymous baseline to the signed-in customer.
+ */
+export declare function createFoirContentClient(config: FoirContentClientConfig): FoirContentClient;

package/dist/graphql/foir-request.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Foir GraphQL client — a single typed fetch wrapper for SSR/edge loaders.
+ *
+ * No GraphQL client (Apollo/urql) required: the Foir public API is a plain
+ * `POST` with an `x-api-key` header, and the dominant consumers (Hydrogen on
+ * Oxygen, React Router loaders, TanStack Start on CF Workers) fetch in
+ * server-only loaders and render — so Apollo's `InMemoryCache`/`useQuery`
+ * reactivity is dead weight, and a shared cache on a stateless multi-tenant
+ * edge worker is a cross-tenant hazard. This helper carries only the
+ * Foir-specific transport concerns (auth header, preview schema channel,
+ * error shape). Consumers on a GraphQL client (Apollo / urql / react-query /
+ * graphql-request) use the generated `TypedDocumentNode`s directly with their
+ * own client and replicate the two Foir-specific headers below — the
+ * `x-api-key` and, in preview, `X-Foir-Schema-Channel: draft`.
+ *
+ * Deduplicates the hand-copied `lib/foir/client.ts` that shipped identically
+ * across the Foir storefronts.
+ *
+ * The transport concerns themselves now live in `../transport/foir-http`, which
+ * has no `graphql` import, so `@foir/sdk/data` can reuse them without dragging
+ * `graphql` into a storefront bundle. Only `print` stayed here. Everything that
+ * module owns is re-exported below, unchanged, so this file's public surface is
+ * exactly what it always was.
+ */
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { type FoirEnv, type FoirRequestOptions } from '../transport/foir-http';
+export { FoirRequestError, isFoirPreview, isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, type FoirEnv, type FoirErrorCode, type FoirErrorExtensions, type FoirGraphQLErrorItem, type FoirRateLimitSnapshot, type FoirRequestOptions, } from '../transport/foir-http';
+export { withFoirRetry, foirRetryDelayMs, type FoirRetryPolicy, } from '../transport/retry';
+/** Default Foir CDN origin used to absolutise relative media URLs. */
+export declare const FOIR_CDN_BASE = "https://cdn.foir.dev/";
+/**
+ * Foir returns `hlsManifestUrl` as a relative path while every other media
+ * URL is absolute. Prefix relative paths with the CDN host so the browser
+ * doesn't request them from the consumer's own origin. Already-absolute URLs
+ * pass through untouched. `cdnBase` is overridable for non-default CDN hosts.
+ */
+export declare function absolutiseFoirMediaUrl(url: string | null | undefined, cdnBase?: string): string | undefined;
+/**
+ * Execute a typed GraphQL document against the Foir platform.
+ *
+ * Throws `FoirRequestError` on HTTP failure or GraphQL errors so the caller
+ * can decide whether to rethrow or fall back to local defaults. GraphQL can
+ * return partial data alongside errors; when data is present the errors are
+ * logged and the data returned (callers handle nulls), and we only throw when
+ * there's no data at all.
+ */
+export declare function foirRequest<TData, TVariables>(env: FoirEnv, document: TypedDocumentNode<TData, TVariables>, variables?: TVariables, options?: FoirRequestOptions): Promise<TData>;

package/dist/hooks/useAutoResize.d.ts

@@ -0,0 +1,22 @@
+export 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>;
+ * }
+ * ```
+ */
+export declare function useAutoResize(options?: UseAutoResizeOptions): (node: HTMLDivElement | null) => void;

package/dist/hooks/useEditor.d.ts

@@ -0,0 +1,16 @@
+import type { EditorContextValue } from '../types';
+/**
+ * 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>;
+ * }
+ * ```
+ */
+export declare function useEditor(): EditorContextValue;