@foir/sdk 0.9.0 → 0.11.0

package/dist/next/cacheTags.d.ts

@@ -0,0 +1,245 @@
+/**
+ * `@foir/sdk/next` — the bridge between Foir's own dependency graph and Next's
+ * cache tags.
+ *
+ * ## The idea, in one line
+ *
+ * The API already computes, for every cacheable response, the exact set of
+ * records and collections that response depends on — it has to, to invalidate
+ * its own cache. It ships that set on `Surrogate-Key`. And it already streams
+ * the change events that make those dependencies stale. **Nothing joined the
+ * two.** This module is the join: tags in on the read, `revalidateTag` out on
+ * the event.
+ *
+ * That is a materially different thing from what a client-side cache can do.
+ * Query-key conventions and normalised-cache heuristics both GUESS at which
+ * cached entries a change affects. Here the graph is computed by the process
+ * that actually resolved the query.
+ *
+ * ## Next is INJECTED, never imported
+ *
+ * Nothing in `@foir/sdk` imports from `next` or `next/*`, and this module keeps
+ * it that way: `cacheTag` and `revalidateTag` arrive as function arguments.
+ *
+ * That is not tidiness. `cacheTag` is `unstable_cacheTag` in Next 15, requires
+ * `experimental.useCache`, and may be renamed or gated differently in 16.
+ * Importing it would make the SDK's install and its type-check depend on a Next
+ * version and a feature flag; injecting it means the SDK inherits none of that
+ * instability, and a consumer on any Next version wires up whatever their
+ * version calls it.
+ *
+ * ```ts
+ * import { unstable_cacheTag as cacheTag } from 'next/cache';
+ * import { createFoirTaggingFetch } from '@foir/sdk/next';
+ *
+ * const foir = createFoirClient({
+ *   apiUrl, apiKey, generated,
+ *   fetch: createFoirTaggingFetch({ cacheTag }),
+ * });
+ *
+ * export async function getProducts() {
+ *   'use cache';
+ *   return foir.products.list();   // tags registered during the fetch
+ * }
+ * ```
+ *
+ * ## Why the fetch is wrapped rather than the transport changed
+ *
+ * `@foir/sdk/data`'s transport returns the parsed envelope and nothing else —
+ * no caller can reach a response header through it, on any path. The client
+ * config already accepts an injected `fetch`, so the bridge reads the headers
+ * there. The transport is a shared file on a lane several other changes are
+ * live in; this needs none of it.
+ */
+/**
+ * `Surrogate-Key` is the CDN's contract: every handle a purge might need,
+ * including records a response was SHAPED BY but did not show.
+ *
+ * That is the right input for a cache tag and the wrong one for a browser, and
+ * the distinction is why the API ships a second, narrower header for page
+ * JavaScript. A Next `use cache` entry is a SERVER-side cache, so it wants the
+ * wider set: an entry whose content was influenced by a record it filtered out
+ * still has to drop when that record changes.
+ */
+export declare const FOIR_SURROGATE_KEY_HEADER = "Surrogate-Key";
+/**
+ * Next's own limits, as of 15.5 (`NEXT_CACHE_TAG_MAX_ITEMS`,
+ * `NEXT_CACHE_TAG_MAX_LENGTH`).
+ *
+ * They are mirrored rather than imported for the same reason `cacheTag` is
+ * injected, and they are the reason {@link foirCacheTags} has a policy at all:
+ * Next's behaviour on exceeding either is a `console.warn` and a SILENT DROP of
+ * the excess. A dropped tag is not a smaller feature, it is an entry that can
+ * never be invalidated for the records whose tags went missing.
+ */
+export declare const FOIR_NEXT_TAG_MAX_ITEMS = 128;
+export declare const FOIR_NEXT_TAG_MAX_LENGTH = 256;
+/**
+ * The tag a response with NO dependency set is filed under.
+ *
+ * Some reads emit no `Surrogate-Key` at all — a draft-channel read, a preview
+ * selection, a `NO_CACHE` model, a client `no-store`, a traced read. Wrapping
+ * one of those in `use cache` stores an entry with ZERO tags, which is strictly
+ * worse than not caching it: nothing can ever invalidate it, and it goes on
+ * being served until Next's own time-based revalidation.
+ *
+ * Reporting an empty array would leave that to be noticed. This gives the entry
+ * one coarse handle instead, so a consumer that discovers the problem has a
+ * `revalidateTag(FOIR_UNTAGGED_TAG)` to reach for — and {@link FoirCacheTags}
+ * says `kind: 'untagged'` so it can be noticed before then.
+ */
+export declare const FOIR_UNTAGGED_TAG = "foir:untagged";
+/**
+ * The minimal header shape this module reads. Structural on purpose — a real
+ * `Headers` satisfies it, and so does a plain object wrapper — so the SDK does
+ * not depend on a particular fetch implementation's types.
+ */
+export interface FoirHeaderSource {
+    get(name: string): string | null | undefined;
+}
+/** A response's dependency set, after the cap policy has been applied. */
+export type FoirCacheTags = {
+    kind: 'tagged';
+    /** What to hand to `cacheTag`. Never empty. */
+    tags: string[];
+    /**
+     * True when the per-record tags were dropped in favour of the coarse ones
+     * — see {@link foirCacheTags} for why that is the safe direction.
+     */
+    coarse: boolean;
+    /** How many `rec:` tags the response actually carried, before any policy. */
+    recordCount: number;
+} | {
+    kind: 'untagged';
+    /** Always the single {@link FOIR_UNTAGGED_TAG}. */
+    tags: [typeof FOIR_UNTAGGED_TAG];
+    /**
+     * `no-surrogate-key` — the response carried no dependency set at all.
+     * `all-tags-unusable` — it carried one, and nothing in it survived Next's
+     * length limit. Two different problems: the first is a read that opted out
+     * of caching, the second is a schema whose tags Next cannot hold.
+     */
+    reason: 'no-surrogate-key' | 'all-tags-unusable';
+};
+/**
+ * Split `Surrogate-Key` into its tags: whitespace-separated, empties dropped,
+ * order preserved, duplicates removed.
+ *
+ * Returns `[]` when the header is absent — which is a real and load-bearing
+ * case, not a parse failure. Use {@link foirCacheTags} rather than this if you
+ * are about to cache something: it is the one that knows what an empty set
+ * means.
+ */
+export declare function readFoirCacheTags(headers: FoirHeaderSource): string[];
+export interface FoirCacheTagsOptions {
+    /** Defaults to Next's own {@link FOIR_NEXT_TAG_MAX_ITEMS}. */
+    maxTags?: number;
+    /** Defaults to Next's own {@link FOIR_NEXT_TAG_MAX_LENGTH}. */
+    maxTagLength?: number;
+}
+/**
+ * Apply the cap policy to a response's dependency set.
+ *
+ * ## The cap is a CORRECTNESS problem, not a limit
+ *
+ * A response carries one `rec:` tag per record, so a 100-item list is fine and a
+ * 200-item list is over Next's 128. Next's answer to that is a `console.warn`
+ * and a silent drop of the excess — so the records whose tags were dropped stay
+ * stale until the entry's own TTL, with nothing to say which ones they were.
+ *
+ * **This never truncates.** Over the cap, the per-record tags are dropped
+ * ENTIRELY and only the coarse ones are kept. The two failures are not
+ * symmetric: truncation loses invalidation for the dropped records permanently
+ * and silently, while falling back to `model:` / `lookup:` / `proj:`
+ * over-invalidates, which costs a refetch. A big list is exactly the entry a
+ * change is most likely to affect, so it is also the entry least able to afford
+ * a hole.
+ *
+ * A tag past the LENGTH cap is handled the same way, because Next drops it the
+ * same way: a `rec:` tag that will not fit escalates the whole set to coarse
+ * rather than leaving one record unreachable.
+ *
+ * And if even the coarse set will not fit — which needs a genuinely strange
+ * schema — the broadest tags win, `proj:` first.
+ */
+export declare function foirCacheTags(headers: FoirHeaderSource, options?: FoirCacheTagsOptions): FoirCacheTags;
+/** What {@link createFoirTaggingFetch} reports for each response it saw. */
+export interface FoirTaggingReport {
+    /** The tag decision for this response. */
+    tags: FoirCacheTags;
+    /**
+     * Whether `cacheTag` accepted them. False when the read happened OUTSIDE a
+     * `use cache` scope, which is normal and not an error — `cacheTag` throws
+     * there, nothing is being cached, and there is nothing to tag.
+     */
+    applied: boolean;
+    /** The error `cacheTag` threw, when it threw one. */
+    error?: unknown;
+}
+export interface FoirTaggingFetchOptions extends FoirCacheTagsOptions {
+    /** Next's `cacheTag` (`unstable_cacheTag` on 15.x). */
+    cacheTag: (...tags: string[]) => void;
+    /** Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Called once per response, after the attempt. The hook for the two cases
+     * worth knowing about — `tags.kind === 'untagged'` and `tags.coarse` — both of
+     * which are silent in Next itself.
+     */
+    onTags?: (report: FoirTaggingReport) => void;
+}
+/**
+ * Wrap a `fetch` so every Foir response registers its own cache tags.
+ *
+ * The response is returned untouched: this reads headers and calls `cacheTag`,
+ * and changes nothing about the body, the status, or how the transport parses
+ * it.
+ *
+ * `cacheTag` throwing is caught and reported rather than propagated, because the
+ * common cause is not a bug: it throws outside a `use cache` scope, and one
+ * client is used for both cached and uncached reads. A read that is not being
+ * cached has nothing to tag, and failing it over that would make this wrapper
+ * unusable on the same client as an ordinary read.
+ */
+export declare function createFoirTaggingFetch(options: FoirTaggingFetchOptions): typeof globalThis.fetch;
+/**
+ * The record-change event shape `recordChanged` delivers, narrowed to what the
+ * tag mapping reads.
+ */
+export interface FoirRecordChange {
+    recordId: string;
+    modelKey: string;
+    /** `created`, `updated`, `published`, `unpublished` or `deleted`. */
+    action: string;
+}
+/**
+ * The tags one record change invalidates.
+ *
+ * # ONE RULE, TWO CACHES
+ *
+ * This delegates to `@foir/sdk/live` rather than restating the mapping, and the
+ * delegation is the point. The same decision governs a Next server cache and a
+ * client-side query cache, and a second copy of it is the kind that drifts
+ * silently: if one side started treating a create as a `rec:`-only
+ * invalidation, its lists would stop seeing new records and nothing would
+ * error — no exception, no failed request, just a page that never updates.
+ *
+ * The rule itself, and why it is shaped this way, is documented at the source.
+ * In short: `updated` matches on the record so one edit does not refetch every
+ * list on the model, and everything else takes the model tag too because
+ * membership changed and a create belongs to no cached list yet.
+ */
+export declare function foirTagsForRecordEvent(event: FoirRecordChange): string[];
+/**
+ * Turn a record change into `revalidateTag` calls — the inverse of the read
+ * side, and the other half of the join.
+ *
+ * `revalidateTag` is injected for the same reason `cacheTag` is. Where the event
+ * reaches the server is the consumer's choice and deliberately not decided here:
+ * a route handler wired to a Foir operations webhook is the honest v1 (they are
+ * already Ed25519-signed and delivered from a durable outbox), and a
+ * server-held subscription is possible but puts a long-lived socket in a
+ * serverless runtime, which is a decision to take on purpose rather than to
+ * default into.
+ */
+export declare function revalidateFoirRecordEvent(event: FoirRecordChange, revalidateTag: (tag: string) => void): string[];

