@foir/sdk 0.5.0 → 0.8.0

package/dist/data/manifest.d.ts

@@ -0,0 +1,424 @@
+/**
+ * `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 (`Image`, `Video`,
+     * `FileValue`, `MediaValue`, `Richtext`, `GeoPoint`,
+     * `Reference`, `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[];
+    /**
+     * Each name in `args` mapped to the GraphQL type the root field declares for
+     * it — `'String!'`, `'[PageOrderByInput]'`, `'SortDirection'` — spelled
+     * exactly as a variable definition needs it.
+     *
+     * This is what lets the printer emit `query FoirQuery($orderBy: [PageOrderByInput])`
+     * and put the value in `variables`, where the executor coerces it. Without
+     * the type a printer has to infer a LITERAL from the JavaScript value, which
+     * is exact for strings, numbers, booleans and objects and ambiguous for
+     * enums — the client holds the string `'DESC'` and `orderBy: { createdAt: DESC }`
+     * needs it unquoted.
+     *
+     * An argument named in `args` with no entry here has no type this projection
+     * could read. The printer REFUSES such a call: inferring the literal form
+     * from the value is the defect this field exists to remove, so falling back
+     * to it would reintroduce it under a condition nobody can see.
+     */
+    argTypes?: Record<string, string>;
+    /** True when the field lives on the Mutation root. */
+    mutation?: boolean;
+    /**
+     * The resolved shape of this op's RESULT.
+     *
+     * The model's own `selection` answers for `findUnique` and for nothing else:
+     * `findMany` returns a connection OVER the model, `search` returns a wrapper
+     * CARRYING it, `delete` returns `Boolean!`, and `myAccess` returns a payload
+     * that is not the model in any sense. A consumer that bridged that gap by
+     * knowing from the OP NAME which shape to print was carrying a schema under
+     * another name.
+     *
+     * Absent is not "no selection". A consumer must refuse the op rather than
+     * synthesise a shape for it.
+     */
+    payload?: FoirManifestOpPayload;
+}
+/**
+ * The resolved shape of one op's result — four kinds, and the printer handles
+ * all four rather than defaulting.
+ */
+export interface FoirManifestOpPayload {
+    /**
+     * - `record` — the payload IS the model named by `model`; print that model's
+     *   published `selection` as the root field's selection set.
+     * - `object` — `fields` is the resolved selection set. A field carrying
+     *   `model` expands to that model's `selection`, which is how the connection
+     *   and search-result wrappers keep the record's tree in one place instead of
+     *   copying it per op.
+     * - `union` — print one inline fragment per member of `selectionUnions[union]`.
+     * - `leaf` — `Boolean!`, `Int`, an enum. NO selection set: emitting `{}` is a
+     *   parse error, which is why this is a stated kind rather than empty `fields`.
+     */
+    kind: 'record' | 'object' | 'union' | 'leaf';
+    /** Model key, for kind `record`. */
+    model?: string;
+    /** `selectionUnions` key, for kind `union`. */
+    union?: string;
+    /** The resolved selection, for kind `object`. */
+    fields?: FoirManifestSelectionField[];
+    /** What this payload emits when printed whole, in `FoirManifestSelection.cost`'s unit. */
+    cost?: number;
+    /**
+     * Why this payload could not be resolved. Set INSTEAD of the shape fields,
+     * never beside them — an op carrying an error has no printable shape and a
+     * consumer must refuse it.
+     */
+    error?: string;
+}
+/** 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>;
+    /**
+     * The resolved complete-by-default selection for this model. Present on a
+     * server that publishes selection trees; absent otherwise.
+     *
+     * It hangs off the MODEL rather than each op because every op whose payload
+     * is this model shares one selection root.
+     */
+    selection?: FoirManifestSelection;
+    /** Why `selection` is absent, when the server could not resolve one. */
+    selectionError?: string;
+    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[];
+    /**
+     * The model's `<Type>OrderByInput`, projected — the vocabulary of the
+     * `orderBy` argument.
+     *
+     * `fields` are the entry keys a sort element may carry; `directions` are the
+     * value names of the enum those entries are typed as (`ASC` / `DESC`). Both
+     * are read off the built input object server-side, so neither can disagree
+     * with what the executor coerces a caller's `orderBy` against.
+     *
+     * IT IS PUBLISHED BECAUSE NOTHING ELSE HERE ANSWERS FOR IT, and `scalars` —
+     * the field that looks like it should — is wrong in both directions at once:
+     *
+     *  - wrong SET: `hero` (`Image`), `body` (`Richtext`), `_segments`
+     *    (`JSON`) and every soft-deleted field are scalars and none is sortable;
+     *  - wrong NAMES: the platform-managed columns are `_id` / `_createdAt` /
+     *    `_updatedAt` / `_naturalKey` on the record type and `id` / `createdAt` /
+     *    `updatedAt` / `naturalKey` in `OrderByInput`. A consumer deriving sort
+     *    keys from the scalar list emits `_createdAt`, which the server refuses.
+     *
+     * `ops[op].argTypes.orderBy` names the input type (`[PageOrderByInput]`) and
+     * stops there: enough to print a variable definition, not enough to type a
+     * call site.
+     *
+     * ABSENT means "this projection has nothing to say" — an embedded model, or a
+     * server that predates the field. A consumer must WIDEN on absent, never read
+     * it as "nothing is sortable".
+     */
+    orderBy?: {
+        fields: string[];
+        directions: 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[];
+    /**
+     * Each of those root fields described the way a model op is described:
+     * arguments with their types, and the resolved shape of the result.
+     *
+     * Keyed by the token the op is ADDRESSED by — the root field name for every
+     * namespace but `operations`, where it is `execute.<key>` / `query.<key>` for
+     * the per-operation surfaces and the plain field name for the bookkeeping
+     * ones. The lists above stay authoritative for REACHABILITY; this is the
+     * description of what those names do.
+     *
+     * Because an entry is a `FoirManifestOp`, whatever prints a model op prints a
+     * namespace op — one code path, not two.
+     */
+    ops?: Record<string, FoirManifestOp>;
+}
+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[];
+        /**
+         * Subscription root fields the server declined to state the reachability
+         * of — today only `events`, whose scope is charged against the resolved
+         * data-plane authority rather than the api key's own scope set. Reported so
+         * the gap is visible; nothing is generated from it.
+         */
+        subscriptions?: string[];
+    };
+    /**
+     * Each union's expansion, once, keyed by union type name. A selection field
+     * references one by name rather than inlining it — seven models reaching one
+     * 56-member block union inlined it seven times and made the manifest 6.9x
+     * larger, 85% of it duplication.
+     *
+     * Absent on a server that predates selection trees, which is why every
+     * consumer must treat it as optional rather than assume the shape.
+     */
+    selectionUnions?: Record<string, FoirManifestSelectionUnion>;
+    /**
+     * Subscription root fields this credential may open over `/graphql/ws`.
+     *
+     * Unlike `models[].ops`, this list is NOT derived from the caller's schema
+     * variant: the server copies the whole Subscription root into every variant
+     * (the transport is out of band), so the variant admits all of them to
+     * everybody. The list is projected from the same table the socket charges at
+     * subscribe time, which is what makes it safe to generate against — a field
+     * that is here will be accepted, and one that is absent will be refused.
+     */
+    subscriptions?: FoirManifestSubscription[];
+}
+/**
+ * One subscription root field, with the tree a document is printed from.
+ */
+export interface FoirManifestSubscription {
+    /** The Subscription root field name. */
+    field: string;
+    /** Argument names, sorted. */
+    args?: string[];
+    /**
+     * Each name in `args` mapped to the GraphQL type the field declares for it —
+     * `'String!'` — spelled exactly as a variable definition needs it, and for
+     * the same reason `FoirManifestOp.argTypes` exists: a subscribe frame carries
+     * a `variables` object like any other operation, so without the type a
+     * consumer would have to infer a literal form from the value it holds.
+     *
+     * It also decides the variable NAME. The socket resolves an argument-gated
+     * subscription's scope by reading `variables[<arg>]` BY NAME, so
+     * `subscription S($m: String!) { recordChanged(modelKey: $m) … }` opens and is
+     * then refused for a scope it cannot complete. Declaring `$<arg>` — which is
+     * what a printer driven by this map does — is what keeps the two in step.
+     */
+    argTypes?: Record<string, string>;
+    /** GraphQL named type of the event payload. */
+    type: string;
+    /**
+     * The scope the socket charges. Empty exactly when `argScope` is set. Carried
+     * so a client can say WHICH capability a refusal was about instead of
+     * reporting a bare failure.
+     */
+    scope?: string;
+    /** Set when the required scope is completed by a subscribe argument. */
+    argScope?: FoirManifestSubscriptionArgScope;
+    /** Resolved complete-by-default selection for the payload type. */
+    selection?: FoirManifestSelection;
+    /** Why `selection` is absent. Absent is not "no fields". */
+    selectionError?: string;
+}
+/**
+ * A subscription whose authorization depends on a value supplied at subscribe
+ * time.
+ *
+ * `recordChanged` is the one instance: the socket charges
+ * `records:read:<modelKey>` against the `modelKey` variable, so the field has
+ * no static yes/no. What is statically true is which values this credential's
+ * scopes admit, and that is what `values` carries.
+ */
+export interface FoirManifestSubscriptionArgScope {
+    /** The subscribe argument whose value completes the scope. */
+    arg: string;
+    /** What the argument's value is appended to. */
+    prefix: string;
+    /**
+     * The argument values this credential admits, sorted. The ADDRESSABLE set,
+     * not a proof of exhaustiveness — a key holding the two-part `records:read`
+     * satisfies the socket for any string at all.
+     */
+    values: string[];
+}
+/**
+ * A resolved complete-by-default selection: what to ask for, already expanded.
+ *
+ * The server resolves this once per schema version — unions expanded per
+ * member, response-shape aliases assigned, cycles broken, field budget
+ * counted — so printing a document is string building rather than a schema
+ * walk. Nothing here requires the consumer to know a field's GraphQL type.
+ */
+export interface FoirManifestSelection {
+    fields: FoirManifestSelectionField[];
+    /**
+     * Fields this tree emits when printed whole, relations excluded. Same unit
+     * the executor's complexity budget is denominated in.
+     */
+    cost: number;
+}
+export interface FoirManifestSelectionField {
+    key: string;
+    /**
+     * The response key to emit instead of `key`, set only where a union member's
+     * field name collides with an incompatible shape on another member. A
+     * consumer prints `alias: key` and types the result under `alias`.
+     */
+    alias?: string;
+    /** Nested selection for a composite or a builtin value object. */
+    fields?: FoirManifestSelectionField[];
+    /**
+     * Names a model whose published `selection` IS this field's selection.
+     *
+     * It appears where a record turns up inside a payload the caller did not
+     * address the record through: a connection's `node`, a search result's
+     * `record`. A REFERENCE rather than an inlined copy, so seven ops over one
+     * model do not carry seven copies of its tree — and so a caller's `omit`
+     * reaches the same tree whichever op it came through.
+     */
+    model?: string;
+    /** Names an entry in `FoirManifest.selectionUnions`. */
+    union?: string;
+    /**
+     * `include` governs this field, so it is NOT part of the default document.
+     * Emit it only when the caller asks for it.
+     */
+    relation?: boolean;
+    /**
+     * The cycle or depth rule stopped expansion here. Still selectable, but only
+     * as `__typename` — print that rather than an empty body, which is a parse
+     * error.
+     */
+    truncated?: boolean;
+}
+export interface FoirManifestSelectionUnion {
+    /** Sorted by type name, so the expansion is stable across runs. */
+    members: FoirManifestSelectionMember[];
+}
+export interface FoirManifestSelectionMember {
+    typeName: string;
+    fields: FoirManifestSelectionField[];
+}
+/**
+ * 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>;