@foir/sdk 0.5.0 → 0.8.0

package/dist/data/schema.d.ts

@@ -0,0 +1,313 @@
+/**
+ * THE `FoirSchema` CONTRACT.
+ *
+ * `createFoirClient<FoirSchema>()` is parameterised by a type that `foir types`
+ * (TTS-875) emits from `GET /v1/manifest`. This file is that contract: the
+ * shape the generator writes and the shape the client reads. It is the only
+ * coupling between the two, so it is written down here rather than living in
+ * the generator's head.
+ *
+ * ---------------------------------------------------------------------------
+ * What the generator emits
+ * ---------------------------------------------------------------------------
+ *
+ * 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`.
+ * import type { FoirSchemaDefinition } from '@foir/sdk/data';
+ *
+ * /** `schemaVersion` from the manifest these types were generated from. *\/
+ * export const foirSchemaVersion = 317;
+ * export const foirSchemaChannel = 'published';
+ *
+ * // `<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<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 {
+ *   id?: string;
+ *   naturalKey?: string;
+ *   locale?: string;
+ *   preview?: boolean;
+ *   // NOT a list, despite the plural: `ResolveContextInput`, an object of four
+ *   // optional fields. This sketch said `ReadonlyArray<string>` until 2026-07-28,
+ *   // when the docs lane caught it by RUNNING the call. A wrong argument type
+ *   // compiles at every call site and fails at the server, which is the exact
+ *   // lie generated types exist to remove — so `foir types` imports the shape
+ *   // from `builtins.ts` rather than restating it.
+ *   contexts?: FoirResolveContext;
+ * }
+ *
+ * export interface FoirSchema extends FoirSchemaDefinition {
+ *   schemaVersion: typeof foirSchemaVersion;
+ *   channel: 'published';
+ *   models: {
+ *     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 };
+ *       };
+ *       ops: {
+ *         findUnique: {
+ *           args: TillyBlockFindUniqueArgs;
+ *           returns: { kind: 'record'; nullable: true };
+ *         };
+ *         findMany: {
+ *           args: TillyBlockFindManyArgs;
+ *           returns: { kind: 'connection' };
+ *         };
+ *       };
+ *     };
+ *   };
+ *   namespaces: {
+ *     search: {
+ *       ops: {
+ *         searchRecords: {
+ *           args: SearchRecordsArgs;
+ *           result: SearchRecordsResult;
+ *         };
+ *       };
+ *     };
+ *   };
+ * }
+ *
+ * // 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;
+ * ```
+ *
+ * ---------------------------------------------------------------------------
+ * Rules the generator must hold to
+ * ---------------------------------------------------------------------------
+ *
+ * 1. **Model keys are the manifest's model keys verbatim** (`tilly_block`, not
+ *    `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
+ *    field (`tillyBlock`, `tillyBlocks`). Same reason: they go on the wire.
+ *    For namespaces the op name IS the root field name, as the manifest lists
+ *    it, because that is what the server matches on.
+ *
+ * 3. **Emit only what the manifest returned.** The manifest is already the
+ *    per-caller projection of `SchemaForCaller(scopes)`, so "only the ops this
+ *    credential can perform" needs no extra filtering — it is what arrives. A
+ *    `pk_` key's generated schema simply has no `create`, and
+ *    `foir.tilly_block.create(...)` is then a compile error, which is the
+ *    entire point of per-key shaping.
+ *
+ * 4. **`fields` is the COMPLETE scalar shape**, every scalar the manifest
+ *    lists, none optional. This is what makes the model type unconditionally
+ *    true: the server always returns every scalar (the selection model is
+ *    complete-by-default), so no field can be typed present and arrive
+ *    `undefined`. Nullable scalars are `T | null`, never `T | undefined` and
+ *    never `?:`.
+ *
+ * 5. **Relations are NOT in `fields`.** A relation key only exists on the
+ *    result when the caller asked for it via `include`. Putting it in `fields`
+ *    would type it as always-present, which is the exact footgun rule 4 is
+ *    there to remove.
+ *
+ * 6. **`returns.kind` classifies the wrapper, not the model.**
+ *    - `record` — the model itself; `nullable` when the field can resolve null
+ *      (`findUnique`, `findMine`).
+ *    - `connection` — a Relay connection over the model (`findMany`).
+ *    - `list` — a plain array of the model.
+ *    - `opaque` — the op does not return the model at all (`myAccess`). Its
+ *      `type` is used verbatim and `include`/`omit` are not offered.
+ *
+ * 7. **Unions are emitted statically.** A polymorphic field's type is written
+ *    out as a discriminated union on `__typename` by the generator. There is
+ *    no inference step, so there is nothing for the client to get wrong — see
+ *    `selection.ts` for why the selection machinery cannot flatten it.
+ *
+ * 8. **`raw` and `ns` are reserved top-level names.** They are the escape hatch
+ *    and the namespace accessor on the client object. A model whose key is
+ *    `raw` or `ns` would collide; the server should reject those model keys at
+ *    create time (noted in TTS-868's "Known limits").
+ *
+ * 9. **`models` and `namespaces` must be object type LITERALS, not named
+ *    `interface`s.** TypeScript gives an implicit index signature to object
+ *    type literals and to `type` aliases of them, but never to an interface. So
+ *    `models: { tilly_block: {…} }` written inline satisfies
+ *    `Readonly<Record<string, FoirModelDefinition>>`, and
+ *    `interface Models { tilly_block: {…} }` + `models: Models` does not — it
+ *    fails with "Index signature for type 'string' is missing". Emitting inline
+ *    (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
+ * real interface here and the client only ever `Omit`s from it or reads its
+ * keys, so constraining it further buys nothing and makes generated interfaces
+ * with index signatures or unusual key types fail to assign.
+ */
+export type FoirFieldsShape = object;
+/** One relation the caller may `include`. */
+export interface FoirRelationDefinition {
+    /** Key in `FoirSchemaDefinition['models']` this relation resolves to. */
+    readonly target: string;
+    /** True when the relation resolves to a list of the target model. */
+    readonly list: boolean;
+    /** True when the relation itself can resolve null. */
+    readonly nullable: boolean;
+}
+/** How an op's result wraps (or does not wrap) the model. */
+export type FoirReturnDefinition = {
+    readonly kind: 'record';
+    readonly nullable: boolean;
+} | {
+    readonly kind: 'connection';
+} | {
+    readonly kind: 'list';
+    readonly nullable: boolean;
+} | {
+    readonly kind: 'opaque';
+    readonly type: unknown;
+};
+/** One operation available on a model for this credential. */
+export interface FoirOpDefinition {
+    /**
+     * The op's arguments, as an object type. These are spread at the CALL SITE
+     * alongside `include`/`omit` (`{ where, first, include }`) and split back out
+     * into the wire's `args` object by the client — `include`/`omit` are
+     * selection, not arguments, and the server takes them as siblings of `args`.
+     */
+    readonly args: object;
+    readonly returns: FoirReturnDefinition;
+}
+/** A model as the per-caller manifest describes it. */
+export interface FoirModelDefinition {
+    /** GraphQL type name, e.g. `'TillyBlock'`. Documentation + tooling. */
+    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>>;
+}
+/**
+ * One op on a non-model namespace (`search`, `customers`, `notifications`).
+ * Namespaces have no model behind them, so there is no `include`/`omit` and
+ * the result type is used verbatim.
+ */
+export interface FoirNamespaceOpDefinition {
+    readonly args: object;
+    readonly result: unknown;
+}
+export interface FoirNamespaceDefinition {
+    readonly ops: Readonly<Record<string, FoirNamespaceOpDefinition>>;
+}
+/**
+ * The type `createFoirClient` is parameterised by. `foir types` emits an
+ * interface extending this; everything above documents what goes in it.
+ */
+export interface FoirSchemaDefinition {
+    /**
+     * `schemaVersion` from the manifest these types were generated from. Kept as
+     * a literal so a human reading the generated file sees it, and mirrored by a
+     * runtime `foirSchemaVersion` const for drift detection — the type cannot be
+     * read at runtime.
+     */
+    readonly schemaVersion: number;
+    readonly channel: 'published' | 'draft';
+    readonly models: Readonly<Record<string, FoirModelDefinition>>;
+    readonly namespaces: Readonly<Record<string, FoirNamespaceDefinition>>;
+}
+/**
+ * A Relay connection, as `findMany` returns it. Not flattened to an array on
+ * purpose: the compiled document is still the wire format, and hiding
+ * `pageInfo` behind a convenience array would make pagination unreachable
+ * without dropping to `raw`.
+ */
+export interface FoirConnection<TNode> {
+    edges: Array<{
+        cursor: string;
+        node: TNode;
+    }>;
+    pageInfo: {
+        hasNextPage: boolean;
+        hasPreviousPage: boolean;
+        startCursor: string | null;
+        endCursor: string | null;
+    };
+    totalCount: number;
+}