@foir/sdk 0.9.0 → 0.11.0

package/dist/auth.js

@@ -11,11 +11,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);
@@ -23,6 +42,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.
@@ -82,16 +103,46 @@ function readFoirRetryAfterMs(headers) {
   const seconds = Number(headers.get("Retry-After"));
   return Number.isFinite(seconds) && 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)) {
@@ -107,14 +158,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
       });
     }
   }
@@ -155,8 +240,9 @@ async function hasFoirErrorCode(res, ...codes) {
 }
 
 // src/graphql/cdn-route.ts
-function isCdnEligible(env, documentText, bearerToken) {
+function isCdnEligible(env, documentText, bearerToken, orgId) {
   if (bearerToken) return false;
+  if (orgId) return false;
   if (isFoirPreview(env)) return false;
   const apiKey = resolveFoirApiKey(env);
   if (!apiKey?.startsWith("pk_")) return false;
@@ -175,12 +261,14 @@ async function foirRequest(env, document, variables, options) {
   const headers = buildFoirHeaders({
     apiKey,
     draftChannel: isFoirPreview(env),
-    bearerToken: options?.bearerToken
+    bearerToken: options?.bearerToken,
+    orgId: options?.orgId,
+    orgUrl: options?.orgUrl
   });
   const documentText = print2(document);
   let res;
   try {
-    if (isCdnEligible(env, documentText, options?.bearerToken)) {
+    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId ?? options?.orgUrl)) {
       const hash = await documentHash(documentText);
       let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
         method: "GET",
@@ -736,10 +824,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" };
 }
@@ -752,23 +874,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,
@@ -778,8 +896,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
@@ -805,7 +923,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 {
@@ -817,19 +935,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) {
@@ -869,6 +984,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",
@@ -890,6 +1015,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
   };
@@ -998,6 +1125,15 @@ async function customerLogout(env, options) {
 async function deleteMyAccount(env, vars, options) {
   return authOp(env, AUTH_OPS.deleteMyAccount, vars, options);
 }
+async function myOrganizations(env, vars, options) {
+  return authOp(env, AUTH_OPS.myOrganizations, vars ?? {}, options);
+}
+async function selectOrganization(env, vars, options) {
+  return authOp(env, AUTH_OPS.selectMyOrganization, vars, options);
+}
+async function registerOrganization(env, vars, options) {
+  return authOp(env, AUTH_OPS.registerOperatorOrganization, vars, options);
+}
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
   await adapter.set(REFRESH_KEY, result.refreshToken);
@@ -1135,25 +1271,48 @@ async function fetchHostedSession(request, config) {
   const match = cookie.match(
     new RegExp(`(?:^|;\\s*)${escapeRegExp(cookieName)}=([^;]+)`)
   );
-  if (!match) return null;
+  if (!match) return { outcome: "signed-out", reason: "no-cookie" };
+  let res;
   try {
-    const res = await fetch(`${config.loginOrigin}${sessionPath}`, {
+    res = await fetch(`${config.loginOrigin}${sessionPath}`, {
       headers: {
         Cookie: `${cookieName}=${match[1]}`,
         "X-Foir-Session": "1"
       }
     });
-    if (!res.ok) return null;
-    const json = await res.json();
-    if (!json.access_token || !json.customer_id) return null;
-    return {
-      token: json.access_token,
-      customerId: json.customer_id,
-      email: json.email ?? ""
-    };
+  } catch (cause) {
+    return { outcome: "unavailable", reason: "network", cause };
+  }
+  if (!res.ok) {
+    if (res.status === 401) {
+      return { outcome: "signed-out", reason: "rejected" };
+    }
+    if (res.status === 403) {
+      return { outcome: "unavailable", reason: "forbidden", httpStatus: res.status };
+    }
+    if (res.status === 429) {
+      return { outcome: "unavailable", reason: "rate-limited", httpStatus: res.status };
+    }
+    return { outcome: "unavailable", reason: "server-error", httpStatus: res.status };
+  }
+  let json;
+  try {
+    json = await res.json();
   } catch {
-    return null;
+    return { outcome: "unavailable", reason: "malformed", httpStatus: res.status };
   }
+  if (!json.access_token || !json.customer_id) {
+    return { outcome: "unavailable", reason: "malformed", httpStatus: res.status };
+  }
+  return {
+    outcome: "active",
+    session: {
+      token: json.access_token,
+      customerId: json.customer_id,
+      email: json.email ?? "",
+      expiresIn: typeof json.expires_in === "number" ? json.expires_in : 0
+    }
+  };
 }
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1326,12 +1485,15 @@ export {
   hostedLogoutUrl,
   loginWithOTP,
   loginWithPassword,
+  myOrganizations,
   myProviderToken,
   refreshSession,
+  registerOrganization,
   registerWithPassword,
   requireAdmin,
   requireAuth,
   resetPasswordAndSignIn,
   saveSession,
+  selectOrganization,
   signOut
 };

package/dist/client.js

@@ -11,11 +11,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);
@@ -23,6 +42,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.
@@ -94,16 +115,46 @@ function readFoirRetryAfterMs(headers) {
   const seconds = Number(headers.get("Retry-After"));
   return Number.isFinite(seconds) && 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)) {
@@ -112,14 +163,48 @@ function buildFoirHeaders(input) {
   }
   return headers;
 }
-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
       });
     }
   }
