@foir/sdk 0.18.0 → 0.20.0

package/dist/data/transport.d.ts

@@ -155,10 +155,10 @@ export type FoirOperationGeneratedModule<S extends FoirSchemaDefinition = FoirSc
  * const foir = createFoirClient({ apiUrl, dispatch, generated });
  * ```
  *
- * The endpoint calls Foir AS the operation, with the capabilities the operation
+ * The endpoint calls Foir AS the operation, with the grants the operation
  * declared, and holds no key of its own. api-public accepts the token as a
  * caller in its own right: it builds the schema overlay from the token's
- * capabilities, and it reads the organization and the customer from the
+ * grants, and it reads the organization and the customer from the
  * token's claims. So nothing a key client configures beside its key
  * (`bearerToken`, `orgId`, `channel`) means anything here, and none of it is
  * accepted.
@@ -419,19 +419,33 @@ export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchema
     /** Called instead of `console.warn` when drift is detected. */
     onSchemaDrift?: (drift: FoirSchemaDrift) => void;
     /**
-     * Refuse typed calls once drift is detected, instead of serving the stale
-     * shape. **On by default**; pass `false` to opt out.
-     *
-     * The asymmetry this closes: an unknown ARGUMENT is refused client-side
-     * before the server sees it, while a field the server has and the generated
-     * selection does not is simply not requested. The second is the common case
-     * when a schema evolves, and it surfaces as absent data rather than as a
-     * tooling problem — so it is the one that needs to be loud.
-     *
-     * It is the default rather than an opt-in because the thing it prevents is
-     * SILENT. An opt-in guard against a silent failure only protects the people
-     * who already suspected the failure existed, and the warning it replaces is
-     * one more line to scroll past.
+     * Refuse a typed call that depends on something the server no longer serves
+     * the way the generated module describes. **On by default**; pass `false` to
+     * opt out.
+     *
+     * A drift by itself refuses nothing. The surface version moves whenever the
+     * surface grows (a field on a model, an op on a namespace, a mutation the
+     * platform adds to every model), and a document printed from the older trees
+     * is still answered in full. So once the manifest has arrived the client
+     * compares its generated trees with the served ones, and refuses only the
+     * calls whose own parts changed:
+     *
+     *   - the op is gone, or its root field or result kind changed;
+     *   - an argument the module declares is gone or has a type the generated
+     *     one no longer fits, or the op now requires an argument the module does
+     *     not know;
+     *   - a field the call's selection names is gone or has another shape, in the
+     *     model the op returns, in a union that model's tree embeds, or in the
+     *     target of a relation the call includes.
+     *
+     * Anything ADDED refuses nothing: a model, a namespace, an op, an optional
+     * argument, a field, a relation, a union member, a subscription.
+     *
+     * It is the default because the alternative is worse for the caller. A call
+     * that depends on a removed field is answered with a server error naming the
+     * field, and one whose relation changed from a record to a list is answered
+     * in a shape the types do not describe. Neither says the generated module is
+     * the thing to fix. `FoirSchemaDriftError` does, and names the part.
      *
      * Two things it deliberately does not do.
      *
@@ -441,20 +455,16 @@ export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchema
      * block every first call on a second round trip, which is the cost the
      * warning was designed to avoid.
      *
-     * It does not touch `raw`. A hand-written document asks for exactly the
-     * fields it names, so it cannot silently omit one — raw is immune to this
-     * class of bug by construction, and refusing it would punish the escape
-     * hatch people reach for precisely because it is immune.
+     * It does not touch `raw`. A hand-written document is not printed from the
+     * generated trees, so nothing compared here says anything about it.
      *
-     * Turning it off is never the remedy for a drift. The version it compares
-     * is the SURFACE the types were generated from, which moves only when
-     * regenerating would write a different file, so every drift it reports is a
-     * real one and the fix is `foir types`. The opt-out exists for an app that
-     * knowingly ships a stale module for a while, and it says so at the call
-     * site, where a reader can see it:
+     * Turning it off is never the remedy. A refusal names something that really
+     * is no longer served as generated, and the fix is `foir types`. The opt-out
+     * exists for an app that would rather send the call and handle the server's
+     * answer, and it says so at the call site, where a reader can see it:
      *
      * ```ts
