@foir/sdk 0.4.0 → 0.5.0

package/dist/client.d.ts

@@ -80,4 +80,56 @@ interface FoirRequestOptions {
 }
 declare function foirRequest<TData, TVariables>(env: FoirEnv, document: TypedDocumentNode<TData, TVariables>, variables?: TVariables, options?: FoirRequestOptions): Promise<TData>;
 
-export { FOIR_CDN_BASE, type FoirEnv, FoirRequestError, type FoirRequestOptions, absolutiseFoirMediaUrl, foirRequest, isFoirPreview };
+/**
+ * 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.
+ */
+
+/**
+ * Supplies the current customer bearer. Sync or async so consumers can read a
+ * cookie session (Hydrogen/Remix), a KV store, an in-memory value, etc. Returns
+ * the token when signed in, or `null`/`undefined` when signed out.
+ */
+type FoirTokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
+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;
+}
+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.
+ */
+declare function createFoirContentClient(config: FoirContentClientConfig): FoirContentClient;
+
+export { FOIR_CDN_BASE, type FoirContentClient, type FoirContentClientConfig, type FoirEnv, FoirRequestError, type FoirRequestOptions, type FoirTokenProvider, absolutiseFoirMediaUrl, createFoirContentClient, foirRequest, isFoirPreview };

package/dist/client.js

@@ -72,10 +72,24 @@ async function foirRequest(env, document, variables, options) {
   }
   return json.data;
 }
+
+// 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
+      });
+    }
+  };
+}
 export {
   FOIR_CDN_BASE,
   FoirRequestError,
   absolutiseFoirMediaUrl,
+  createFoirContentClient,
   foirRequest,
   isFoirPreview
 };

package/dist/server.d.ts

@@ -519,8 +519,8 @@ interface CallbackClient<TResult = unknown> {
  * payload structure on every call.
  *
  * `signingSecret` lives on the extension (set as `FOIR_SIGNING_SECRET` or
- * equivalent env var). The CLI publishes it during `foir push` so it's
- * available before any callback runs — see foir-cli writeConfigCredential.
+ * equivalent env var). `foir push` writes it there from the project's
+ * signing secret, so it's available before any callback runs.
  *
  * `fetch` is overridable for testability and to support runtimes (CF
  * Workers, Node) where `fetch` may not be the global.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {