@foir/sdk 0.5.0 → 0.7.0

package/dist/data/schema.d.ts

@@ -0,0 +1,243 @@
+/**
+ * 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`. 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.
+ *
+ * ```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';
+ *
+ * export interface TillyBlock {
+ *   _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;
+ * }
+ *
+ * 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;
+ *       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;
+ *         };
+ *       };
+ *     };
+ *   };
+ * }
+ * ```
+ *
+ * ---------------------------------------------------------------------------
+ * Rules the generator must hold to
+ * ---------------------------------------------------------------------------
+ *
+ * 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.
+ *
+ * 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.
+ */
+/**
+ * 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;
+    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;
+}

package/dist/data/selection.d.ts

@@ -0,0 +1,330 @@
+/**
+ * The type-level selection machinery — deliberately shallow.
+ *
+ * Two operations and nothing else:
+ *
+ *   1. `Omit<Fields, K>` for `omit`.
+ *   2. One conditional per `include`d relation key.
+ *
+ * No template-literal parsing (Supabase's approach, and the source of its
+ * `tsc` perf complaints), no deep recursive mapped types over field values, no
+ * build-time query parser. The complete-by-default selection model is what
+ * makes that enough: scalars are ALWAYS returned, so the model type is
+ * unconditionally true and there is nothing to narrow. If this file ever
+ * misbehaves the failure mode is a missing relation key, not a mis-parsed
+ * string.
+ *
+ * ---------------------------------------------------------------------------
+ * Why unions survive
+ * ---------------------------------------------------------------------------
+ *
+ * Sanity's typegen — a mature, shipped implementation of the same
+ * architecture — is documented to lose discriminated-union information on
+ * rest-operator array projections. That is the fragile part of any generated
+ * type system, so it is worth being explicit about why it cannot happen here:
+ *
+ * every transformation below operates on the OUTER object's keys only. `Omit`,
+ * `Simplify` and the include-shape mapped type all iterate `keyof Fields` and
+ * copy `Fields[K]` through untouched. A polymorphic field's value type — a
+ * union of `__typename`-discriminated members, written out statically by the
+ * generator — is a property VALUE. It is never mapped over, never distributed,
+ * never re-inferred, so it arrives at the call site byte-identical to what the
+ * generator emitted and narrows under `switch` exactly as it would have.
+ *
+ * `__tests__/selection.test-d.ts` pins this, including the rest-operator and
+ * `.map()` shapes that break Sanity.
+ *
+ * Two notes for whoever edits this file next, both found by mutating it and
+ * watching what the tests did:
+ *
+ *   - A homomorphic mapped type over a NAKED type parameter — the classic
+ *     `type Simplify<T> = { [K in keyof T]: T[K] }` applied to an array's
+ *     element type — is SAFE. It distributes over unions, so the discriminated
+ *     union comes out the other side intact. Mutating the pipeline to do this
+ *     left all six union tests green.
+ *   - `Omit<U, …>` or `Pick<U, …>` on that element type is NOT safe. Both
+ *     compile to `{ [P in K]: … }`, which is not homomorphic and does not
+ *     distribute, and `keyof (A | B | C)` is the INTERSECTION of their keys —
+ *     so the union collapses to `{ __typename: 'A' | 'B' | 'C' }` and every
+ *     branch's own fields vanish. That is Sanity's failure mode, and mutating
+ *     the pipeline to do it reds all six union tests plus the rest-operator
+ *     one by name.
+ *
+ * So: never reach inside a field's value type when that type may be a UNION.
+ *
+ * Nested selection (`pick: { seo: { jsonLd: true } }`) does reach one level in,
+ * and is safe only because `Descendable` refuses unions before it gets there —
+ * see the guard below and the two tests that pin it. The list form of a union
+ * is caught earlier still by the array check, which is why the guard needs a
+ * NON-list union to be tested at all; a mutation disabling it left every test
+ * green until one was added.
+ */
+import type { FoirConnection, FoirModelDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirRelationDefinition, FoirSchemaDefinition } from './schema';
+/**
+ * How deep `include` may nest. Finite by necessity, not by taste: relations are
+ * routinely self-referential (`tilly_block.parentBlockId -> tilly_block`), and
+ * an uncapped recursive mapped type over that is an immediate
+ * "Type instantiation is excessively deep and possibly infinite".
+ */
+type IncludeDepth = 3;
+/** `Decrement[3] === 2`. */
+type Decrement = [never, 0, 1, 2, 3];
+/**
+ * The model a relation resolves to. Falls back to a relation-free, opaque model
+ * when the generated schema names a target that is not in `models` — a
+ * malformed generated file should surface as a useless-but-quiet type, not as a
+ * mapped type over `keyof never`.
+ */
+type TargetModel<S extends FoirSchemaDefinition, R extends FoirRelationDefinition> = R['target'] extends keyof S['models'] ? S['models'][R['target']] : OpaqueModel;
+type OpaqueModel = {
+    typeName: string;
+    fields: Record<string, unknown>;
+    relations: Record<never, FoirRelationDefinition>;
+    ops: Record<never, FoirOpDefinition>;
+};
+/**
+ * The keys a caller may `omit`.
+ *
+ * `_id` is excluded because the server refuses it — verified against deployed
+ * dev: `omit "_id": "_id" is required for correctness and cannot be removed`
+ * (HTTP 400). Excluding it here turns a runtime 400 into a compile error.
+ *
+ * Relations are absent by construction: they are not in `fields`, and omitting
+ * something you never asked for is meaningless.
+ */
+export type FoirOmittableKey<M extends FoirModelDefinition> = Exclude<Extract<keyof M['fields'], string>, '_id'>;
+/**
+ * The `omit` entries actually present in a call.
+ *
+ * `never` when `omit` was not passed. That matters: an OPTIONAL `omit?:` on the
+ * inferred query type does not satisfy the required-property check below, so
+ * the no-argument case (where `Q` falls back to its own constraint) correctly
+ * omits nothing rather than omitting every omittable key.
+ */
+type OmittedKeys<Q> = Q extends {
+    omit: readonly (infer K)[];
+} ? Extract<K, string> : never;
+type ApplyOmit<M extends FoirModelDefinition, Q> = [OmittedKeys<Q>] extends [never] ? M['fields'] : Omit<M['fields'], OmittedKeys<Q>>;
+/**
+ * Every scalar key, including `_id`.
+ *
+ * Unlike `FoirOmittableKey` this does NOT exclude `_id`: naming it is harmless
+ * because it survives either way, and excluding it would make the obvious
+ * `pick: ['_id', 'title']` a type error for no reason.
+ */
+export type FoirPickableKey<M extends FoirModelDefinition> = Extract<keyof M['fields'], string>;
+/** The `pick` entries actually present in a call. `never` when absent — see OmittedKeys. */
+type PickedKeys<Q> = Q extends {
+    pick: readonly (infer K)[];
+} ? Extract<K, string> : never;
+/**
+ * `_id` is added back unconditionally, because the server emits it whatever the
+ * caller asked for (`protectedSelectionFields`). Typing the result without it
+ * would describe a response the server does not send, and a caller would lose
+ * the ability to address the record they just read.
+ *
+ * This is the one place `pick` is not literally what was asked for, which is
+ * why it is stated in the docs rather than left to be discovered.
+ */
+type ApplyPick<M extends FoirModelDefinition, Q> = Pick<M['fields'], Extract<PickedKeys<Q> | '_id', keyof M['fields']>>;
+/**
+ * One narrowing step for both verbs.
+ *
+ * They are mutually exclusive on the wire and in `FoirQuery`, so this only has
+ * to decide which is present — `pick` first, and `omit` is then reached exactly
+ * when `pick` is absent.
+ */
+type ApplySelection<M extends FoirModelDefinition, Q> = [PickedKeys<Q>] extends [never] ? [SelectorOf<Q, 'pick'>] extends [never] ? [SelectorOf<Q, 'omit'>] extends [never] ? ApplyOmit<M, Q> : ApplyOmitSelector<M['fields'], SelectorOf<Q, 'omit'>> : ApplyPickSelector<M['fields'], SelectorOf<Q, 'pick'>> : ApplyPick<M, Q>;
+/**
+ * True when `T` is a union.
+ *
+ * Load-bearing for the guard below rather than a curiosity: a union distributed
+ * through `(U extends any ? (k: U) => void : never)` intersects to something
+ * that is not assignable back to the original, which a single type always is.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
+/**
+ * Whether a field's value may be descended into.
+ *
+ * Objects yes, **unions no**, and the exclusion is the whole point. `Pick` and
+ * `Omit` compile to `{ [P in K]: … }`, which is not homomorphic and does not
+ * distribute, and `keyof (A | B | C)` is the INTERSECTION of their keys — so
+ * narrowing inside a polymorphic block union collapses it to
+ * `{ __typename: 'A' | 'B' | 'C' }` and every branch's own fields vanish. That
+ * is Sanity's documented failure mode, and the union tests in
+ * `__tests__/selection.test-d.ts` go red the moment anything reaches inside a
+ * field's value type.
+ *
+ * The server will happily narrow inside a union; the types must not offer it.
+ * Use GraphQL for that, which is what the transport-choice docs say.
+ */
+type Descendable<V> = IsUnion<NonNullable<V>> extends true ? false : NonNullable<V> extends readonly unknown[] ? false : NonNullable<V> extends object ? true : false;
+/**
+ * The nested selector: `true` for a leaf, or the verb again to descend.
+ *
+ * The verb repeats at each level — `pick: { seo: { pick: { jsonLd: true } } }` —
+ * which is Prisma's shape and, more to the point here, the shape `include`
+ * already uses (`include: { author: { include: { tags: true } } }`). One idiom
+ * in the call rather than two.
+ *
+ * Repeating the keyword also leaves a slot: a future `include: { author: { pick:
+ * {…} } }` has somewhere to live. A bare child map — the first cut of this —
+ * had nowhere to put it and, worse, could not express more than one level, so
+ * `image.variants.thumbnail` was reachable on the wire and untypeable here.
+ *
+ * `D` bounds the recursion for the same reason `IncludeDepth` does: composites
+ * can reference each other, and an uncapped recursive mapped type over that is
+ * an immediate "Type instantiation is excessively deep and possibly infinite".
+ */
+export type FoirSelector<T, Verb extends 'pick' | 'omit', D extends number = SelectorDepth> = {
+    [K in keyof T]?: Descendable<T[K]> extends true ? D extends 0 ? true : true | {
+        [P in Verb]: FoirSelector<NonNullable<T[K]>, Verb, Decrement[D]>;
+    } : true;
+};
+/**
+ * How deep a selector may nest. Three, matching `IncludeDepth`, and comfortably
+ * past what real composites do — `ImageValue.variants.thumbnail` is the deepest
+ * shape on any live model at two.
+ */
+type SelectorDepth = 3;
+/** The selector actually present under `verb`, or `never` when absent or an array. */
+type SelectorOf<Q, Verb extends 'pick' | 'omit'> = Q extends Record<Verb, infer S> ? S extends readonly unknown[] ? never : S : never;
+/**
+ * Apply a nested `pick` selector. `_id` survives regardless, for the same
+ * reason it does in the flat form — the server always emits it.
+ */
+type ApplyPickSelector<F, S> = {
+    [K in Extract<keyof S, keyof F> | Extract<'_id', keyof F>]: K extends keyof S ? S[K] extends {
+        pick: infer Inner;
+    } ? PickSelectorDeep<NonNullable<F[K]>, Inner> : F[K] : F[K];
+};
+/**
+ * The same walk one level in. Separate from the root because `_id` is forced at
+ * the ROOT only — a composite has no `_id`, and adding one would describe a
+ * response shape the server never sends.
+ */
+type PickSelectorDeep<F, S> = {
+    [K in Extract<keyof S, keyof F>]: S[K] extends {
+        pick: infer Inner;
+    } ? PickSelectorDeep<NonNullable<F[K]>, Inner> : F[K];
+};
+/**
+ * Apply a nested `omit` selector.
+ *
+ * `true` at a key drops the whole field. An object at a key drops only the
+ * named children, which is what makes `omit: { description: { markdown: true } }`
+ * able to shed one richtext encoding of three without losing the field.
+ */
+type ApplyOmitSelector<F, S> = {
+    [K in keyof F as K extends keyof S ? (S[K] extends true ? never : K) : K]: K extends keyof S ? S[K] extends {
+        omit: infer Inner;
+    } ? ApplyOmitSelector<NonNullable<F[K]>, Inner> : F[K] : F[K];
+};
+/**
+ * The `include` argument for a model: every relation key, opt-in, optionally
+ * carrying a nested `include` for the relation's own relations.
+ *
+ * `true` only (not `boolean`) — a `false` would go on the wire and the server
+ * validates `include` keys strictly, so a conditional include has to be built
+ * by conditionally spreading the key, not by passing `false`.
+ */
+export type FoirInclude<S extends FoirSchemaDefinition, M extends FoirModelDefinition, D extends number = IncludeDepth> = {
+    [K in keyof M['relations']]?: D extends 0 ? true : true | {
+        include?: FoirInclude<S, TargetModel<S, M['relations'][K]>, Decrement[D]>;
+    };
+};
+/** The relation keys a call asked for, shaped by list/nullable and nesting. */
+type IncludedRelations<S extends FoirSchemaDefinition, M extends FoirModelDefinition, I, D extends number> = {
+    [K in Extract<keyof I, keyof M['relations']>]: WrapRelation<M['relations'][K], FoirRecordResult<S, TargetModel<S, M['relations'][K]>, I[K], Decrement[D]>>;
+};
+type WrapRelation<R extends FoirRelationDefinition, T> = R['list'] extends true ? R['nullable'] extends true ? T[] | null : T[] : R['nullable'] extends true ? T | null : T;
+/**
+ * A model as this call will receive it: the complete scalar shape, minus
+ * `omit`, plus the `include`d relations.
+ *
+ * When neither was passed this resolves to `M['fields']` BY IDENTITY — not a
+ * structurally-equal copy — so `foir.tilly_block.findUnique({ id })` hovers as
+ * `TillyBlock` rather than as an anonymous 40-property object literal.
+ *
+ * `include` produces an INTERSECTION rather than a flattened object, on
+ * purpose. A `{ [K in keyof T]: T[K] }` flattening pass would read a little
+ * tidier in a hover, but `TillyBlock & { noteId: TillyNote | null }` already
+ * reads well and names the generated interface — and, more to the point, it
+ * means the only mapped type anywhere near a result is `Omit`. One less thing
+ * between the generator's union and the call site.
+ */
+export type FoirRecordResult<S extends FoirSchemaDefinition, M extends FoirModelDefinition, Q, D extends number = IncludeDepth> = Q extends {
+    include: infer I;
+} ? ApplySelection<M, Q> & IncludedRelations<S, M, I, D> : ApplySelection<M, Q>;
+/** Apply an op's return wrapper to the shaped record. */
+export type FoirOpResult<S extends FoirSchemaDefinition, M extends FoirModelDefinition, O extends FoirOpDefinition, Q> = O['returns'] extends {
+    kind: 'opaque';
+    type: infer T;
+} ? T : O['returns'] extends {
+    kind: 'connection';
+} ? FoirConnection<FoirRecordResult<S, M, Q>> : O['returns'] extends {
+    kind: 'list';
+    nullable: infer N;
+} ? N extends true ? Array<FoirRecordResult<S, M, Q>> | null : Array<FoirRecordResult<S, M, Q>> : O['returns'] extends {
+    kind: 'record';
+    nullable: infer N;
+} ? N extends true ? FoirRecordResult<S, M, Q> | null : FoirRecordResult<S, M, Q> : never;
+/**
+ * What a model op accepts: the op's own args with `include`/`omit` as siblings.
+ * They are split back apart onto the wire (`{ model, op, args, include, omit }`)
+ * — `include`/`omit` are selection, not arguments — but at the call site a
+ * single flat object is what reads well.
+ *
+ * An `opaque` op returns something that is not the model, so selection does not
+ * apply and is not offered.
+ */
+export type FoirQuery<S extends FoirSchemaDefinition, M extends FoirModelDefinition, O extends FoirOpDefinition> = O['returns'] extends {
+    kind: 'opaque';
+} ? O['args'] : O['args'] & ({
+    include?: FoirInclude<S, M>;
+    omit?: readonly FoirOmittableKey<M>[] | FoirSelector<M['fields'], 'omit'>;
+    /**
+     * Mutually exclusive with `omit`, mirroring the server's 400. Typed as
+     * `never?` on this branch rather than left out, because omitting the key
+     * would let an object carrying BOTH satisfy this branch and reach the
+     * wire — the excess-property check does not fire on a value inferred
+     * into a generic parameter, which is the same hole `NoExtraKeys` exists
+     * to close.
+     */
+    pick?: never;
+} | {
+    include?: FoirInclude<S, M>;
+    pick?: readonly FoirPickableKey<M>[] | FoirSelector<M['fields'], 'pick'>;
+    omit?: never;
+});
+/**
+ * Reject keys the op does not declare.
+ *
+ * TypeScript's excess-property check does NOT fire when an object literal is
+ * inferred into a generic type parameter — `Q` is inferred as the literal's own
+ * shape and then merely has to be *assignable* to its constraint, which an
+ * object with extra keys is. So `findUnique({ id, first: 10 })` compiled
+ * silently and sent `first` to a server that does not take it. Typing every
+ * undeclared key as `never` puts the check back: `first: 10` is not assignable
+ * to `never`, and the error lands on the offending key.
+ *
+ * Pinned by "rejects an arg the op does not declare" in
+ * `__tests__/selection.test-d.ts`.
+ */
+type NoExtraKeys<Q, T> = Record<Exclude<keyof Q, keyof T>, never>;
+/**
+ * One model operation.
+ *
+ * `const Q` is what makes `omit: ['bodyRichtext']` infer as the tuple
+ * `readonly ['bodyRichtext']` instead of `string[]`; without it `Omit` would
+ * have nothing to remove. It also pins `include: { author: true }` to the
+ * literal `true`.
+ */
+export type FoirModelOperation<S extends FoirSchemaDefinition, M extends FoirModelDefinition, O extends FoirOpDefinition> = <const Q extends FoirQuery<S, M, O>>(query?: Q & NoExtraKeys<Q, FoirQuery<S, M, O>>) => Promise<FoirOpResult<S, M, O, Q>>;
+/**
+ * One namespace operation. No model behind it, so no `include`/`omit` and the
+ * generated result type is used verbatim.
+ */
+export type FoirNamespaceOperation<O extends FoirNamespaceOpDefinition> = (args?: O['args']) => Promise<O['result']>;
+export {};

