@foir/sdk 0.30.0 → 0.31.0

package/dist/auth/steps.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The finishing halves of signing in, and of a person's own account steps,
+ * each on the data API's own route.
+ *
+ * A step is begun by an auth op (asking for a password reset, for one) and
+ * finished with the proof the person brings back: the token the reset link
+ * carried. The finish is no op of its own. The data API takes it on the step's
+ * route for somebody who holds no session yet, and the proof decides whose
+ * step it finishes, so it is sent with no key and no session.
+ */
+import { type FoirEnv } from '../transport/foir-http';
+/**
+ * A code sign-in begun: {@link requestOTP} and {@link signUpWithPassword} answer one.
+ * The code the address was sent is brought back to it with
+ * {@link signInWithOTP}. Every address is answered a step alike, so having one
+ * says nothing of whether the address is anybody's.
+ */
+export interface FoirSignInStep {
+    id: string;
+    /** Minted for this step alone; it is the credential the code goes back with. */
+    token: string;
+    /** The step's own route. */
+    endpoint: string;
+    /** When the step, and its code, lapse (RFC 3339). */
+    expiresAt: string;
+}
+/**
+ * A change to the calling user's own account begun: {@link addMyAddress}
+ * answers one. What it asks for (the code the address was sent) is brought
+ * back to it with its token in the body, with {@link proveMyAddress}. It
+ * finishes once, for the person who began it, and not once the session that
+ * began it has ended.
+ */
+export interface FoirAccountStep {
+    id: string;
+    /** Minted for this step alone; it goes back in the body. */
+    token: string;
+    /** The step's own route. */
+    endpoint: string;
+    /** When the step lapses (RFC 3339). */
+    expiresAt: string;
+}
+/**
+ * Posts a step's proof to its route and answers the step as the platform gave
+ * it, with the step's token where the step has one. A refusal is thrown as a
+ * {@link FoirRequestError} carrying the HTTP status and the same error code a
+ * GraphQL refusal carries, so `isFoirUnauthenticated` and the rest read it
+ * alike.
+ */
+export declare function postSignInStep<T>(env: FoirEnv, path: `/v1/${string}`, body: Record<string, unknown>, stepToken?: string): Promise<T>;

package/dist/auth-session.js

@@ -1,13 +1,13 @@
 // src/auth/session-client.ts
 var DEFAULT_SESSION_PATH = "/session/token";