-     * createFoirClient({ strictSchemaDrift: false })  // serve stale, warn only
+     * createFoirClient({ strictSchemaDrift: false })  // never refuse, warn only
      * ```
      */
     strictSchemaDrift?: boolean;
@@ -578,9 +588,23 @@ export interface FoirSchemaDrift {
      * too. Empty only when the module was wired without `surfaceHashes`.
      */
     changed: readonly string[];
+    /**
+     * What the generated module describes that the server no longer serves that
+     * way, as paths into the manifest, sorted:
+     * `models.order.selection.status`, `models.order.ops.update`,
+     * `namespaces.search.ops.searchRecords.args.query`,
+     * `models.order.relations.customer`, `selectionUnions.Block.HeroBlock.title`.
+     *
+     * `changed` says what moved; this says what BROKE. Empty when the surface
+     * only grew, which is the usual drift, and then no typed call is refused.
+     * Also empty for a client that prints from the served manifest rather than
+     * from generated trees, since it has nothing older to compare.
+     */
+    incompatible: readonly string[];
 }
 /**
- * Thrown by a typed call under `strictSchemaDrift` once drift is detected.
+ * Thrown by a typed call under `strictSchemaDrift` when the call depends on
+ * something in `drift.incompatible`. The message names which.
  *
  * A subclass rather than a plain `FoirRequestError` so an app can tell "your
  * generated module is stale" from "this request failed", which want different

package/dist/data.js

@@ -1008,6 +1008,304 @@ function isFoirMutationDocument(documentText) {
   return /\bmutation\b/.test(documentText);
 }
 
+// src/data/compatibility.ts
+var newPart = () => ({ broken: [], prints: /* @__PURE__ */ new Set() });
+var GONE = "no longer served";
+function shapeOf(field) {
+  if (field.relation) return "a relation";
+  if (field.truncated) {
+    return field.union ? `a stopping point before the union ${field.union}` : "a stopping point";
+  }
+  if (field.model) return `the model ${field.model}`;
+  if (field.union) return `the union ${field.union}`;
+  return field.fields?.length ? "an object" : "a leaf";
+}
+function compareFields(generated, served, path, part) {
+  const byKey = new Map((served ?? []).map((field) => [field.key, field]));
+  for (const field of generated) {
+    if (field.relation) continue;
+    const at = `${path}.${field.key}`;
+    const now = byKey.get(field.key);
+    if (!now) {
+      part.broken.push({ path: at, reason: GONE });
+      continue;
+    }
+    const was = shapeOf(field);
+    const is = shapeOf(now);
+    if (field.truncated) {
+      const composite = !now.relation && is !== "a leaf";
+      if (!composite || field.union && now.union !== field.union) {
+        part.broken.push({ path: at, reason: `generated as ${was}, served as ${is}` });
+        continue;
+      }
+      if (field.union) part.prints.add(`u:${field.union}`);
+      continue;
+    }
+    if (was !== is) {
+      part.broken.push({ path: at, reason: `generated as ${was}, served as ${is}` });
+      continue;
+    }
+    if (field.model) part.prints.add(`m:${field.model}`);
+    else if (field.union) part.prints.add(`u:${field.union}`);
+    else if (field.fields?.length) compareFields(field.fields, now.fields, at, part);
+  }
+}
+function variableFits(variable, position) {
+  if (position.endsWith("!")) {
+    return variable.endsWith("!") && variableFits(variable.slice(0, -1), position.slice(0, -1));
+  }
+  if (variable.endsWith("!")) return variableFits(variable.slice(0, -1), position);
+  if (position.startsWith("[")) {
+    return variable.startsWith("[") && variableFits(variable.slice(1, -1), position.slice(1, -1));
+  }
+  return variable === position;
+}
+function compareOp(generated, served, at) {
+  const part = newPart();
+  if (!served) {
+    part.broken.push({ path: at, reason: GONE });
+    return part;
+  }
+  if (generated.field !== served.field) {
+    part.broken.push({
+      path: `${at}.field`,
+      reason: `root field ${generated.field}, served as ${served.field}`
+    });
+  }
+  if (Boolean(generated.mutation) !== Boolean(served.mutation)) {
+    part.broken.push({
+      path: `${at}.mutation`,
+      reason: served.mutation ? "now a mutation" : "no longer a mutation"
+    });
+  }
+  const declared = generated.args ?? [];
+  for (const name of declared) {
+    const type = generated.argTypes?.[name];
+    if (!type) continue;
+    if (!served.args?.includes(name)) {
+      part.broken.push({ path: `${at}.args.${name}`, reason: "no longer accepted" });
+      continue;
+    }
+    const now2 = served.argTypes?.[name];
+    if (!now2 || !variableFits(type, now2)) {
+      part.broken.push({
+        path: `${at}.args.${name}`,
+        reason: `type ${type}, served as ${now2 ?? "no published type"}`
+      });
+    }
+  }
+  for (const name of served.args ?? []) {
+    if (declared.includes(name)) continue;
+    if (served.argTypes?.[name]?.endsWith("!")) {
+      part.broken.push({ path: `${at}.args.${name}`, reason: "a new required argument" });
+    }
+  }
+  const payload = generated.payload;
+  if (!payload || payload.error) return part;
+  const now = served.payload;
+  if (!now || now.error) {
+    part.broken.push({ path: `${at}.payload`, reason: "no result shape is served" });
+    return part;
+  }
+  if (payload.kind !== now.kind) {
+    part.broken.push({
+      path: `${at}.payload`,
+      reason: `result kind ${payload.kind}, served as ${String(now.kind)}`
+    });
+    return part;
+  }
+  if (payload.kind === "record" && payload.model) {
+    if (payload.model !== now.model) {
+      part.broken.push({
+        path: `${at}.payload`,
+        reason: `returns the model ${payload.model}, served as ${now.model ?? "none"}`
+      });
+    } else {
+      part.prints.add(`m:${payload.model}`);
+    }
+  } else if (payload.kind === "union" && payload.union) {
+    if (payload.union !== now.union) {
+      part.broken.push({
+        path: `${at}.payload`,
+        reason: `returns the union ${payload.union}, served as ${now.union ?? "none"}`
+      });
+    } else {
+      part.prints.add(`u:${payload.union}`);
+    }
+  } else if (payload.kind === "object") {
+    compareFields(payload.fields ?? [], now.fields, `${at}.payload`, part);
+  }
+  return part;
+}
+function compareRelation(generated, served, at) {
+  if (!served) return { path: at, reason: GONE };
+  const targets = generated.targets ?? [];
+  const nowTargets = served.targets ?? [];
+  if (targets.length) {
+    const dropped = targets.filter((target) => !nowTargets.includes(target));
+    if (dropped.length) {
+      return { path: at, reason: `no longer targets ${dropped.join(", ")}` };
+    }
+  } else if (nowTargets.length || (generated.target ?? "") !== (served.target ?? "")) {
+    return {
+      path: at,
+      reason: `targets ${generated.target ?? "nothing"}, served as ${nowTargets.length ? nowTargets.join(" | ") : served.target ?? "nothing"}`
+    };
+  }
+  if (Boolean(generated.connection) !== Boolean(served.connection)) {
+    return {
+      path: at,
+      reason: served.connection ? "now a connection" : "no longer a connection"
+    };
+  }
+  if (Boolean(generated.list) !== Boolean(served.list)) {
+    return { path: at, reason: served.list ? "now a list" : "no longer a list" };
+  }
+  return void 0;
+}
+var NOTHING = [];
+function compareFoirSurfaces(generated, served) {
+  const servedModels = served.models ?? {};
+  const servedNamespaces = served.namespaces ?? {};
+  const servedUnions = served.selectionUnions ?? {};
+  const trees = /* @__PURE__ */ new Map();
+  const ops = /* @__PURE__ */ new Map();
+  const relations = /* @__PURE__ */ new Map();
+  for (const [key, model] of Object.entries(generated.models ?? {})) {
+    const at = `models.${key}`;
+    const now = servedModels[key];
+    const tree = newPart();
+    trees.set(`m:${key}`, tree);
+    if (!now) {
+      const gone = { path: at, reason: GONE };
+      tree.broken.push(gone);
+      for (const op of Object.keys(model.ops ?? {})) {
+        ops.set(`${at}.ops.${op}`, { broken: [gone], prints: /* @__PURE__ */ new Set() });
+      }
+      for (const relation of model.relations ?? []) {
+        relations.set(`${key} ${relation.key}`, gone);
+      }
+      continue;
+    }
+    if (model.typeName !== now.typeName) {
+      tree.broken.push({
+        path: `${at}.typeName`,
+        reason: `type ${model.typeName}, served as ${now.typeName}`
+      });
+    }
+    if (model.selection) {
+      if (!now.selection) tree.broken.push({ path: `${at}.selection`, reason: GONE });
+      else compareFields(model.selection.fields, now.selection.fields, `${at}.selection`, tree);
+    }
+    for (const [op, def] of Object.entries(model.ops ?? {})) {
+      ops.set(`${at}.ops.${op}`, compareOp(def, now.ops?.[op], `${at}.ops.${op}`));
+    }
+    for (const relation of model.relations ?? []) {
+      const broken = compareRelation(
+        relation,
+        now.relations?.find((r) => r.key === relation.key),
+        `${at}.relations.${relation.key}`
+      );
+      if (broken) relations.set(`${key} ${relation.key}`, broken);
+    }
+  }
+  for (const [name, namespace] of Object.entries(generated.namespaces ?? {})) {
+    const at = `namespaces.${name}`;
+    const now = servedNamespaces[name];
+    const gone = now ? void 0 : { path: at, reason: GONE };
+    for (const [op, def] of Object.entries(namespace.ops ?? {})) {
+      ops.set(
+        `${at}.ops.${op}`,
+        gone ? { broken: [gone], prints: /* @__PURE__ */ new Set() } : compareOp(def, now?.ops?.[op], `${at}.ops.${op}`)
+      );
+    }
+  }
+  for (const [name, union] of Object.entries(generated.selectionUnions ?? {})) {
+    const at = `selectionUnions.${name}`;
+    const now = servedUnions[name];
+    const tree = newPart();
+    trees.set(`u:${name}`, tree);
+    if (!now) {
+      tree.broken.push({ path: at, reason: GONE });
+      continue;
+    }
+    for (const member of union.members) {
+      const nowMember = now.members?.find((m) => m.typeName === member.typeName);
+      if (!nowMember) {
+        tree.broken.push({ path: `${at}.${member.typeName}`, reason: "no longer a member" });
+        continue;
+      }
+      compareFields(member.fields, nowMember.fields, `${at}.${member.typeName}`, tree);
+    }
+  }
+  const paths = /* @__PURE__ */ new Set();
+  for (const part of [...trees.values(), ...ops.values()]) {
+    for (const broken of part.broken) paths.add(broken.path);
+  }
+  for (const broken of relations.values()) paths.add(broken.path);
+  const incompatible = [...paths].sort();
+  const reached = /* @__PURE__ */ new Map();
+  const reach = (start) => {
+    const held = reached.get(start);
+    if (held) return held;
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    const pending = [start];
+    while (pending.length) {
+      const id = pending.pop();
+      if (seen.has(id)) continue;
+      seen.add(id);
+      const tree = trees.get(id);
+      if (!tree) continue;
+      out.push(...tree.broken);
+      pending.push(...tree.prints);
+    }
+    reached.set(start, out);
+    return out;
+  };
+  const included = (modelKey, include, out) => {
+    if (!include || typeof include !== "object") return;
+    const model = generated.models[modelKey];
+    if (!model) return;
+    for (const [key, value] of Object.entries(include)) {
+      if (value === void 0 || value === false) continue;
+      const relation = model.relations?.find((r) => r.key === key);
+      if (!relation) continue;
+      const broken = relations.get(`${modelKey} ${key}`);
+      if (broken) out.push(broken);
+      const nested = value && typeof value === "object" ? value["include"] : void 0;
+      const targets = relation.targets?.length ? relation.targets : [relation.target ?? ""];
+      for (const target of targets) {
+        out.push(...reach(`m:${target}`));
+        included(target, nested, out);
+      }
+    }
+  };
+  const call = (address, def, include) => {
+    if (incompatible.length === 0) return NOTHING;
+    const op = ops.get(address);
+    if (!op || !def) return NOTHING;
+    const out = [...op.broken];
+    for (const id of op.prints) out.push(...reach(id));
+    if (include && def.payload) {
+      const records = new Set(payloadRecordPaths(def.payload).map((entry) => entry.modelKey));
+      if (records.size === 1) included([...records][0], include, out);
+    }
+    if (out.length === 0) return NOTHING;
+    const unique = new Map(out.map((broken) => [broken.path, broken]));
+    return [...unique.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  };
+  return {
+    incompatible,
+    modelCall: (model, op, include) => call(`models.${model}.ops.${op}`, generated.models[model]?.ops?.[op], include),
+    namespaceCall: (namespace, op, include) => call(
+      `namespaces.${namespace}.ops.${op}`,
+      generated.namespaces?.[namespace]?.ops?.[op],
+      include
+    )
+  };
+}
+
 // src/data/subscription-document.ts
 function printSubscriptionDocument(input) {
   const args = input.args ?? [];
@@ -1863,6 +2161,15 @@ function describeDrift(drift) {
   const moved = describeChanged(drift.changed);
   return `the types were generated from surface ${drift.generated}, and the server is serving ${drift.server} (${drift.channel}).` + (moved ? ` Changed since: ${moved}.` : "");
 }
+var NAMED_INCOMPATIBLE_PARTS = 5;
+function nameParts(parts) {
+  const named = parts.slice(0, NAMED_INCOMPATIBLE_PARTS).join(", ");
+  const rest = parts.length - NAMED_INCOMPATIBLE_PARTS;
+  return rest > 0 ? `${named} and ${rest} more` : named;
+}
+function describeIncompatible(parts) {
+  return nameParts(parts.map((part) => `${part.path} (${part.reason})`));
+}
 function announceFallback(config) {
   if (config.generated !== void 0 || config.selections !== void 0) return;
   if (config.announceManifestFallback === false) return;
@@ -1881,6 +2188,7 @@ function createFoirClient(clientConfig) {
   announceFallback(config);
   let driftChecked = false;
   let detectedDrift;
+  let servedComparison;
   let manifestOnce;
   const manifest = () => {
     if (!manifestOnce) {
@@ -1909,32 +2217,51 @@ function createFoirClient(clientConfig) {
     driftChecked = true;
     void manifest().then((served) => {
       if (!served.surfaceVersion || served.surfaceVersion === generated) return;
+      const comparison = config.selections ? compareFoirSurfaces(
+        {
+          models: config.selections,
+          namespaces: config.namespaceSelections,
+          selectionUnions: config.selectionUnions
+        },
+        served
+      ) : void 0;
       const drift = {
         generated,
         server: served.surfaceVersion,
         channel: served.channel,
-        changed: changedSurfaceParts(config.surfaceHashes, served.surfaceHashes)
+        changed: changedSurfaceParts(config.surfaceHashes, served.surfaceHashes),
+        incompatible: comparison?.incompatible ?? []
       };
       detectedDrift = drift;
+      servedComparison = comparison;
       if (config.onSchemaDrift) {
         config.onSchemaDrift(drift);
         return;
       }
+      if (drift.incompatible.length === 0) {
+        console.warn(
+          `[foir] schema drift: ${describeDrift(drift)} Everything the generated module describes is still served as generated, so every typed call keeps working. The surface has grown: re-run \`foir types\` to pick up what is new, because a field added since is not merely untyped, it is not requested.`
+        );
+        return;
+      }
+      const those = drift.incompatible.length === 1 ? "it" : "them";
       console.warn(
-        `[foir] schema drift: ${describeDrift(drift)} Re-run \`foir types\`: the selection trees this client prints from are the ones that surface published, so a new field is not merely untyped, it is not requested.`
+        `[foir] schema drift: ${describeDrift(drift)} No longer served as the generated module describes: ${nameParts(drift.incompatible)}. ` + (config.strictSchemaDrift === false ? `Typed calls that depend on ${those} are still sent, and can fail or answer in another shape. ` : `Typed calls that depend on ${those} are refused. `) + `Re-run \`foir types\`.`
       );
     }).catch(() => {
     });
   };
