@foir/sdk 0.4.0 → 0.7.0

package/dist/content/richtext.d.ts

@@ -0,0 +1,70 @@
+/**
+ * RichTextRenderer — render a Foir richtext field (a Lexical EditorState) with
+ * per-paragraph typography tokens applied as inline styles.
+ *
+ * The design-token dependency is INJECTED, not imported from an app: pass the
+ * resolved `typography` token array as a prop, or provide it once via
+ * `<RichTextTypographyProvider>`. With no tokens the structure still renders
+ * (fallback tag, no inline typography), and a doc-less value falls back to its
+ * `html` projection. No `@foir`-app imports.
+ *
+ * Token semantics:
+ *   - `token.tag` (paragraph / h1–h6 / blockquote) controls the rendered HTML
+ *     element and wins over the Lexical heading `tag` when both are present.
+ *   - Paragraph `format` ('left'|'center'|'right'|'justify') → text-align.
+ *   - Text-node `format` bits → inline emphasis: bold(1) italic(2)
+ *     strikethrough(4) underline(8) code(16).
+ */
+import { type ReactNode, type JSX } from 'react';
+/**
+ * safeHref allow-lists link schemes so stored richtext can't smuggle a
+ * `javascript:` (or `data:`/`vbscript:`) URL that executes on click (EID-207).
+ * Relative URLs, anchors, and the http(s)/mailto/tel schemes pass; anything
+ * else collapses to '#'. Editors are not fully trusted, so this runs on the
+ * structured render path, not only the html fallback.
+ */
+export declare function safeHref(url: string | undefined): string;
+/** A resolved typography token from the project's design tokens. */
+export interface TypographyToken {
+    /** Token key referenced by a Lexical node's `style`. */
+    name: string;
+    /** Rendered HTML element (paragraph / h1–h6 / blockquote). */
+    tag?: string;
+    value: {
+        fontFamily: string[];
+        fontSize: string | number;
+        fontWeight: string | number;
+        lineHeight: string | number;
+        letterSpacing: string | number;
+        textTransform?: string;
+    };
+}
+/**
+ * Provide the project's resolved typography tokens to every nested
+ * `<RichTextRenderer>` so callers don't thread them through each usage. A
+ * `tokens` prop on the renderer still takes precedence.
+ */
+export declare function RichTextTypographyProvider({ tokens, children, }: {
+    tokens: TypographyToken[];
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Read the injected typography tokens (null when no provider is mounted). */
+export declare function useRichTextTypography(): TypographyToken[] | null;
+interface RichtextValueLike {
+    html?: string | null;
+    json?: unknown;
+}
+export interface RichTextRendererProps {
+    value: RichtextValueLike | null | undefined;
+    className?: string;
+    /**
+     * Resolved typography tokens. Overrides any provided via
+     * `<RichTextTypographyProvider>`. When neither is set, paragraphs render
+     * with `fallbackTag` and no inline typography.
+     */
+    tokens?: TypographyToken[];
+    /** Tag used for any paragraph with no token style and no Lexical tag. */
+    fallbackTag?: keyof JSX.IntrinsicElements;
+}
+export declare function RichTextRenderer({ value, className, tokens, fallbackTag, }: RichTextRendererProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/data/builtins.d.ts

@@ -0,0 +1,296 @@
+/**
+ * The platform-owned types `foir types` does NOT generate.
+ *
+ * Two closed sets live here, and they are here rather than in the generated
+ * file for the same reason: they are identical in every project, so generating
+ * them per project would emit the same 200 lines into every consumer's repo and
+ * give four projects four chances to disagree about `ImageValue`.
+ *
+ *  1. **Value objects.** `GET /v1/manifest` reports a scalar's `type` as a
+ *     GraphQL named type, and eight of the names it can use are platform-owned
+ *     objects rather than leaves: `ImageValue`, `VideoValue`, `FileValue`,
+ *     `MediaValue`, `RichtextValue`, `GeoPointValue`, `ReferenceValue`,
+ *     `CollabInfo`. They are structurally nested but behave as leaves — always
+ *     present, never lazily hydrated, never `include`-able.
+ *
+ *  2. **Block primitives.** A block union's members are *model keys*, except
+ *     for eight lowercase tokens — `text`, `image`, `video`, `file`,
+ *     `richtext`, `media`, `reference`, `flexible` — which are members of the
+ *     real GraphQL union but have **no entry in `models`**. On the live dev
+ *     Marketing project, 7 of `tilly_page.blocks`'s 29 members are these. A
+ *     generator that resolved every member to `models[key]` would skip them
+ *     (an inexhaustive union, silently wrong at runtime) or emit `never`.
+ *
+ * Both sets are the manifest's own prescription, not this file's invention: the
+ * payload reference says of the value objects that a client "ships static types
+ * for them rather than generating them per project", and names the eight block
+ * tokens as having no `models` entry by design.
+ *
+ * ---------------------------------------------------------------------------
+ * The obligation that comes with a static table
+ * ---------------------------------------------------------------------------
+ *
+ * This IS a mirror of a platform-side table, and mirrors drift. What keeps it
+ * honest is that the generator refuses to guess: a union member key that is
+ * neither in `models` nor in this table makes `foir types` fail loudly naming
+ * the member, rather than emitting a union that silently lacks a branch. So the
+ * failure mode of drift is a red build with the missing name in it.
+ *
+ * `apps/cli/src/lib/__tests__/types-codegen.test.ts` asserts that against both
+ * committed live-captured manifests.
+ *
+ * Field shapes verified against deployed dev's introspection on 2026-07-28 and
+ * against `api-public/internal/schema/field_mapping.go`.
+ */
+/** A `JSON` scalar. Deliberately not `any`: reading through it needs a check. */
+export type FoirJsonValue = string | number | boolean | null | FoirJsonValue[] | {
+    [key: string]: FoirJsonValue;
+};
+export type ImageFormat = 'WEBP' | 'AVIF' | 'JPEG' | 'PNG';
+/** One rendition of an image at a named tier, in a single format. */
+export interface ImageVariant {
+    size: string;
+    format: ImageFormat;
+    url: string;
+    width: number | null;
+    height: number | null;
+}
+/**
+ * The curated tier set for one format. `_2xl`/`_3xl`/`_4xl` carry the
+ * underscore because a GraphQL identifier cannot start with a digit.
+ */
+export interface ImageVariantSet {
+    thumbnail: ImageVariant | null;
+    small: ImageVariant | null;
+    medium: ImageVariant | null;
+    large: ImageVariant | null;
+    xlarge: ImageVariant | null;
+    _2xl: ImageVariant | null;
+    _3xl: ImageVariant | null;
+    _4xl: ImageVariant | null;
+}
+export interface ImageValue {
+    url: string;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    blurhash: string | null;
+    dominantColor: string | null;
+    mimeType: string | null;
+    fileSize: number | null;
+    focalPoint: FoirJsonValue | null;
+    crop: FoirJsonValue | null;
+    variants: ImageVariantSet | null;
+    /** WebP tier set (universal support). Pair with `avif` in a `<picture>`. */
+    webp: ImageVariantSet | null;
+    /** AVIF tier set (smaller, narrower support). The preferred `<picture>` source. */
+    avif: ImageVariantSet | null;
+}
+export interface VideoValue {
+    url: string;
+    thumbnailUrl: string | null;
+    previewUrl: string | null;
+    hlsManifestUrl: string | null;
+    width: number | null;
+    height: number | null;
+    duration: number | null;
+    blurhash: string | null;
+    dominantColor: string | null;
+    mimeType: string | null;
+    fileSize: number | null;
+}
+export interface FileValue {
+    url: string | null;
+    filename: string | null;
+    mimeType: string | null;
+    size: number | null;
+}
+export interface GeoPointValue {
+    lat: number | null;
+    lng: number | null;
+}
+export interface RichtextValue {
+    html: string | null;
+    json: FoirJsonValue | null;
+    markdown: string | null;
+}
+/**
+ * A foreign key, and the reason a consumer never writes `include` to get one:
+ * this arrives with the record, complete, under the complete-by-default
+ * selection model. `post.author._id` is always there and always typed present.
+ */
+export interface ReferenceValue {
+    _id: string | null;
+    _type: string | null;
+    _schema: string | null;
+    naturalKey: string | null;
+    _preview: FoirJsonValue | null;
+}
+/** Inline media embedded in a content field — polymorphic per `mediaType`. */
+export interface MediaValue {
+    mediaType: string | null;
+    url: string | null;
+    mimeType: string | null;
+    fileId: string | null;
+    fileSize: number | null;
+    filename: string | null;
+    width: number | null;
+    height: number | null;
+    blurhash: string | null;
+    dominantColor: string | null;
+    duration: number | null;
+    hlsManifestUrl: string | null;
+    previewUrl: string | null;
+    thumbnailUrl: string | null;
+    variants: FoirJsonValue | null;
+    crop: FoirJsonValue | null;
+    focalPoint: FoirJsonValue | null;
+}
+/** Collaborative-editing discovery. */
+export interface CollabInfo {
+    enabled: boolean;
+    wsUrl: string;
+    roomName: string;
+}
+/**
+ * The metadata every block member carries, and the two discriminants an
+ * exhaustive `switch` narrows on.
+ *
+ * `__typename` is the one to prefer. The op compiler emits it on the union's
+ * own selection set for every union it expands, and it is the only field that
+ * cannot be `omit`ed (no omit path can name it). `_type` is the foir block-type
+ * token — the model key for a model-derived member, the lowercase primitive
+ * token otherwise — and is deliberately NOT protected from `omit` by the
+ * server, so a caller who omits it loses the second discriminant while keeping
+ * the first.
+ */
+export interface FoirBlockMeta<TType extends string, TTypename extends string> {
+    __typename: TTypename;
+    _type: TType;
+    _id: string | null;
+    _key: string | null;
+    _label: string | null;
+}
+export interface RichtextBlock extends FoirBlockMeta<'richtext', 'RichtextBlock'>, RichtextValue {
+}
+export interface ImageBlock extends FoirBlockMeta<'image', 'ImageBlock'>, Omit<ImageValue, 'url'> {
+    /**
+     * Nullable here, `String!` on `ImageValue`. Wrapping a value type as a block
+     * drops NonNull (`wrapValueFieldsAsBlock`), and reporting it non-null would
+     * be a lie a consumer's generated types cannot recover from.
+     */
+    url: string | null;
+}
+export interface VideoBlock extends FoirBlockMeta<'video', 'VideoBlock'>, Omit<VideoValue, 'url'> {
+    /** Nullable here, `String!` on `VideoValue` — see `ImageBlock.url`. */
+    url: string | null;
+}
+export interface FileBlock extends FoirBlockMeta<'file', 'FileBlock'>, FileValue {
+}
+export interface MediaBlock extends FoirBlockMeta<'media', 'MediaBlock'>, MediaValue {
+}
+export interface TextBlock extends FoirBlockMeta<'text', 'TextBlock'> {
+    value: string | null;
+}
+/**
+ * A reference to another record.
+ *
+ * `record` is the resolved target, over the project's `Record` union — every
+ * model in the project. It is left as a type parameter so the generated file
+ * can name that union; the default is the honest answer for a consumer who has
+ * not narrowed it.
+ */
+export interface ReferenceBlock<TRecord = FoirUnexpandedRecord> extends FoirBlockMeta<'reference', 'ReferenceBlock'>, Omit<ReferenceValue, '_id' | '_type'> {
+    record: TRecord | null;
+}
+/**
+ * The fallback member, for a `flexible` field in a project with no block types
+ * to offer. Its `_type` is whatever the stored value carried, so — uniquely
+ * among the primitives — it is not a literal.
+ */
+export interface FlexibleBlock {
+    __typename: 'FlexibleBlock';
+    _type: string | null;
+    _id: string | null;
+    _key: string | null;
+    _label: string | null;
+    value: FoirJsonValue | null;
+}
+/**
+ * What a nested union or a re-entered object resolves to.
+ *
+ * The op compiler enforces a termination rule — *never expand a type, object or
+ * union, that is already on the current path; degrade it to `__typename`
+ * instead* — because `Block` contains members that contain `Block`, and a
+ * `tilly_page.blocks → TillyPageBlock.blocks` cycle is reachable in two hops
+ * with no `include` and no caller input at all. At a degraded position the
+ * response carries `__typename` and nothing else, so that is what the generated
+ * type says. Reach the rest with `foir.raw()`.
+ */
+export interface FoirDegraded<TTypename extends string = string> {
+    __typename: TTypename;
+}
+/** A `Record`-union value the compiler did not expand. See `FoirDegraded`. */
+export type FoirUnexpandedRecord = FoirDegraded;
+/**
+ * The results of the ops that do NOT return the model.
+ *
+ * `foir types` classifies these as `opaque`, so the client offers no
+ * `include` / `omit` for them and uses the type below verbatim. They are here
+ * for the same reason the value objects are: platform-owned, fixed, and
+ * identical in every project.
+ */
+export type FoirVisibility = 'PRIVATE' | 'PUBLIC';
+export type FoirAccessLevel = 'READ' | 'WRITE' | 'DELETE';
+export type FoirAccessSource = 'PUBLIC' | 'OWNER' | 'GRANT' | 'ROLE';
+export type FoirGranteeKind = 'CUSTOMER' | 'ADMIN';
+/** `myAccess` — this principal's effective access to one record. */
+export interface FoirMyAccess {
+    access: FoirAccessLevel;
+    source: FoirAccessSource;
+}
+export interface FoirAccessGrant {
+    access: FoirAccessLevel;
+    createdAt: string;
+    granteeId: string;
+    granteeKind: FoirGranteeKind;
+}
+export interface FoirAccessor {
+    access: FoirAccessLevel;
+    granteeId: string;
+    granteeKind: FoirGranteeKind;
+    source: FoirAccessSource;
+}
+/** `access` — the full ACL of one record. */
+export interface FoirResourceAccess {
+    accessors: FoirAccessor[];
+    grants: FoirAccessGrant[];
+    public: boolean;
+    visibility: FoirVisibility;
+}
+/** `updateMany` — how many rows moved, and which. */
+export interface FoirUpdateManyPayload {
+    count: number;
+    ids: string[];
+}
+export type FoirDeviceType = 'DESKTOP' | 'MOBILE' | 'TABLET';
+export type FoirPlatformType = 'IOS' | 'ANDROID' | 'WEB';
+/**
+ * The `contexts` argument on every typed read.
+ *
+ * **It is an object, not a list**, despite the plural name — `ResolveContextInput`
+ * on the wire, verified against deployed dev's introspection on both projects:
+ * `contexts: ResolveContextInput` with no LIST wrapper, four optional fields.
+ *
+ * Worth the paragraph because the plural reads like `string[]` and typing it
+ * that way compiles fine and then sends a body the server rejects. The
+ * `FoirSchemaDefinition` sketch in `schema.ts` had exactly that error, and it
+ * was found by the docs lane running the call rather than by anyone reading the
+ * contract.
+ */
+export interface FoirResolveContext {
+    device?: FoirDeviceType | null;
+    locale?: string | null;
+    platform?: FoirPlatformType | null;
+    preview?: boolean | null;
+}

package/dist/data/client.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `createFoirClient` — the typed data client.
+ *
+ * ```ts
+ * import { createFoirClient } from '@foir/sdk/data';
+ * import { type FoirSchema, foirSchemaVersion } from './foir.generated';
+ *
+ * const foir = createFoirClient<FoirSchema>({
+ *   apiUrl: process.env.PLATFORM_API_URL!,
+ *   apiKey: process.env.PLATFORM_API_KEY!,
+ *   schemaVersion: foirSchemaVersion,
+ * });
+ *
+ * const block = await foir.tilly_block.findUnique({
+ *   id: 'a3pr8x0j10rigx8u6t1xthbr',
+ *   include: { noteId: true },
+ *   omit: ['aiSummary'],
+ * });
+ * ```
+ *
+ * ---------------------------------------------------------------------------
+ * Why this is a Proxy
+ * ---------------------------------------------------------------------------
+ *
+ * `FoirSchema` is a TYPE. `foir types` emits interfaces, and interfaces do not
+ * exist at runtime, so the client is handed the full shape of the API at
+ * compile time and nothing at all at run time. There is no model list to build
+ * an object from — `foir.tilly_block.findMany` has to be resolved when it is
+ * reached. A two-level `Proxy` does that in a few lines and costs one property
+ * lookup per call.
+ *
+ * The alternative — fetching `/v1/manifest` at construction — would put a
+ * round trip in front of the first query on every cold edge invocation, to
+ * learn something the types already know.
+ *
+ * ---------------------------------------------------------------------------
+ * Why namespaces live under `.ns`
+ * ---------------------------------------------------------------------------
+ *
+ * `POST /v1/query` takes `model` OR `namespace`, never both, and refuses the
+ * request if you send both. Since there is no runtime schema (above), the
+ * client cannot tell which one `foir.search` means. So the addressing carries
+ * it: `foir.<model>.<op>()` sends `model`, `foir.ns.<namespace>.<op>()` sends
+ * `namespace`. `ns` and `raw` are therefore reserved top-level names.
+ */
+import type { FoirModelDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirSchemaDefinition } from './schema';
+import type { FoirModelOperation, FoirNamespaceOperation } from './selection';
+import { type FoirEnv } from '../transport/foir-http';
+import { type FoirClientConfig, type FoirRawOp } from './transport';
+/** The ops available on one model for this credential. */
+export type FoirModelClient<S extends FoirSchemaDefinition, M extends FoirModelDefinition> = {
+    [OK in keyof M['ops']]: M['ops'][OK] extends FoirOpDefinition ? FoirModelOperation<S, M, M['ops'][OK]> : never;
+};
+export type FoirNamespaceClient<N extends {
+    ops: object;
+}> = {
+    [OK in keyof N['ops']]: N['ops'][OK] extends FoirNamespaceOpDefinition ? FoirNamespaceOperation<N['ops'][OK]> : never;
+};
+export interface FoirClientCore<S extends FoirSchemaDefinition> {
+    /**
+     * Non-model root namespaces (`search`, `customers`, `notifications`).
+     * Separate accessor because the wire distinguishes `model` from `namespace`
+     * and the client has no runtime schema to disambiguate with.
+     */
+    readonly ns: {
+        [NK in keyof S['namespaces']]: FoirNamespaceClient<S['namespaces'][NK]>;
+    };
+    /**
+     * Untyped passthrough to `POST /v1/query`.
+     *
+     * Every generated-type system needs an escape hatch; shipping one
+     * deliberately is better than people forking the client when the generated
+     * types cannot express something. Returns the single root field, same as a
+     * typed call, and throws the same `FoirRequestError`.
+     */
+    raw<T = unknown>(op: FoirRawOp): Promise<T>;
+}
+/**
+ * The client, shaped by the credential's manifest. An op that is not in
+ * `FoirSchema` is not on this type, so `foir.tilly_block.create(...)` under a
+ * read-only `pk_` key is a compile error rather than a 400.
+ */
+export type FoirClient<S extends FoirSchemaDefinition> = FoirClientCore<S> & {
+    [MK in keyof S['models']]: FoirModelClient<S, S['models'][MK]>;
+};
+export declare function createFoirClient<S extends FoirSchemaDefinition>(config: FoirClientConfig): FoirClient<S>;
+/**
+ * `createFoirClient` from the `PLATFORM_API_URL` / `PLATFORM_API_KEY` /
+ * `FOIR_PREVIEW` convention `@foir/sdk/client` already uses, so a storefront
+ * that has an env wired for GraphQL can add the data client without a second
+ * set of variables. Preview picks the `sk_` `PLATFORM_PREVIEW_API_KEY` and the
+ * draft schema channel, exactly as `foirRequest` does.
+ */
+export declare function createFoirClientFromEnv<S extends FoirSchemaDefinition>(env: FoirEnv, overrides?: Omit<FoirClientConfig, 'apiUrl' | 'apiKey' | 'channel'>): FoirClient<S>;

package/dist/data/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `@foir/sdk/data` — the typed data client.
+ *
+ * A second app-runtime transport alongside `@foir/sdk/client`'s GraphQL one,
+ * shaped by the credential you hand it. `POST /v1/query` takes a JSON op and
+ * the server compiles it to a GraphQL document, so both surfaces run through
+ * the same executor, the same scope checks, the same response cache — the SDK
+ * surface is a projection of `SchemaForCaller(scopes)`, never a parallel
+ * construction.
+ *
+ * What you get over the GraphQL path: no `.graphql` documents, no
+ * `graphql-codegen` step, and **no `graphql` dependency at all**. This subpath
+ * imports neither `graphql` nor `@graphql-typed-document-node/core`; the import
+ * graph is asserted graphql-free by `__tests__/data.test.ts`
+ * ("`@foir/sdk/data` has zero graphql dependency").
+ *
+ * `./data` and not `./client` because `./client` is the editor-iframe/GraphQL
+ * transport and is already published.
+ *
+ * ```ts
+ * import { createFoirClient } from '@foir/sdk/data';
+ * import { type FoirSchema, foirSchemaVersion } from './foir.generated';
+ *
+ * const foir = createFoirClient<FoirSchema>({
+ *   apiUrl: 'https://api.foir.dev',
+ *   apiKey: process.env.PLATFORM_API_KEY!,
+ *   schemaVersion: foirSchemaVersion,
+ * });
+ *
+ * const page = await foir.page.findUnique({
+ *   naturalKey: 'home',
+ *   include: { author: true },
+ *   omit: ['bodyRichtext'],
+ * });
+ *
+ * const results = await foir.ns.search.searchRecords({ query: 'shoes' });
+ * const anything = await foir.raw({ model: 'page', op: 'findMany', args: { first: 5 } });
+ * ```
+ *
+ * `FoirSchema` comes from `foir types` (TTS-875). The contract it generates
+ * against is written down in `schema.ts` — read that file before changing
+ * anything here, because a generator is written against it.
+ */
+export { createFoirClient, createFoirClientFromEnv } from './client';
+export type { FoirClient, FoirClientCore, FoirModelClient, FoirNamespaceClient } from './client';
+export { fetchFoirManifest } from './manifest';
+export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManifestNamespace, FoirManifestOp, FoirManifestRelation, FoirManifestScalar, FoirManifestUnclassifiedField, } from './manifest';
+export type { CollabInfo, FileBlock, FileValue, FlexibleBlock, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirBlockMeta, FoirDegraded, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPointValue, ImageBlock, ImageFormat, ImageValue, ImageVariant, ImageVariantSet, MediaBlock, MediaValue, ReferenceBlock, ReferenceValue, RichtextBlock, RichtextValue, TextBlock, VideoBlock, VideoValue, } from './builtins';
+export { foirDataEndpoint } from './transport';
+export type { FoirClientConfig, FoirRawOp, FoirSchemaDrift } from './transport';
+export type { FoirConnection, FoirFieldsShape, FoirModelDefinition, FoirNamespaceDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirRelationDefinition, FoirReturnDefinition, FoirSchemaDefinition, } from './schema';
+export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmittableKey, FoirOpResult, FoirQuery, FoirRecordResult, } from './selection';
+export { FoirRequestError } from '../transport/foir-http';
+export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, } from '../transport/foir-http';