-var DEFAULT_LOGOUT_PATH = "/session/logout";
+var DEFAULT_SIGN_OUT_PATH = "/session/logout";
 var DEFAULT_REFRESH_SKEW_SECONDS = 60;
 var MIN_REFRESH_DELAY_MS = 5e3;
 var CSRF_HEADER = { "X-Foir-Session": "1" };
 function createFoirSessionClient(config) {
   const forApp = config.clientId ? `?client_id=${encodeURIComponent(config.clientId)}` : "";
   const sessionUrl = `${trimSlash(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH}${forApp}`;
-  const logoutUrl = `${trimSlash(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}${forApp}`;
+  const signOutUrl = `${trimSlash(config.loginOrigin)}${config.signOutPath ?? DEFAULT_SIGN_OUT_PATH}${forApp}`;
   const skewMs = (config.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
   let cached = null;
   let inflight = null;
@@ -103,7 +103,7 @@ function createFoirSessionClient(config) {
     },
     async signOut() {
       try {
-        await fetch(logoutUrl, {
+        await fetch(signOutUrl, {
           method: "POST",
           credentials: "include",
           headers: { ...CSRF_HEADER }

package/dist/auth.js

@@ -37,6 +37,18 @@ var MALFORMED_PRUNE_REASONS = /* @__PURE__ */ new Set([
   "subselections_on_scalar",
   "missing_subselections"
 ]);
+function stepUpRequired(error) {
+  if (!(error instanceof FoirRequestError)) return null;
+  for (const item of error.graphQLErrors ?? []) {
+    if (item.extensions?.code !== "STEP_UP_REQUIRED") continue;
+    const kind = item.extensions.stepUp;
+    if (kind === "proof" || kind === "second_factor" || kind === "sign_in_method") {
+      const url = item.extensions.stepUpUrl;
+      return { kind, url: typeof url === "string" && url !== "" ? url : null };
+    }
+  }
+  return null;
+}
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
   status;
@@ -1069,7 +1081,7 @@ async function fetchFoirManifest(config, options = {}) {
 
 // src/auth/ops.ts
 var AUTH_OPS = {
-  // Pre-credential reads a login screen renders itself from.
+  // Pre-credential reads a sign-in screen renders itself from.
   authConfig: "authConfig",
   authProviders: "authProviders",
   defaultAuthProvider: "defaultAuthProvider",
@@ -1081,17 +1093,15 @@ var AUTH_OPS = {
   // they hold. `./access` reads it.
   whoami: "whoami",
   // Methods.
-  login: "login",
+  signIn: "signIn",
   register: "register",
   requestOTP: "requestOTP",
-  loginWithOTP: "loginWithOTP",
   // Session lifecycle.
   refreshToken: "refreshToken",
-  logout: "logout",
+  signOut: "signOut",
   joinWaitlist: "joinWaitlist",
   // Password management and account lifecycle.
   requestPasswordReset: "requestPasswordReset",
-  resetPassword: "resetPassword",
   updatePassword: "updatePassword",
   deleteMyAccount: "deleteMyAccount",
   // Ending their own membership where the request stands.
@@ -1105,10 +1115,10 @@ var AUTH_OPS = {
   mySessions: "mySessions",
   endMySession: "endMySession",
   signOutEverywhere: "signOutEverywhere",
-  // Their email addresses: one added is kept once the code it was sent proves it.
+  // Their email addresses: one added is kept once the code it was sent comes
+  // back on the step addMyAddress answers, on its own route (proveMyAddress).
   myAddresses: "myAddresses",
   addMyAddress: "addMyAddress",
-  proveMyAddress: "proveMyAddress",
   makeMyAddressPrimary: "makeMyAddressPrimary",
   removeMyAddress: "removeMyAddress",
   // A copy of their own data.
@@ -1119,10 +1129,8 @@ var AUTH_OPS = {
   disconnectSignInMethod: "disconnectSignInMethod",
   // Their second factors. A change needs one proven first, by a step-up.
   myFactors: "myFactors",
-  beginStepUp: "beginStepUp",
-  completeStepUp: "completeStepUp",
+  stepUp: "stepUp",
   beginFactorEnrollment: "beginFactorEnrollment",
-  completeFactorEnrollment: "completeFactorEnrollment",
   removeFactor: "removeFactor",
   renameFactor: "renameFactor",
   makeRecoveryCodes: "makeRecoveryCodes",
@@ -1136,13 +1144,7 @@ var AUTH_OPS = {
   // Founding one. Present in a manifest only when the project opted in.
   registerOrganization: "registerOrganization",
   // External identity providers.
-  loginWithProvider: "loginWithProvider",
-  providerCallback: "providerCallback",
-  providerVerifyOTP: "providerVerifyOTP",
-  // A provider sign-in that names an address somebody already holds, waiting
-  // for the code sent to it.
-  confirmProviderLink: "confirmProviderLink",
-  resendProviderLinkCode: "resendProviderLinkCode"
+  signInWithProvider: "signInWithProvider"
 };
 function authClientConfig(env, options) {
   const apiKey = resolveFoirApiKey(env);
@@ -1202,34 +1204,94 @@ function stripUndefined(args) {
   return out;
 }
 
+// src/auth/steps.ts
+async function postSignInStep(env, path, body, stepToken) {
+  const apiUrl = env.PLATFORM_API_URL;
+  if (!apiUrl) {
+    throw new FoirRequestError("[foir] no api url configured: set PLATFORM_API_URL");
+  }
+  const headers = { "Content-Type": "application/json" };
+  if (stepToken) headers["X-Foir-Token"] = stepToken;
+  const res = await fetch(foirApiEndpoint(apiUrl, path), {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const message = typeof data.error === "string" ? data.error : `[foir] POST ${path} failed: HTTP ${res.status}`;
+    const code = typeof data.code === "string" ? data.code : void 0;
+    const extensions = {};
+    if (code) extensions.code = code;
+    if (data.signIn && typeof data.signIn === "object") extensions.signIn = data.signIn;
+    if (data.providerSignIn && typeof data.providerSignIn === "object") extensions.providerSignIn = data.providerSignIn;
+    throw new FoirRequestError(message, {
+      status: res.status,
+      graphQLErrors: Object.keys(extensions).length > 0 ? [{ message, extensions }] : void 0
+    });
+  }
+  return data;
+}
+
 // src/auth/auth.ts
 var TOKEN_KEY = "foir:token";
 var REFRESH_KEY = "foir:refreshToken";
 var USER_ID_KEY = "foir:userId";
 var EMAIL_KEY = "foir:email";
-async function login(env, vars) {
-  return authOp(env, AUTH_OPS.login, vars);
-}
-async function register(env, vars) {
-  return authOp(env, AUTH_OPS.register, vars);
-}
 async function requestOTP(env, email) {
   return authOp(env, AUTH_OPS.requestOTP, { email });
 }
-async function loginWithOTP(env, vars) {
-  return authOp(env, AUTH_OPS.loginWithOTP, vars);
+async function codeSignIn(env, vars) {
+  const signedIn = await postSignInStep(env, `/v1/sign-ins/${encodeURIComponent(vars.step.id)}/code`, { code: vars.otp }, vars.step.token);
+  return {
+    token: signedIn.accessToken ?? "",
+    refreshToken: signedIn.refreshToken ?? "",
+    userId: signedIn.user?.id ?? "",
+    email: signedIn.user?.email ?? ""
+  };
 }
-async function refreshTokens(env, refreshToken) {
+async function rotateTokens(env, refreshToken) {
   return authOp(env, AUTH_OPS.refreshToken, { refreshToken });
 }
-async function loginWithProvider(env, input) {
-  return authOp(env, AUTH_OPS.loginWithProvider, { input });
+async function signInWithProvider(adapter, env, input) {
+  const started = await authOp(
+    env,
+    AUTH_OPS.signInWithProvider,
+    { input }
+  );
+  if (started.step) await adapter.set(PROVIDER_STEP_KEY, JSON.stringify(started.step));
+  else await adapter.unset(PROVIDER_STEP_KEY);
+  return { redirectUrl: started.redirectUrl ?? null };
+}
+async function finishProviderSignIn(adapter, env, input) {
+  const step = await keptProviderStep(adapter, "no provider sign-in was started here: start one before finishing it");
+  return signedInOnStep(adapter, env, step, "provider", {
+    providerKey: input.providerKey,
+    code: input.code,
+    state: input.state
+  });
 }
-async function providerCallback(env, input) {
-  return authOp(env, AUTH_OPS.providerCallback, { input });
+var PROVIDER_STEP_KEY = "foir:providerStep";
+async function keptProviderStep(adapter, missing) {
+  const raw = await adapter.get(PROVIDER_STEP_KEY);
+  if (raw) {
+    try {
+      const step = JSON.parse(raw);
+      if (typeof step.id === "string" && typeof step.token === "string") return step;
+    } catch {
+    }
+  }
+  throw new Error(`[foir] ${missing}`);
 }
-async function providerVerifyOTP(env, input) {
-  return authOp(env, AUTH_OPS.providerVerifyOTP, { input });
+async function signedInOnStep(adapter, env, step, route, body) {
+  const signedIn = await postSignInStep(env, `/v1/sign-ins/${encodeURIComponent(step.id)}/${route}`, body, step.token);
+  await adapter.unset(PROVIDER_STEP_KEY);
+  return saveSession(adapter, {
+    token: signedIn.accessToken ?? "",
+    refreshToken: signedIn.refreshToken ?? "",
+    userId: signedIn.userId ?? "",
+    email: signedIn.email ?? ""
+  });
 }
 function providerSignInRefusalOf(error) {
   if (!(error instanceof FoirRequestError)) return null;
@@ -1252,11 +1314,19 @@ function signInRefusalOf(error) {
   }
   return null;
 }
-async function confirmProviderLink(env, input) {
-  return authOp(env, AUTH_OPS.confirmProviderLink, { input });
+async function confirmProviderLink(adapter, env, input) {
+  const step = await keptProviderStep(adapter, "no provider sign-in is waiting for a code here");
+  return signedInOnStep(adapter, env, step, "link", { pending: input.pending, code: input.code });
 }
-async function resendProviderLinkCode(env, input) {
-  return authOp(env, AUTH_OPS.resendProviderLinkCode, { input });
+async function resendProviderLinkCode(adapter, env, input) {
+  const step = await keptProviderStep(adapter, "no provider sign-in is waiting for a code here");
+  const resent = await postSignInStep(
+    env,
+    `/v1/sign-ins/${encodeURIComponent(step.id)}/link/resend`,
+    { pending: input.pending },
+    step.token
+  );
+  return { pending: resent.pending ?? "" };
 }
 async function getAuthProviders(env) {
   return authOp(env, AUTH_OPS.authProviders);
@@ -1276,8 +1346,14 @@ async function joinWaitlist(env, email) {
 async function requestPasswordReset(env, email, options) {
   return authOp(env, AUTH_OPS.requestPasswordReset, { email, clientId: options?.clientId });
 }
-async function resetPassword(env, vars) {
-  return authOp(env, AUTH_OPS.resetPassword, vars);
+async function redeemPasswordReset(env, vars) {
+  const reset = await postSignInStep(env, "/v1/password-resets/redeem", { token: vars.token, newPassword: vars.newPassword });
+  return {
+    token: reset.accessToken ?? "",
+    refreshToken: reset.refreshToken ?? "",
+    userId: reset.user?.id ?? "",
+    email: reset.user?.email ?? ""
+  };
 }
 async function updatePassword(env, vars, options) {
   return authOp(env, AUTH_OPS.updatePassword, vars, options);
@@ -1290,8 +1366,8 @@ async function myProviderToken(env, providerKey, options) {
   const vars = forceRefresh ? { providerKey, forceRefresh: true } : { providerKey };
   return authOp(env, AUTH_OPS.myProviderToken, vars, rest);
 }
-async function logout(env, options) {
-  return authOp(env, AUTH_OPS.logout, void 0, options);
+async function endSignIn(env, options) {
+  return authOp(env, AUTH_OPS.signOut, void 0, options);
 }
 async function deleteMyAccount(env, vars, options) {
   return authOp(env, AUTH_OPS.deleteMyAccount, vars, options);
@@ -1326,8 +1402,14 @@ async function myAddresses(env, options) {
 async function addMyAddress(env, vars, options) {
   return authOp(env, AUTH_OPS.addMyAddress, vars, options);
 }
-async function proveMyAddress(env, vars, options) {
-  return authOp(env, AUTH_OPS.proveMyAddress, vars, options);
+async function proveMyAddress(env, vars) {
+  const kept = await postSignInStep(env, `/v1/address-proofs/${encodeURIComponent(vars.step.id)}`, { token: vars.step.token, code: vars.code });
+  return {
+    email: kept.address?.email ?? "",
+    primary: kept.address?.primary ?? false,
+    proven: kept.address?.proven ?? false,
+    addedAt: kept.address?.addedAt ?? null
+  };
 }
 async function makeMyAddressPrimary(env, email, options) {
   return authOp(env, AUTH_OPS.makeMyAddressPrimary, { email }, options);
@@ -1350,17 +1432,24 @@ async function disconnectSignInMethod(env, provider, options) {
 async function myFactors(env, options) {
   return authOp(env, AUTH_OPS.myFactors, void 0, options);
 }
-async function beginStepUp(env, password, options) {
-  return authOp(env, AUTH_OPS.beginStepUp, { password }, options);
-}
-async function completeStepUp(env, vars, options) {
-  return authOp(env, AUTH_OPS.completeStepUp, vars, options);
+async function stepUp(env, options) {
+  return authOp(env, AUTH_OPS.stepUp, void 0, options);
 }
 async function beginFactorEnrollment(env, vars, options) {
   return authOp(env, AUTH_OPS.beginFactorEnrollment, vars, options);
 }
-async function completeFactorEnrollment(env, vars, options) {
-  return authOp(env, AUTH_OPS.completeFactorEnrollment, vars, options);
+async function completeFactorEnrollment(env, vars) {
+  const done = await postSignInStep(
+    env,
+    `/v1/factor-enrollments/${encodeURIComponent(vars.step.id)}`,
+    {
+      token: vars.step.token,
+      webauthnAttestationJson: vars.webauthnAttestationJson,
+      totpCode: vars.totpCode,
+      displayName: vars.name
+    }
+  );
+  return done.enrolled === true;
 }
 async function removeFactor(env, vars, options) {
   return authOp(env, AUTH_OPS.removeFactor, vars, options);
@@ -1368,8 +1457,8 @@ async function removeFactor(env, vars, options) {
 async function renameFactor(env, vars, options) {
   return authOp(env, AUTH_OPS.renameFactor, vars, options);
 }
-async function makeRecoveryCodes(env, elevatedHandle, options) {
-  return authOp(env, AUTH_OPS.makeRecoveryCodes, { elevatedHandle }, options);
+async function makeRecoveryCodes(env, options) {
+  return authOp(env, AUTH_OPS.makeRecoveryCodes, void 0, options);
 }
 async function myOrganizations(env, vars, options) {
   return authOp(env, AUTH_OPS.myOrganizations, vars ?? {}, options);
@@ -1406,16 +1495,16 @@ async function getSessionUser(adapter) {
   return { id, email: email ?? "" };
 }
 async function signInWithPassword(adapter, env, vars) {
-  return saveSession(adapter, await login(env, vars));
+  return saveSession(adapter, await authOp(env, AUTH_OPS.signIn, vars));
 }
 async function signUpWithPassword(env, vars) {
-  await register(env, vars);
+  return authOp(env, AUTH_OPS.register, vars);
 }
 async function signInWithOTP(adapter, env, vars) {
-  return saveSession(adapter, await loginWithOTP(env, vars));
+  return saveSession(adapter, await codeSignIn(env, vars));
 }
 async function resetPasswordAndSignIn(adapter, env, vars) {
-  return saveSession(adapter, await resetPassword(env, vars));
+  return saveSession(adapter, await redeemPasswordReset(env, vars));
 }
 async function deleteMyAccountAndSignOut(adapter, env, vars) {
   const result = await authedOp(adapter, env, AUTH_OPS.deleteMyAccount, vars);
@@ -1426,7 +1515,7 @@ async function signOut(adapter, env) {
   const token = await getSessionToken(adapter);
   if (token) {
     try {
-      await logout(env, { bearerToken: token });
+      await endSignIn(env, { bearerToken: token });
     } catch {
     }
   }
@@ -1436,7 +1525,7 @@ async function refreshSession(adapter, env) {
   const refreshToken = await adapter.get(REFRESH_KEY) ?? null;
   if (!refreshToken) return null;
   try {
-    const result = await refreshTokens(env, refreshToken);
+    const result = await rotateTokens(env, refreshToken);
     await saveSession(adapter, result);
     return { token: result.token, refreshToken: result.refreshToken };
   } catch {
@@ -1816,7 +1905,7 @@ async function requireScope(adapter, env, scope) {
 var DEFAULT_COOKIE_NAME = "foir_session";
 var DEFAULT_SESSION_PATH = "/session/token";
 var DEFAULT_END_SESSION_PATH = "/session/end-session";
-function hostedLoginUrl(config, returnTo, options = {}) {
+function hostedSignInUrl(config, returnTo, options = {}) {
   const dest = new URL(config.loginOrigin);
   if (options.signUp) {
     dest.pathname = `${dest.pathname.replace(/\/+$/, "")}/signup`;
@@ -1829,7 +1918,7 @@ function hostedLoginUrl(config, returnTo, options = {}) {
   }
   return dest.toString();
 }
-function hostedLogoutUrl(config, clientId, returnTo) {
+function hostedSignOutUrl(config, clientId, returnTo) {
   const path = config.endSessionPath ?? DEFAULT_END_SESSION_PATH;
   const dest = new URL(path, config.loginOrigin);
   dest.searchParams.set("client_id", clientId);
@@ -2092,14 +2181,14 @@ async function completeSignIn(config, callback, pending) {
 
 // src/auth/session-client.ts
 var DEFAULT_SESSION_PATH2 = "/session/token";
-var DEFAULT_LOGOUT_PATH = "/session/logout";
+var DEFAULT_SIGN_OUT_PATH = "/session/logout";
 var DEFAULT_REFRESH_SKEW_SECONDS = 60;
 var MIN_REFRESH_DELAY_MS = 5e3;
 var CSRF_HEADER = { "X-Foir-Session": "1" };
 function createFoirSessionClient(config) {
   const forApp2 = config.clientId ? `?client_id=${encodeURIComponent(config.clientId)}` : "";
   const sessionUrl = `${trimSlash2(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH2}${forApp2}`;
-  const logoutUrl = `${trimSlash2(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}${forApp2}`;
+  const signOutUrl = `${trimSlash2(config.loginOrigin)}${config.signOutPath ?? DEFAULT_SIGN_OUT_PATH}${forApp2}`;
   const skewMs = (config.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
   let cached = null;
   let inflight = null;
@@ -2195,7 +2284,7 @@ function createFoirSessionClient(config) {
     },
     async signOut() {
       try {
-        await fetch(logoutUrl, {
+        await fetch(signOutUrl, {
           method: "POST",
           credentials: "include",
           headers: { ...CSRF_HEADER }
@@ -2237,11 +2326,9 @@ export {
   authedRequest,
   beginFactorEnrollment,
   beginSignIn,
-  beginStepUp,
   clearSession,
   completeFactorEnrollment,
   completeSignIn,
-  completeStepUp,
   confirmProviderLink,
   connectSignInMethod,
   createFoirSessionClient,
@@ -2253,6 +2340,7 @@ export {
   endMySession,
   exportMyData,
   fetchHostedSession,
+  finishProviderSignIn,
   getAuthConfig,
   getAuthProviders,
   getDefaultAuthProvider,
@@ -2261,15 +2349,11 @@ export {
   getSessionUser,
   hasRole,
   hasScope,
-  hostedLoginUrl,
-  hostedLogoutUrl,
   hostedSignInNoticeOf,
+  hostedSignInUrl,
+  hostedSignOutUrl,
   joinWaitlist,
   leaveMembership,
-  login,
-  loginWithOTP,
-  loginWithProvider,
-  logout,
   makeMyAddressPrimary,
   makeRecoveryCodes,
   myAddresses,
@@ -2281,13 +2365,9 @@ export {
   mySessions,
   mySignInMethods,
   proveMyAddress,
-  providerCallback,
   providerSignInRefusalOf,
-  providerVerifyOTP,
   refreshSession,
   refreshSessionOnce,
-  refreshTokens,
-  register,
   registerOrganization,
   removeFactor,
   removeMyAddress,
@@ -2298,17 +2378,19 @@ export {
   requireRole,
   requireScope,
   resendProviderLinkCode,
-  resetPassword,
   resetPasswordAndSignIn,
   revokeAuthorizedApp,
   saveSession,
   signInRefusalOf,
   signInWithOTP,
   signInWithPassword,
+  signInWithProvider,
   signOut,
   signOutEverywhere,
   signUpWithPassword,
   signupContext,
+  stepUp,
+  stepUpRequired,
   updateMyProfile,
   updatePassword,
   userAccess

package/dist/content/content-renderer.d.ts

@@ -4,7 +4,7 @@
  * It does NOT know any concrete item types. Given a registry that maps each
  * entry `__typename` to a component, it renders a prose flow's entries (or a
  * plain item array): looks each entry up by `__typename`, renders unknown
- * types as null, keys by the entry `_key`/`_id` where one is present, assigns
+ * types as null, keys by the entry `_id` where one is present, assigns
  * LCP `priority` to the first entry that actually renders, and threads a
  * consumer-defined `Ctx` to every component.
  *
@@ -31,8 +31,8 @@ import { type PassageLike } from './richtext';
 /** Minimal shape every entry in a prose flow carries. */
 export interface ItemLike {
     __typename: string;
+    /** The entry's own id. */
     _id?: string | null;
-    _key?: string | null;
 }
 /** Props an item component receives from the content renderer. */
 export interface ItemComponentProps<TItem, TCtx = unknown> {

package/dist/content/richtext.d.ts

@@ -17,7 +17,7 @@
  *   - `list` + `level` flatten list membership onto the passage; consecutive
  *     list passages regroup into <ul>/<ol> with nesting rebuilt from `level`.
  *   - Span marks are the eight decorations (bold, italic, underline,
- *     strikethrough, code, subscript, superscript, highlight) or the `_key`
+ *     strikethrough, code, subscript, superscript, highlight) or the `_id`
  *     of a markDef on the same passage (links, scheme-checked through
  *     `safeHref`).
  *   - A soft line break is `"\n"` inside a span's text.
@@ -64,7 +64,7 @@ export interface ProseSpanLike {
 export interface PassageLike {
     __typename?: string;
     _type?: string;
-    _key?: string | null;
+    _id?: string | null;
     kind?: string | null;
     token?: string | null;
     align?: string | null;

package/dist/content.js

@@ -108,12 +108,12 @@ function PassageList({
             level: minLevel(run),
             tokens: tokenMap
           },
-          run[0]._key ?? `list-${out.length}`
+          run[0]._id ?? `list-${out.length}`
         )
       );
       continue;
     }
-    out.push(renderPassage(passage, passage._key ?? i, tokenMap, fallbackTag));
+    out.push(renderPassage(passage, passage._id ?? i, tokenMap, fallbackTag));
     i++;
   }
   return /* @__PURE__ */ jsx(Fragment, { children: out });
@@ -144,7 +144,7 @@ function ListRun({
         prev.nested = nested;
       } else {
         items.push({
-          key: deep[0]._key ?? `d${items.length}`,
+          key: deep[0]._id ?? `d${items.length}`,
           content: null,
           nested,
           type: deep[0].list ?? "bullet"
@@ -154,7 +154,7 @@ function ListRun({
     }
     const token = passage.token ? tokens.get(passage.token) ?? null : null;
     items.push({
-      key: passage._key ?? `li${items.length}`,
+      key: passage._id ?? `li${items.length}`,
       content: /* @__PURE__ */ jsx("span", { style: tokenToCss(token, passage.align), children: renderSpans(passage) }),
       nested: null,
       type: passage.list ?? "bullet"
@@ -216,7 +216,7 @@ function renderSpan(span, key, markDefs) {
       el = createElement(decorationTag, null, el);
       continue;
     }
-    const def = markDefs.find((d) => d._key === mark);
+    const def = markDefs.find((d) => d._id === mark);
     if (def?.type === "link" && def.href) link = def;
   }
   if (link?.href) {
@@ -273,7 +273,7 @@ function createContentRenderer(registry, options) {
       const priority = !priorityAssigned;
       priorityAssigned = true;
       out.push(
-        /* @__PURE__ */ jsx2(Fragment2, { children: /* @__PURE__ */ jsx2(PassageRun, { passages: run, ctx, priority }) }, run[0]._key ?? `run-${out.length}`)
+        /* @__PURE__ */ jsx2(Fragment2, { children: /* @__PURE__ */ jsx2(PassageRun, { passages: run, ctx, priority }) }, run[0]._id ?? `run-${out.length}`)
       );
       run = [];
     };
@@ -289,7 +289,7 @@ function createContentRenderer(registry, options) {
       const priority = !priorityAssigned;
       priorityAssigned = true;
       out.push(
-        /* @__PURE__ */ jsx2(Fragment2, { children: /* @__PURE__ */ jsx2(Component, { item, block: item, ctx, priority }) }, item._key ?? item._id ?? i)
+        /* @__PURE__ */ jsx2(Fragment2, { children: /* @__PURE__ */ jsx2(Component, { item, block: item, ctx, priority }) }, item._id ?? i)
       );
     });
     flushRun();