@@ -160,8 +245,9 @@ async function hasFoirErrorCode(res, ...codes) {
 }
 
 // src/graphql/cdn-route.ts
-function isCdnEligible(env, documentText, bearerToken) {
+function isCdnEligible(env, documentText, bearerToken, orgId) {
   if (bearerToken) return false;
+  if (orgId) return false;
   if (isFoirPreview(env)) return false;
   const apiKey = resolveFoirApiKey(env);
   if (!apiKey?.startsWith("pk_")) return false;
@@ -214,12 +300,14 @@ async function foirRequest(env, document, variables, options) {
   const headers = buildFoirHeaders({
     apiKey,
     draftChannel: isFoirPreview(env),
-    bearerToken: options?.bearerToken
+    bearerToken: options?.bearerToken,
+    orgId: options?.orgId,
+    orgUrl: options?.orgUrl
   });
   const documentText = print2(document);
   let res;
   try {
-    if (isCdnEligible(env, documentText, options?.bearerToken)) {
+    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId ?? options?.orgUrl)) {
       const hash = await documentHash(documentText);
       let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
         method: "GET",

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

@@ -2,7 +2,7 @@
  * `@foir/sdk/codegen/block-registry` — DEPRECATED alias.
  *
  * `block` was one project's name for a flexible field, never a platform
- * concept (TTS-1391). The plugin moved to `@foir/sdk/codegen/item-registry`;
+ * concept. The plugin moved to `@foir/sdk/codegen/item-registry`;
  * this path re-exports it unchanged so an existing `codegen.ts` keeps working.
  * Repoint the `plugins:` entry when convenient — this will be removed in a
  * future major.

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

@@ -2,7 +2,7 @@
  * `@foir/sdk/codegen/block-scaffold` — DEPRECATED alias.
  *
  * `block` was one project's name for a flexible field, never a platform
- * concept (TTS-1391). The plugin moved to `@foir/sdk/codegen/item-scaffold`;
+ * concept. The plugin moved to `@foir/sdk/codegen/item-scaffold`;
  * this path re-exports it unchanged so an existing `codegen.ts` keeps working.
  * Repoint the `plugins:` entry when convenient — this will be removed in a
  * future major.

package/dist/codegen/index.d.ts

@@ -6,7 +6,7 @@
  * and item-scaffold plugins are wired by the preset and also available at
  * `@foir/sdk/codegen/item-registry` / `@foir/sdk/codegen/item-scaffold`.
  *
- * The pre-TTS-1391 paths `@foir/sdk/codegen/block-registry` and
+ * The pre-rename paths `@foir/sdk/codegen/block-registry` and
  * `/block-scaffold` still resolve, re-exporting those modules unchanged.
  */
 export { foirCodegen, foirScaffold } from './preset';

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

@@ -13,7 +13,7 @@
  * types from the codegen output (`./graphql`) and `ItemComponent` from
  * `@foir/sdk/content`, so it pairs directly with `createContentRenderer`.
  *
- * Reachable at the pre-TTS-1391 path `@foir/sdk/codegen/block-registry` too,
+ * Reachable at the pre-rename path `@foir/sdk/codegen/block-registry` too,
  * which re-exports this module unchanged.
  */
 import type { GraphQLSchema } from 'graphql';

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

@@ -10,7 +10,7 @@
  * in. Adding a new item type later surfaces as a compile error on
  * `itemRegistry` (via the regenerated `ItemRegistry` type), not here.
  *
- * Reachable at the pre-TTS-1391 path `@foir/sdk/codegen/block-scaffold` too,
+ * Reachable at the pre-rename path `@foir/sdk/codegen/block-scaffold` too,
  * which re-exports this module unchanged.
  */
 import type { GraphQLSchema } from 'graphql';

package/dist/codegen/preset.d.ts

@@ -21,9 +21,10 @@ export interface FoirCodegenOptions {
      */
     apiKey?: string;
     /**
-     * Preview (`sk_`) key with `drafts:read`. Reads the DRAFT schema channel so
+     * Preview key holding `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.
+     * Strongly preferred: a key without `drafts:read` only sees the published
+     * schema.
      */
     previewKey?: string;
     /** Output directory for the generated client types. Default `./app/gql/foir/`. */