package/dist/data/manifest.d.ts

@@ -0,0 +1,161 @@
+/**
+ * `GET /v1/manifest` — the per-caller surface descriptor, as a runtime type.
+ *
+ * This is the *runtime* mirror of `schema.ts`'s compile-time contract: what the
+ * server actually sends, verbatim, so `foir types` (TTS-875) has a typed thing
+ * to read and the drift check has a version to compare. The manifest is already
+ * the projection of `CachedSchema.SchemaForCaller(scopes)`, so what it lists is
+ * exactly what this credential may do — no client-side filtering anywhere.
+ *
+ * Shape verified against deployed dev on 2026-07-28, against two live keys
+ * (an unnarrowed one over 7 models, and one narrowed to a single model whose
+ * `tilly_page.blocks` union carries 29 members). The buckets below are the
+ * platform's `Manifest` struct
+ * (`api-public/internal/schema/manifest.go`) field for field; where the two
+ * disagree the platform is right and this file is the bug.
+ */
+import { type FoirClientConfig } from './transport';
+export interface FoirManifestScalar {
+    key: string;
+    /**
+     * GraphQL named type: a scalar (`String`, `Float`, `Boolean`, `ID`,
+     * `DateTime`, `JSON`), a generated enum (then `enumValues` is set), or one of
+     * the closed set of platform-owned value objects (`ImageValue`, `VideoValue`,
+     * `FileValue`, `MediaValue`, `RichtextValue`, `GeoPointValue`,
+     * `ReferenceValue`, `CollabInfo`) — see `builtins.ts`.
+     */
+    type: string;
+    /**
+     * Mirrors the EXECUTABLE schema, NOT the model's `required` flag. The schema
+     * generator deliberately never emits NonNull for a user field, so a
+     * `required: true` field still reports `nullable: true`. Reporting otherwise
+     * would be the lie a consumer's generated types cannot recover from.
+     */
+    nullable: boolean;
+    list: boolean;
+    /** Enum value NAMES (what the wire carries). Set only when `type` names an enum. */
+    enumValues?: string[];
+    /**
+     * A soft-deleted field, still in the executable schema for its 30-day grace
+     * window and always resolving null. Reported rather than dropped so an
+     * in-flight client query still type-checks.
+     */
+    deprecated?: boolean;
+}
+export interface FoirManifestRelation {
+    key: string;
+    /** Model key of the relation's target. Absent for a polymorphic reference. */
+    target?: string;
+    /** Member model keys, for a polymorphic reference (a `Ref` union over ≥2 models). */
+    targets?: string[];
+    list: boolean;
+    /** A Relay connection (the association-inverse shape) rather than a plain list. */
+    connection?: boolean;
+    nullable: boolean;
+    deprecated?: boolean;
+}
+/**
+ * An embedded (inline) model field: `seo`, `page_content`, `section`.
+ *
+ * Its own bucket because neither of the other two fits — always returned like
+ * a scalar, structurally nested like a relation, and never `include`-able.
+ */
+export interface FoirManifestComposite {
+    key: string;
+    /** The embedded model's key. Its shape is in `models`. */
+    target: string;
+    list: boolean;
+    nullable: boolean;
+    deprecated?: boolean;
+}
+export interface FoirManifestOp {
+    /** GraphQL root field this op compiles to, e.g. `tillyBlocks`. */
+    field: string;
+    args?: string[];
+    /** True when the field lives on the Mutation root. */
+    mutation?: boolean;
+}
+/** A built field the projection has no bucket for. Reported rather than dropped. */
+export interface FoirManifestUnclassifiedField {
+    key: string;
+    type: string;
+    list: boolean;
+}
+export interface FoirManifestModel {
+    typeName: string;
+    /**
+     * `record` for a record-bearing model, `embedded` for an inline model.
+     * Embedded models never carry `ops` — they exist in the payload only because
+     * a composite or a block union names them.
+     */
+    kind: string;
+    /**
+     * Present ⇔ the corresponding root field is in this caller's variant.
+     * ABSENT ENTIRELY on an embedded model, and on a record model no op of which
+     * survived pruning — hence optional, not `{}`.
+     */
+    ops?: Record<string, FoirManifestOp>;
+    scalars: FoirManifestScalar[];
+    relations: FoirManifestRelation[];
+    composites: FoirManifestComposite[];
+    /**
+     * 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`.
+     */
+    unions?: Record<string, string[]>;
+    /** Op names of this model's typed lookups. Each also appears in `ops`. */
+    lookups?: string[];
+    unclassifiedFields?: FoirManifestUnclassifiedField[];
+    cacheControl?: {
+        scope: string;
+        maxAge?: number;
+    };
+}
+/**
+ * One built-in non-model surface.
+ *
+ * `queries` / `mutations` hold ROOT FIELD NAMES, and for every namespace but
+ * one the op name a caller sends IS that root field name — the server matches
+ * on it and constructs nothing (`resolveNamespaceRoot`).
+ *
+ * `operations` is the exception, and it is why `execute` / `query` are on this
+ * interface rather than a second one: there the op name is `execute.<key>` or
+ * `query.<key>` built from an operation KEY, while `queries` / `mutations`
+ * still hold plain bookkeeping field names.
+ */
+export interface FoirManifestNamespace {
+    queries?: string[];
+    mutations?: string[];
+    /** `operations` only: operation keys reachable as `execute.<key>`. */
+    execute?: string[];
+    /** `operations` only: operation keys reachable as `query.<key>`. */
+    query?: string[];
+}
+export interface FoirManifest {
+    schemaVersion: number;
+    channel: 'published' | 'draft';
+    models: Record<string, FoirManifestModel>;
+    /**
+     * Keyed by namespace name (`auth`, `customers`, `files`, `notifications`,
+     * `operations`, `schedules`, `search`, `secrets`). Deliberately an open
+     * record rather than the eight names: a namespace the platform adds must
+     * reach the generator, and a closed union would silently drop it.
+     */
+    namespaces: Record<string, FoirManifestNamespace>;
+    /** Root fields reachable by this credential that no model/namespace claims. */
+    unclassified?: {
+        queries?: string[];
+        mutations?: string[];
+    };
+}
+/**
+ * Fetch the manifest for the credential in `config`.
+ *
+ * Exported because two things outside this file need it: `foir types` reads it
+ * to generate `FoirSchema`, and the client's drift check reads its
+ * `schemaVersion`. Both would otherwise hand-roll the same fetch.
+ */
+export declare function fetchFoirManifest(config: FoirClientConfig): Promise<FoirManifest>;