@foir/sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -104,8 +104,60 @@ on `dev` would publish unreviewed work to npm.
 
 Changes on `dev` that have not been published to npm.
 
-**The next release is BREAKING** — see `foir.raw()` under "Changed". A MINOR,
-per the pre-1.0 note above.
+---
+
+## [0.9.0] — 2026-08-20
+
+Everything additive, so a MINOR either way under the pre-1.0 note.
+
+### Added
+
+- **`hostedLogoutUrl(config, clientId, returnTo?)` on `./auth`** — the mirror of
+  `hostedLoginUrl`, and the only thing that actually signs a customer out on the
+  hosted-cookie flow.
+
+  Login on that flow is symmetric across browser and server; logout was not.
+  The apex `foir_customer_session` cookie is the durable credential, and
+  disposing of a bearer, clearing a local session, or calling the
+  `customerLogout` mutation all leave it in place — the next request
+  re-establishes the customer from it. The only surface that ended a session was
+  `POST /session/logout`, cookie-authenticated and CSRF-header-gated, which only
+  a browser sending `credentials: 'include'` can reach.
+
+  This is a URL builder: no transport, no CORS surface, no CSRF header, no
+  JavaScript required. Server-side logout becomes
+  `return redirect(hostedLogoutUrl(config, clientId, returnTo))`. `returnTo`
+  must be absolute and on an origin registered for `clientId`.
+
+  Requires the platform's `end-session` endpoint (TTS-1534). `HostedLoginConfig`
+  gains an optional `endSessionPath`, defaulting to `/session/end-session`.
+
+- **`Prose`, `Passage`, `ProseSpan` and `RecordAncestor` on `./data`.** The
+  shapes a prose field and the record hierarchy resolve to, shipped here
+  rather than generated per project because they are identical everywhere —
+  the same reason `Image` and `Reference` live here.
+
+  `Prose<E>` is parameterised on its entries element: `Prose<Passage>` for a
+  text-only field, `Prose<Cta | Passage>` for one that admits embeds. `foir
+  types` fills the parameter in from the field's own member set.
+
+- **`FoirManifestStructural`, and `structurals` on `FoirManifestModel`.** The
+  manifest's bucket for a platform-owned object with no model behind it — a
+  prose wrapper, an `ancestors` list. Absent on a server that predates it,
+  where those fields landed in `unclassifiedFields` and dropped out of the
+  selection entirely; widen on absent.
+
+---
+
+## [0.8.0] — 2026-08-20
+
+**BREAKING** — see `foir.raw()` under "Changed". A MINOR, per the pre-1.0
+note above.
+
+> Filed after the fact. 0.8.0 was published with a version bump and no
+> changelog entry, so everything below sat under "Unreleased" while it was
+> already on npm. Recorded here rather than left there, because a consumer
+> upgrading from 0.7.0 has no other account of what changed.
 
 ### Removed
 

package/dist/auth/hosted.d.ts

@@ -19,12 +19,34 @@ export interface HostedLoginConfig {
     cookieName?: string;
     /** Session-exchange path on the front door. Default `/session/token`. */
     sessionPath?: string;
+    /** RP-initiated logout path on the front door. Default `/session/end-session`. */
+    endSessionPath?: string;
 }
 /**
  * Build the redirect URL to the hosted front door, forwarding a best-effort
  * absolute `returnTo` (honoured if the front door supports it).
  */
 export declare function hostedLoginUrl(config: HostedLoginConfig, returnTo?: string): string;