-  const assertNoStaleSelections = (what) => {
-    if (config.strictSchemaDrift === false || !detectedDrift) return;
+  const assertStillServed = (what, dependsOn) => {
+    if (config.strictSchemaDrift === false || !detectedDrift || !servedComparison) return;
+    const broken = dependsOn(servedComparison);
+    if (broken.length === 0) return;
     throw new FoirSchemaDriftError(
-      `[foir] refusing ${what}: ${describeDrift(detectedDrift)} The selection trees this client prints from are the ones that surface published, so a field added since is not requested at all. Re-run \`foir types\`.`,
+      `[foir] refusing ${what}: ${describeDrift(detectedDrift)} This call depends on ${describeIncompatible(broken)}, which the server no longer serves as the generated module describes. Re-run \`foir types\`.`,
       detectedDrift
     );
   };
   const runModel = async (model, op, query) => {
-    assertNoStaleSelections(`${model}.${op}`);
+    assertStillServed(`${model}.${op}`, (served) => served.modelCall(model, op, query?.include));
     const { args, include, omit, pick, depth } = splitQuery(query);
     const source = await selectionSource();
     const plan = planFoirModelCall(source, {
@@ -1952,7 +2279,10 @@ function createFoirClient(clientConfig) {
     return result;
   };
   const runNamespace = async (namespace, op, query) => {
-    assertNoStaleSelections(`ns.${namespace}.${op}`);
+    assertStillServed(
+      `ns.${namespace}.${op}`,
+      (served) => served.namespaceCall(namespace, op, query?.include)
+    );
     const { args, include, omit, pick, depth } = splitQuery(query);
     const plan = planFoirNamespaceCall(await selectionSource(), {
       namespace,

package/dist/next.js

@@ -921,6 +921,9 @@ var AUTH_OPS = {
   // Post-credential self reads.
   currentUser: "currentUser",
   myProviderToken: "myProviderToken",
+  // What the calling credential may do, and for a signed-in customer the roles
+  // they hold. `./access` reads it.
+  whoami: "whoami",
   // Methods.
   customerLogin: "customerLogin",
   customerRegister: "customerRegister",

package/dist/placement/index.d.ts

@@ -5,8 +5,9 @@
  * reaches a cross-site frame, so the console hands the page a short-lived token
  * instead, by message, to your placement's origin only. The token is the
  * operator looking at the page, acting through your app at the level your app
- * is installed at, carrying the scopes your placement declares that this
- * operator holds. Your page runs no login of its own.
+ * is installed at, carrying what your placement declares and this operator
+ * holds, as grants in the permission catalogue's names. Your page runs no
+ * login of its own.
  *
  * ```ts
  * import { connectPlacement, FOIR_CONSOLE_ORIGINS } from '@foir/sdk/placement';
@@ -15,7 +16,7 @@
  *   apiUrl: 'https://api.foir.dev',
  *   consoleOrigins: FOIR_CONSOLE_ORIGINS.production,
  * });
- * if (session.can('records:write:preorder')) showEditButtons();
+ * if (session.can('records:write.all:preorder')) showEditButtons();
  * const data = await session.request('{ preorders { items { id } } }');
  * ```
  *
@@ -52,14 +53,38 @@ export interface PlacementGrant {
     expiresAt: string;
     /** The organisation the page acts at: your app's install. Empty for the project. */
     orgId: string;
-    /** What the token carries. */
+    /**
+     * What the token carries: the grants your placement declares that this
+     * operator holds, in the permission catalogue's names. A grant the operator
+     * holds part of is carried as that part, so ask with `can` and not by
+     * looking for a spelling here.
+     */
+    grants: string[];
+    /** Each grant your placement declares that the token does not carry whole, and why. */
+    withheldGrants: {
+        grant: string;
+        reason: string;
+    }[];
+    /**
+     * @deprecated Read `grants`. The same list under the name it had before a
+     * placement declared grants.
+     */
     grantedScopes: string[];
-    /** What your placement declares that this operator does not hold, and why. */
+    /**
+     * @deprecated Read `withheldGrants`. The same list under the name it had
+     * before a placement declared grants.
+     */
     withheld: {
         scope: string;
         reason: string;
     }[];
 }
+/**
+ * What a console sends with a token. A console of the release before sends
+ * only `grantedScopes` and `withheld`, and the session reads `grants` from
+ * those.
+ */
+type PlacementGrantMessage = Pick<PlacementGrant, 'accessToken' | 'expiresAt' | 'orgId'> & Partial<Pick<PlacementGrant, 'grants' | 'withheldGrants' | 'grantedScopes' | 'withheld'>>;
 /** How the console looks, for an embedded page to match. */
 export interface PlacementAppearance {
     /**
@@ -71,7 +96,7 @@ export interface PlacementAppearance {
 /** A message the console sends an embedded page. */
 export type PlacementHostMessage = {
     type: typeof PLACEMENT_MESSAGE.token;
-    grant: PlacementGrant;
+    grant: PlacementGrantMessage;
 } | {
     type: typeof PLACEMENT_MESSAGE.refused;
     reason: string;
@@ -138,8 +163,14 @@ export interface PlacementSession {
      * older than this). Kept current as the operator changes it.
      */
     readonly appearance: PlacementAppearance | null;
-    /** Whether the token carries this scope, to hide or grey out what the operator cannot do. */
-    can(scope: string): boolean;
+    /**
+     * Whether the token covers this grant, to hide or grey out what the operator
+     * cannot do. It answers as Foir's API would: a grant for every model covers
+     * the same grant for one, and one for every owner's rows covers a person's
+     * own. `can('records:read.all:order')` is true for a token that carries
+     * `records:read.all`.
+     */
+    can(grant: string): boolean;
     /** A GraphQL request to Foir's API as the operator, through your app. */
     request<TResult = unknown>(document: string | {
         toString(): string;
@@ -156,3 +187,4 @@ export interface PlacementSession {
  * console gives no token, or when none arrives in time.
  */
 export declare function connectPlacement(options: ConnectPlacementOptions): Promise<PlacementSession>;
+export {};