@foir/sdk 0.7.0 → 0.9.0

package/dist/data/manifest.d.ts

@@ -20,9 +20,9 @@ export interface FoirManifestScalar {
     /**
      * 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`.
+     * the closed set of platform-owned value objects (`Image`, `Video`,
+     * `FileValue`, `MediaValue`, `Richtext`, `GeoPoint`,
+     * `Reference`, `CollabInfo`) — see `builtins.ts`.
      */
     type: string;
     /**
@@ -72,8 +72,89 @@ 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 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 {
@@ -95,19 +176,62 @@ export interface FoirManifestModel {
      * 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[];
+    /** 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`. */
     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;
@@ -133,6 +257,20 @@ export interface FoirManifestNamespace {
     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;
@@ -149,7 +287,151 @@ export interface FoirManifest {
     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`.

package/dist/data/schema.d.ts

@@ -11,9 +11,20 @@
  * What the generator emits
  * ---------------------------------------------------------------------------
  *
- * A single module, `foir.generated.ts`. A `.ts` and not a `.d.ts` for exactly
- * one reason: `foirSchemaVersion` has to survive to runtime for drift
- * detection. Everything else in the file is types and erases to nothing.
+ * A single module, `foir.generated.ts`, PASSED WHOLE:
+ *
+ * ```ts
+ * import * as generated from './foir.generated';
+ * const foir = createFoirClient({ apiUrl, apiKey, generated });
+ * ```
+ *
+ * A `.ts` and not a `.d.ts` because the file has a runtime half — the selection
+ * trees, `foirSchemaVersion`, and `foirSchemaType`, which is what carries
+ * `FoirSchema` across the type/value boundary so the client can infer it (a
+ * namespace import carries values; an interface erases). `FoirGeneratedModule`
+ * in `transport.ts` is the shape those exports have to satisfy, and it requires
+ * all of them: there is no case where a subset is wanted, and accepting one
+ * quietly meant a client that fetched the manifest on every cold start instead.
  *
  * ```ts
  * // foir.generated.ts — DO NOT EDIT. Generated by `foir types`.
@@ -23,14 +34,26 @@
  * export const foirSchemaVersion = 317;
  * export const foirSchemaChannel = 'published';
  *
- * export interface TillyBlock {
+ * // `<D>` ONLY on the types between the record and a union stopping point —
+ * // see rule 10. Everything else is emitted without it.
+ * export interface TillyBlock<D extends FoirDepthLevel = 1> {
  *   _id: string;
  *   _createdAt: string;
  *   text: string | null;
  *   // Composite/polymorphic fields are emitted as a STATIC discriminated
  *   // union on `__typename`. The client never infers these; it only has to
  *   // avoid destroying them. See `selection.ts`.
- *   body: Array<HeroBlock | TextBlock> | null;
+ *   body: Array<HeroBlock<D> | TextBlock> | null;
+ * }
+ *
+ * export interface HeroBlock<D extends FoirDepthLevel = 1> {
+ *   __typename: 'HeroBlock';
+ *   headline: string;
+ *   // The stopping point: a union reached from inside a union member is
+ *   // already on the op compiler's path, so it degrades — unless the caller
+ *   // bought a level. Mirrors the printer's `depth - 1` at this position.
+ *   body: Array<(D extends 1 ? TillyBlockBodyDegraded
+ *                            : TillyBlockBody<FoirDepthBelow[D]>) | null> | null;
  * }
  *
  * export interface TillyBlockFindUniqueArgs {
@@ -54,6 +77,8 @@
  *     tilly_block: {
  *       typeName: 'TillyBlock';
  *       fields: TillyBlock;
+ *       // Rule 10. Absent on a model with no stopping point, which is most.
+ *       atDepth: { 2: TillyBlock<2>; 3: TillyBlock<3>; 4: TillyBlock<4> };
  *       relations: {
  *         parentBlockId: { target: 'tilly_block'; list: false; nullable: true };
  *       };
@@ -80,6 +105,10 @@
  *     };
  *   };
  * }
+ *
+ * // The type carrier. `FoirSchema` is an interface and erases, so this is the
+ * // only thing a namespace import can infer it from. Runtime value: undefined.
+ * export const foirSchemaType = undefined as unknown as FoirSchema;
  * ```
  *
  * ---------------------------------------------------------------------------
@@ -87,9 +116,9 @@
  * ---------------------------------------------------------------------------
  *
  * 1. **Model keys are the manifest's model keys verbatim** (`tilly_block`, not
- *    `tillyBlock`). They are what `POST /v1/query` takes in `model`, and the
- *    client forwards the property name straight onto the wire. Renaming them
- *    for aesthetics breaks the request.
+ *    `tillyBlock`). They are the key the client looks the model's selection
+ *    tree up by, and the key a refusal names when there is no tree to look up.
+ *    Renaming them for aesthetics breaks the lookup.
  *
  * 2. **Op names are the manifest's op names verbatim** (`findUnique`,
  *    `findMany`, `search`, …) — the canonical names, NOT the GraphQL root
@@ -144,6 +173,27 @@
  *    (as the sketch above does) is the safe shape; if the generator ever
  *    factors these out for readability, they have to be `type X = {…}`.
  *    `__tests__/fixture-schema.ts` is the compiling reference.
+ *
+ * 10. **The `<D>` level parameter goes on the path to a stopping point, and
+ *     nowhere else.** A union reached from inside a union member is already on
+ *     the op compiler's path, so it degrades to `__typename` — and `depth: 2`
+ *     buys one such level back, on the wire AND in the type. The parameter is
+ *     what carries the caller's level from the record down to that position,
+ *     so it belongs on exactly the interfaces, union aliases and member
+ *     projections between the two, and the model names its shape at each level
+ *     under `atDepth`.
+ *
+ *     Both halves of "and nowhere else" matter. A parameter on a type that
+ *     reaches no stopping point is a generic instantiation at every reference
+ *     that can only ever resolve to the default — measured at 7 interfaces of
+ *     50 on the live dev project, which is why the change costs +1.6% types
+ *     rather than a multiple. And `= 1` on every one of them is what makes a
+ *     call passing no `depth` resolve to the type it always did; a parameter
+ *     without a default would be a breaking change to every generated name.
+ *
+ *     The generator computes the set (`depthReach`); it is not a judgement
+ *     call. See `builtins.ts` for `FoirDepthLevel` / `FoirDepthBelow`, and
+ *     `selection.ts` for the single lookup that reads `atDepth`.
  */
 /**
  * A model's complete scalar shape. Deliberately loose — the generator writes a
@@ -191,6 +241,26 @@ export interface FoirModelDefinition {
     readonly typeName: string;
     /** Complete scalar shape. See contract rule 4. */
     readonly fields: FoirFieldsShape;
+    /**
+     * The same shape at a depth ABOVE the default, keyed by the level a caller
+     * would pass as `depth`.
+     *
+     * Present only on models whose tree reaches a union stopping point — a
+     * position the op compiler refuses to expand because the union is already on
+     * its path. `depth: 2` expands one such level on the wire, and the entry
+     * under `2` is the model type describing what then arrives.
+     *
+     * OPTIONAL, and absent is the common case. A model with no stopping point
+     * reads identically at every depth, so generating an entry for it would emit
+     * a second name for one type. A LEVEL with no entry — a depth past what the
+     * generator emitted, or a `depth` that is not a literal at the call site —
+     * falls back to `fields`, which under-promises: the caller gets the values
+     * and narrows by hand, exactly as they did before this key existed. That is
+     * the safe direction, and the reason absence never has to be an error.
+     *
+     * Contract rule 9 applies: emit it as an object type LITERAL.
+     */
+    readonly atDepth?: Readonly<Record<number, FoirFieldsShape>>;
     readonly relations: Readonly<Record<string, FoirRelationDefinition>>;
     readonly ops: Readonly<Record<string, FoirOpDefinition>>;
 }