package/dist/next/index.d.ts

@@ -3,12 +3,19 @@
  * (the BFF pattern): an HttpOnly-cookie session adapter, server-side session
  * helpers, a provider-callback exchange, and a route-protection middleware.
  *
+ * It also carries the cache-tag bridge: a Foir read's own dependency set
+ * (`Surrogate-Key`) registered with Next's `cacheTag`, and a record-change event
+ * turned back into `revalidateTag` calls. `cacheTag` / `revalidateTag` are
+ * INJECTED there, never imported — see `./cacheTags` for why.
+ *
  * This is the server counterpart to `@foir/sdk/react`. `next` is a peer
  * dependency (for the middleware helper).
  */
 export { createFoirCookieAdapter, foirCookieName, } from './cookieAdapter';
 export type { FoirCookieStore, CookieAdapterOptions } from './cookieAdapter';
 export { getFoirSession, getFoirToken, foirSignOut, foirSignInWithPassword, foirRegisterWithPassword, foirSignInWithOtp, completeFoirProviderLogin, } from './session';
+export { readFoirCacheTags, foirCacheTags, createFoirTaggingFetch, foirTagsForRecordEvent, revalidateFoirRecordEvent, FOIR_SURROGATE_KEY_HEADER, FOIR_NEXT_TAG_MAX_ITEMS, FOIR_NEXT_TAG_MAX_LENGTH, FOIR_UNTAGGED_TAG, } from './cacheTags';
+export type { FoirHeaderSource, FoirCacheTags, FoirCacheTagsOptions, FoirTaggingReport, FoirTaggingFetchOptions, FoirRecordChange, } from './cacheTags';
 export { createFoirMiddleware } from './middleware';
 export type { FoirMiddlewareConfig, FoirMiddlewareRequest } from './middleware';
 export type { FoirCustomer, SessionAdapter } from '../auth';