package/dist/data/transport.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `POST /v1/query` transport.
+ *
+ * Everything Foir-specific about the request — which key, the preview schema
+ * channel, the customer bearer, the error shape — comes from
+ * `../transport/foir-http`, the same module `@foir/sdk/client`'s `foirRequest`
+ * uses. This file adds only what is specific to the JSON op endpoint: the URL,
+ * the body, and reading the single root field back out.
+ *
+ * Edge-safe: `fetch` only, no Node built-ins, and no module-level state of any
+ * kind. A shared cache on a stateless multi-tenant edge worker is a
+ * cross-tenant hazard (see `../graphql/foir-request.ts:1-18`), and that applies
+ * with more force here — this client is per-credential, so anything cached
+ * across instances is cached across tenants.
+ */
+import { type FoirTokenProvider } from '../transport/foir-http';
+/** The wire body `POST /v1/query` accepts. Exactly one of model/namespace. */
+export type FoirRawOp = {
+    op: string;
+    args?: Record<string, unknown>;
+    include?: Record<string, unknown>;
+    /** Remove named paths. Mutually exclusive with `pick` — the server 400s on both. */
+    omit?: readonly string[];
+    /** Keep only named paths. Mutually exclusive with `omit`. `_id` is always returned. */
+    pick?: readonly string[];
+} & ({
+    model: string;
+    namespace?: never;
+} | {
+    namespace: string;
+    model?: never;
+});
+export interface FoirClientConfig {
+    /**
+     * Foir public API origin, e.g. `https://api.foir.dev`.
+     *
+     * A full GraphQL endpoint is accepted too — `PLATFORM_API_URL` is
+     * conventionally `https://api.foir.dev/graphql` and people will paste it — so
+     * a trailing `/graphql` is stripped before `/v1/query` is appended.
+     */
+    apiUrl: string;
+    /** `pk_…` or `sk_…`. The manifest, and therefore the generated types, are shaped by it. */
+    apiKey: string;
+    /**
+     * Read the draft schema channel (`X-Foir-Schema-Channel: draft`). Needs a
+     * `sk_` key with `drafts:read`; the header is ignored under public keys.
+     * Defaults to `'published'`.
+     */
+    channel?: 'published' | 'draft';
+    /**
+     * Customer bearer for self-scoped reads (`myProfile`, `myTillyNotes`). A
+     * function is resolved before every request so a cookie session can be read
+     * per-request; a bare string is used as-is.
+     */
+    bearerToken?: string | FoirTokenProvider;
+    /** Extra headers, applied last so they can override the ones above. */
+    headers?: Readonly<Record<string, string>>;
+    /**
+     * `fetch` implementation. Defaults to `globalThis.fetch`. Injectable for
+     * tests and for runtimes that hand you a bound `fetch` (Hydrogen/Oxygen).
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Merged into every `fetch` call — `{ cache: 'no-store' }`,
+     * `{ next: { revalidate: 60 } }`, an `AbortSignal`, and so on. Applied after
+     * method/headers/body, so those cannot be clobbered by accident.
+     */
+    requestInit?: Omit<RequestInit, 'method' | 'headers' | 'body'>;
+    /**
+     * `foirSchemaVersion` from the generated module. When set, the client
+     * compares it against the server's manifest once and warns on mismatch.
+     * Omitted — e.g. types generated as a bare `.d.ts` — disables the check.
+     */
+    schemaVersion?: number;
+    /** Set `false` to suppress the drift check even when `schemaVersion` is set. */
+    checkSchemaDrift?: boolean;
+    /** Called instead of `console.warn` when drift is detected. */
+    onSchemaDrift?: (drift: FoirSchemaDrift) => void;
+}
+export interface FoirSchemaDrift {
+    /** Manifest version the local types were generated from. */
+    generated: number;
+    /** Manifest version the server is serving now. */
+    server: number;
+    channel: string;
+}
+/**
+ * Build a `/v1/...` URL from whatever the caller put in `apiUrl`.
+ *
+ * Tolerates the three things people actually pass: an origin, an origin with a
+ * trailing slash, and the conventional `PLATFORM_API_URL` value
+ * (`https://api.foir.dev/graphql`).
+ */
+export declare function foirDataEndpoint(apiUrl: string, path: `/${string}`): string;
+/** Resolve `config.bearerToken`, whether it is a string, a function, or absent. */
+export declare function resolveBearerToken(config: Pick<FoirClientConfig, 'bearerToken'>): Promise<string | undefined>;
+/**
+ * Execute one op and return the single root field's value.
+ *
+ * The response is a normal GraphQL envelope keyed by the compiled document's
+ * root field (`{"data":{"tillyBlocks":{…}}}`), and the client has no manifest at
+ * runtime so it does not know that name. It does not need to: one op compiles
+ * to exactly one root field, so "the only key of `data`" is unambiguous. A
+ * response with a different number of keys means the server changed shape, and
+ * guessing would be worse than saying so.
+ */
+export declare function postFoirOp<T>(config: FoirClientConfig, body: FoirRawOp): Promise<T>;