+/**
+ * Build the redirect URL that ENDS the hosted session — the mirror of
+ * `hostedLoginUrl`, and the only thing that actually signs a customer out on
+ * this flow.
+ *
+ * The cookie is the durable credential. Disposing of a bearer, clearing a
+ * local session, or calling the `customerLogout` mutation (which clears
+ * upstream provider tokens and nothing else) all leave it in place, and the
+ * next request re-establishes the customer from it. This URL points at the
+ * front door's end-session endpoint, which revokes the session row and clears
+ * the cookie before returning the browser to `returnTo`.
+ *
+ * A URL builder, deliberately: no transport, no CORS surface, no CSRF header,
+ * and no JavaScript required at the consumer. Server-side logout is
+ * `return redirect(hostedLogoutUrl(config, clientId, returnTo))`.
+ *
+ * `returnTo` must be an absolute URL on an origin registered for `clientId`;
+ * the platform refuses anything else. Omit it for a bare 204 with no redirect.
+ */
+export declare function hostedLogoutUrl(config: HostedLoginConfig, clientId: string, returnTo?: string): string;
 /** The identity + bearer returned by a successful hosted-session exchange. */
 export interface HostedSession {
     token: string;

package/dist/auth/index.d.ts

@@ -14,7 +14,7 @@ export { customerLogin, customerRegister, customerRequestOTP, customerLoginOTP,
 export type { FoirAuthTokens, FoirCustomer, FoirUser, SessionAdapter, RequireAuthOptions, RequireAdminOptions, } from './auth';
 export { AUTH_OPS } from './ops';
 export type { AuthOpName, AuthOpOptions } from './ops';
-export { hostedLoginUrl, fetchHostedSession } from './hosted';
+export { hostedLoginUrl, hostedLogoutUrl, fetchHostedSession } from './hosted';
 export type { HostedLoginConfig, HostedSession } from './hosted';
 export { createFoirSessionClient } from './session-client';
 export type { FoirSessionClient, FoirSessionConfig, FoirSessionUser, } from './session-client';

package/dist/auth.js

@@ -1111,6 +1111,7 @@ async function requireAdmin(adapter, options) {
 // src/auth/hosted.ts
 var DEFAULT_COOKIE_NAME = "foir_customer_session";
 var DEFAULT_SESSION_PATH = "/session/token";
+var DEFAULT_END_SESSION_PATH = "/session/end-session";
 function hostedLoginUrl(config, returnTo) {
   const dest = new URL(config.loginOrigin);
   if (returnTo && returnTo !== "/") {
@@ -1118,6 +1119,15 @@ function hostedLoginUrl(config, returnTo) {
   }
   return dest.toString();
 }
+function hostedLogoutUrl(config, clientId, returnTo) {
+  const path = config.endSessionPath ?? DEFAULT_END_SESSION_PATH;
+  const dest = new URL(path, config.loginOrigin);
+  dest.searchParams.set("client_id", clientId);
+  if (returnTo) {
+    dest.searchParams.set("post_logout_redirect_uri", returnTo);
+  }
+  return dest.toString();
+}
 async function fetchHostedSession(request, config) {
   const cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
   const sessionPath = config.sessionPath ?? DEFAULT_SESSION_PATH;
@@ -1313,6 +1323,7 @@ export {
   getSessionCustomer,
   getSessionToken,
   hostedLoginUrl,
+  hostedLogoutUrl,
   loginWithOTP,
   loginWithPassword,
   myProviderToken,

package/dist/data/builtins.d.ts

@@ -132,6 +132,73 @@ export interface Richtext {
     json: FoirJsonValue | null;
     markdown: string | null;
 }
+/**
+ * One run of styled text inside a passage.
+ *
+ * `marks` are named — `strong`, `em`, `code`, or a key into the passage's
+ * `markDefs` for anything that carries data (a link, and nothing else today).
+ * The bitmask the old editor stored is gone.
+ */
+export interface ProseSpan {
+    __typename?: 'ProseSpan';
+    text: string | null;
+    marks: Array<string | null> | null;
+}
+/**
+ * A text entry in a prose flow — a paragraph, a heading, a quote, a list item.
+ *
+ * `kind` is the semantic shape and `token` is the design-token override that
+ * beats it when set. `list` + `level` carry list nesting flat rather than as a
+ * tree. A soft break inside a passage is a `\n` in a span's text, not a
+ * separate entry.
+ *
+ * `markDefs` stays an open JSON leaf by declaration: def types are extensible,
+ * and a typed object over an open shape would drop what it does not know.
+ */
+export interface Passage {
+    __typename?: 'Passage';
+    _key: string | null;
+    kind: string | null;
+    token: string | null;
+    align: string | null;
+    list: string | null;
+    level: number | null;
+    language: string | null;
+    spans: Array<ProseSpan | null> | null;
+    markDefs: FoirJsonValue | null;
+}
+/**
+ * A prose field's read projection.
+ *
+ * `entries` is the typed reading and the one that keeps prose structured —
+ * `Passage` for a text-only field, and a union of `Passage` with the field's
+ * admitted embeds for one that places models. `html` and `markdown` are the
+ * passages only: an embed is omitted from both BY DECLARATION rather than
+ * rendered as invented markup, so a consumer that wants the embeds reads
+ * `entries`. `json` is the declared flow verbatim — the lossless escape hatch
+ * where an entry nobody recognises always survives.
+ *
+ * `E` is the entries element, filled in per field by `foir types`.
+ */
+export interface Prose<E = Passage> {
+    html: string | null;
+    markdown: string | null;
+    json: FoirJsonValue | null;
+    entries: Array<E | null> | null;
+}
+/**
+ * One ancestor of a hierarchy record, root-first.
+ *
+ * Identity only, by design: a child's public URL already exposes every
+ * ancestor's slug, so the walk never widens content visibility. Anything more
+ * than identity goes through the `parent` reference like any other read.
+ */
+export interface RecordAncestor {
+    __typename?: 'RecordAncestor';
+    _id: string;
+    _naturalKey: string | null;
+    _modelKey: string | null;
+}
 /**
  * A reference whose target model is not pinned by the field's declaration.
  *

package/dist/data/index.d.ts

@@ -44,12 +44,12 @@
 export { createFoirClient, createFoirClientFromEnv } from './client';
 export type { FoirClient, FoirClientCore, FoirModelClient, FoirNamespaceClient } from './client';
 export { fetchFoirManifest } from './manifest';
-export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManifestNamespace, FoirManifestOp, FoirManifestOpPayload, FoirManifestRelation, FoirManifestScalar, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionMember, FoirManifestSelectionUnion, FoirManifestSubscription, FoirManifestSubscriptionArgScope, FoirManifestUnclassifiedField, } from './manifest';
+export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManifestNamespace, FoirManifestOp, FoirManifestOpPayload, FoirManifestRelation, FoirManifestScalar, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionMember, FoirManifestSelectionUnion, FoirManifestStructural, FoirManifestSubscription, FoirManifestSubscriptionArgScope, FoirManifestUnclassifiedField, } from './manifest';
 export { planFoirModelCall, planFoirNamespaceCall } from './document';
 export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
 export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
 export type { FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
-export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Reference, Richtext, Video, } from './builtins';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
 /**
  * Pre-TTS-1391 spellings. The `<Name>Block` wrappers and the `<Name>Value`
  * split are the same thing as the types above — an item IS its value — so each

package/dist/data/manifest.d.ts

@@ -139,6 +139,23 @@ export interface FoirManifestOpPayload {
      */
     error?: string;
 }
+/**
+ * A platform-owned structural field: a prose wrapper, or the hierarchy walk's
+ * `ancestors`. Nested and always returned, like a composite — but there is no
+ * model behind it, so the entry names its TYPE (`Prose`, `ProseCta`,
+ * `RecordAncestor`) and the shape is `builtins.ts`'s.
+ *
+ * ABSENT on a server that predates the bucket, where these fields landed in
+ * `unclassifiedFields` and dropped out of the selection entirely. Widen on
+ * absent, as everywhere else in this file.
+ */
+export interface FoirManifestStructural {
+    key: string;
+    type: string;
+    list: boolean;
+    nullable: boolean;
+    deprecated?: boolean;
+}
 /** A built field the projection has no bucket for. Reported rather than dropped. */
 export interface FoirManifestUnclassifiedField {
     key: string;
@@ -172,12 +189,14 @@ export interface FoirManifestModel {
     scalars: FoirManifestScalar[];
     relations: FoirManifestRelation[];
     composites: FoirManifestComposite[];
+    /** Platform-owned structural fields — prose wrappers, `ancestors`. */
+    structurals?: FoirManifestStructural[];
     /**
-     * Block-union field key → member model keys. Members that are built-in block
-     * primitives appear under their lowercase token (`text`, `image`, `video`,
-     * `file`, `richtext`, `media`, `reference`, `flexible`) and have NO entry in
-     * `models` — they are platform-owned, identical in every project, and typed
-     * statically by `builtins.ts`.
+     * Union field key → member model keys. Members that are platform primitives
+     * appear under their lowercase token (`richtext`, `image`, `video`, `file`,
+     * `reference`, `geopoint`) and have NO entry in `models` — they are
+     * platform-owned, identical in every project, and typed statically by
+     * `builtins.ts`.
      */
     unions?: Record<string, string[]>;
     /** Op names of this model's typed lookups. Each also appears in `ops`. */

package/package.json

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