package/dist/next.js

@@ -30,11 +30,30 @@ function isFoirPreview(env) {
 function resolveFoirApiKey(env) {
   return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
 }
+var MALFORMED_PRUNE_REASONS = /* @__PURE__ */ new Set([
+  "unknown_field",
+  "subselections_on_scalar",
+  "missing_subselections"
+]);
 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;
+  /**
+   * The `data` the server did return, when a STRICT read refused a partial
+   * response. Present only on that path: without it, opting into strictness
+   * would trade a silent wrong answer for a thrown one that discards the answer,
+   * and a caller that wants to log what it nearly rendered could not.
+   */
+  partialData;
+  /**
+   * The selections the server stripped, when the refusal was a pruned document
+   * rather than a partial error. Same purpose as `partialData`: a caller that
+   * wants to log what it nearly rendered, or name the offending path in a
+   * developer-facing message, has it without re-parsing anything.
+   */
+  prunedSelections;
   cause;
   constructor(message, options) {
     super(message);
@@ -42,6 +61,8 @@ var FoirRequestError = class extends Error {
     this.cause = options?.cause;
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
+    this.partialData = options?.partialData;
+    this.prunedSelections = options?.prunedSelections;
   }
   /**
    * The code of the first error, if the response carried one.
@@ -80,16 +101,46 @@ var FoirRequestError = class extends Error {
     return typeof seconds === "number" && seconds > 0 ? seconds * 1e3 : void 0;
   }
 };
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
 function buildFoirHeaders(input) {
   const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": input.apiKey
+    "Content-Type": "application/json"
   };
-  if (input.draftChannel) {
-    headers["X-Foir-Schema-Channel"] = "draft";
-  }
-  if (input.bearerToken) {
-    headers["Authorization"] = `Bearer ${input.bearerToken}`;
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    if (input.orgUrl) {
+      headers["X-Org-Url"] = input.orgUrl;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -105,14 +156,48 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
-function readFoirEnvelope(json) {
+var warnedDowngrade = null;
+function reportAuthDowngrade(envelope) {
+  const downgrade = envelope.extensions?.auth;
+  if (!downgrade) {
+    warnedDowngrade = null;
+    return;
+  }
+  if (warnedDowngrade === downgrade.reason) return;
+  warnedDowngrade = downgrade.reason;
+  console.warn(
+    `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}) \u2014 this request was served as ${downgrade.servedAs}, so auth-targeted content resolved to its anonymous variant. ` + (downgrade.reason === "expired" ? "Re-exchange the token and retry." : "Check which credential you are sending.")
+  );
+}
+function refusePrunedDocument(json, options) {
+  const selections = json.extensions?.pruned?.selections;
+  if (!selections?.length) return;
+  const describe = (s) => `${s.path}${s.type ? ` on ${s.type}` : ""} (${s.reason})`;
+  const malformed = selections.filter((s) => MALFORMED_PRUNE_REASONS.has(s.reason));
+  if (malformed.length && options?.strict !== false) {
+    throw new FoirRequestError(
+      `[foir] the server could not serve part of this query and returned the rest without it: ${malformed.map(describe).join(", ")}. Those selections do not exist on the schema this project is serving. Pass strict: false to get the partial answer instead of this error.`,
+      { prunedSelections: selections }
+    );
+  }
+  console.warn(
+    `[foir] selections stripped from this query: ${selections.map(describe).join(", ")}`
+  );
+}
+function answeredAnything(data) {
+  return typeof data === "object" && data !== null && Object.values(data).some((value) => value !== null && value !== void 0);
+}
+function readFoirEnvelope(json, options) {
+  reportAuthDowngrade(json);
+  refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data) {
+    if (answeredAnything(json.data) && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
-        graphQLErrors: json.errors
+        graphQLErrors: json.errors,
+        partialData: json.data ?? void 0
       });
     }
   }
@@ -626,10 +711,44 @@ async function resolveBearerToken(config) {
   if (typeof source === "function") return await source() ?? void 0;
   return source ?? void 0;
 }
+async function resolveDispatchToken(dispatch) {
+  const token = (await dispatch.token())?.trim();
+  if (!token) {
+    throw new FoirRequestError(
+      "[foir] the dispatch token provider returned no token. A client built from a dispatch calls Foir as that operation and holds no other credential. Build it from the token the endpoint was handed: `(await requireScopedToken(request)).dispatch`."
+    );
+  }
+  return token;
+}
+async function resolveFoirAuth(config) {
+  if (config.dispatch !== void 0) {
+    return {
+      headers: buildFoirHeaders({
+        dispatchToken: await resolveDispatchToken(config.dispatch),
+        dispatchContext: config.dispatch.context ?? void 0,
+        extra: config.headers
+      })
+    };
+  }
+  const bearerToken = await resolveBearerToken(config);
+  return {
+    headers: buildFoirHeaders({
+      apiKey: config.apiKey,
+      draftChannel: config.channel === "draft",
+      bearerToken,
+      orgId: config.orgId,
+      orgUrl: config.orgUrl,
+      extra: config.headers
+    }),
+    key: { apiKey: config.apiKey, bearerToken }
+  };
+}
 function foirRoute(input) {
   if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
+  if (input.orgId || input.orgUrl) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
+  if (input.writeToken) return { lane: "origin", reason: "floor" };
   if (input.channel === "draft") return { lane: "origin", reason: "channel" };
   return { lane: "shared" };
 }
@@ -642,23 +761,19 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
-async function runFoirDocument(config, document, mutation, variables) {
+async function runFoirDocument(config, document, mutation, variables, options) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
-  const bearerToken = await resolveBearerToken(config);
-  const headers = buildFoirHeaders({
-    apiKey: config.apiKey,
-    draftChannel: config.channel === "draft",
-    bearerToken,
-    extra: config.headers
-  });
+  const { headers, key } = await resolveFoirAuth(config);
   const hash = await documentHash(document);
-  const route = foirRoute({
-    apiKey: config.apiKey,
-    bearerToken,
+  const sharedKey = key !== void 0 && foirRoute({
+    apiKey: key.apiKey,
+    bearerToken: key.bearerToken,
+    orgId: config.orgId,
+    orgUrl: config.orgUrl,
     mutation,
     channel: config.channel
-  });
+  }).lane === "shared" ? key.apiKey : void 0;
   const post = (body) => doFetch(endpoint, {
     method: "POST",
     headers,
@@ -668,8 +783,8 @@ async function runFoirDocument(config, document, mutation, variables) {
   const extensions = persistedQueryExtension(hash);
   let res;
   try {
-    if (route.lane === "shared") {
-      res = await doFetch(buildCdnUrl(endpoint, config.apiKey, hash, variables), {
+    if (sharedKey !== void 0) {
+      res = await doFetch(buildCdnUrl(endpoint, sharedKey, hash, variables), {
         method: "GET",
         headers,
         ...config.requestInit
@@ -695,7 +810,7 @@ async function runFoirDocument(config, document, mutation, variables) {
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json);
+  return readFoirEnvelope(json, options);
 }
 async function readErrorBody(res) {
   try {
@@ -707,19 +822,16 @@ async function readErrorBody(res) {
 }
 
 // src/data/manifest.ts
-async function fetchFoirManifest(config) {
-  const url = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+async function fetchFoirManifest(config, options = {}) {
+  const base = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+  const url = options.operation === void 0 ? base : `${base}?operation=${encodeURIComponent(options.operation)}`;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const { headers } = await resolveFoirAuth(config);
   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
-      }),
+      headers,
       ...config.requestInit
     });
   } catch (err) {
@@ -759,6 +871,16 @@ var AUTH_OPS = {
   customerUpdatePassword: "customerUpdatePassword",
   customerVerifyEmail: "customerVerifyEmail",
   deleteMyAccount: "deleteMyAccount",
+  // The operator's organization context. TWO ops and no third: one to read
+  // which organizations the caller may stand in, one to say which. There is
+  // deliberately no per-call org argument anywhere in this SDK — the claim the
+  // row layer reads is resolved from the caller's own membership row on every
+  // request, so an application that never names an org cannot name the wrong
+  // one.
+  myOrganizations: "myOrganizations",
+  selectMyOrganization: "selectMyOrganization",
+  // Founding one. Present in a manifest only when the project opted in.
+  registerOperatorOrganization: "registerOperatorOrganization",
   // External identity providers.
   customerLoginWithProvider: "customerLoginWithProvider",
   customerProviderCallback: "customerProviderCallback",
@@ -780,6 +902,8 @@ function authClientConfig(env, options) {
     apiKey,
     channel: isFoirPreview(env) ? "draft" : "published",
     bearerToken: options?.bearerToken,
+    orgId: options?.orgId,
+    orgUrl: options?.orgUrl,
     headers: options?.headers,
     fetch: options?.fetch
   };
@@ -927,6 +1051,99 @@ async function completeFoirProviderLogin(opts) {
   );
 }
 
+// src/live/events.ts
+var RECORD_TAG_PREFIX = "rec:";
+var CACHED_CHANNEL = "published";
+function foirRecordTag(recordId) {
+  return `${RECORD_TAG_PREFIX}${recordId}`;
+}
+function foirModelTag(modelKey) {
+  return `model:${modelKey}:${CACHED_CHANNEL}`;
+}
+function foirTagsForRecordChange(event) {
+  const record = foirRecordTag(event.recordId);
+  if (event.action === "updated") return [record];
+  return [record, foirModelTag(event.modelKey)];
+}
+
+// src/next/cacheTags.ts
+var FOIR_SURROGATE_KEY_HEADER = "Surrogate-Key";
+var FOIR_NEXT_TAG_MAX_ITEMS = 128;
+var FOIR_NEXT_TAG_MAX_LENGTH = 256;
+var FOIR_UNTAGGED_TAG = "foir:untagged";
+var RECORD_TAG_PREFIX2 = "rec:";
+var COARSE_PREFIXES = ["proj:", "schema:", "model:", "lookup:"];
+function readFoirCacheTags(headers) {
+  const raw = headers.get(FOIR_SURROGATE_KEY_HEADER);
+  if (!raw) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const tag of raw.split(/\s+/)) {
+    if (!tag || seen.has(tag)) continue;
+    seen.add(tag);
+    out.push(tag);
+  }
+  return out;
+}
+function foirCacheTags(headers, options = {}) {
+  const maxTags = options.maxTags ?? FOIR_NEXT_TAG_MAX_ITEMS;
+  const maxTagLength = options.maxTagLength ?? FOIR_NEXT_TAG_MAX_LENGTH;
+  const all = readFoirCacheTags(headers);
+  if (all.length === 0) {
+    return { kind: "untagged", tags: [FOIR_UNTAGGED_TAG], reason: "no-surrogate-key" };
+  }
+  const records = all.filter((t) => t.startsWith(RECORD_TAG_PREFIX2));
+  const coarse = all.filter((t) => !t.startsWith(RECORD_TAG_PREFIX2));
+  const recordCount = records.length;
+  const recordsFit = records.length > 0 && records.every((t) => t.length <= maxTagLength);
+  const fitting = coarse.filter((t) => t.length <= maxTagLength);
+  if (recordsFit && records.length + fitting.length <= maxTags) {
+    return { kind: "tagged", tags: [...fitting, ...records], coarse: false, recordCount };
+  }
+  if (fitting.length === 0) {
+    return { kind: "untagged", tags: [FOIR_UNTAGGED_TAG], reason: "all-tags-unusable" };
+  }
+  return {
+    kind: "tagged",
+    tags: byBreadth(fitting).slice(0, maxTags),
+    coarse: true,
+    recordCount
+  };
+}
+function byBreadth(tags) {
+  const rank = (t) => {
+    const i = COARSE_PREFIXES.findIndex((p) => t.startsWith(p));
+    return i === -1 ? COARSE_PREFIXES.length : i;
+  };
+  return [...tags].sort((a, b) => rank(a) - rank(b));
+}
+function createFoirTaggingFetch(options) {
+  const { cacheTag, fetch: baseFetch, onTags, ...tagOptions } = options;
+  const doFetch = baseFetch ?? globalThis.fetch;
+  return async (input, init) => {
+    const res = await doFetch(input, init);
+    const tags = foirCacheTags(res.headers, tagOptions);
+    let applied = true;
+    let error;
+    try {
+      cacheTag(...tags.tags);
+    } catch (err) {
+      applied = false;
+      error = err;
+    }
+    onTags?.(error === void 0 ? { tags, applied } : { tags, applied, error });
+    return res;
+  };
+}
+function foirTagsForRecordEvent(event) {
+  return foirTagsForRecordChange(event);
+}
+function revalidateFoirRecordEvent(event, revalidateTag) {
+  const tags = foirTagsForRecordEvent(event);
+  for (const tag of tags) revalidateTag(tag);
+  return tags;
+}
+
 // src/next/middleware.ts
 function createFoirMiddleware(config) {
   const cookieName = config.cookieName ?? foirCookieName("foir:token");
@@ -947,14 +1164,23 @@ function createFoirMiddleware(config) {
   };
 }
 export {
+  FOIR_NEXT_TAG_MAX_ITEMS,
+  FOIR_NEXT_TAG_MAX_LENGTH,
+  FOIR_SURROGATE_KEY_HEADER,
+  FOIR_UNTAGGED_TAG,
   completeFoirProviderLogin,
   createFoirCookieAdapter,
   createFoirMiddleware,
+  createFoirTaggingFetch,
+  foirCacheTags,
   foirCookieName,
   foirRegisterWithPassword,
   foirSignInWithOtp,
   foirSignInWithPassword,
   foirSignOut,
+  foirTagsForRecordEvent,
   getFoirSession,
-  getFoirToken
+  getFoirToken,
+  readFoirCacheTags,
+  revalidateFoirRecordEvent
 };