@foir/sdk 0.5.0 → 0.8.0

package/dist/data/document.d.ts

@@ -0,0 +1,251 @@
+/**
+ * From a resolved selection tree to a GraphQL document string.
+ *
+ * ---------------------------------------------------------------------------
+ * Why there is no `graphql` dependency here, and never can be
+ * ---------------------------------------------------------------------------
+ *
+ * The tree arrives PRE-RESOLVED. The server walked the built schema once per
+ * schema version — unions expanded per member, response-shape aliases assigned,
+ * cycles broken, the field budget counted — and published the answer on
+ * `GET /v1/manifest`: `models.<key>.selection` for a model's own tree, and
+ * `ops.<op>.payload` for the shape of what each op actually returns. What is
+ * left at runtime is a filter and a printer, which is string building. That is
+ * the whole reason this client shrinks rather than inheriting
+ * `query_compiler.go` in TypeScript.
+ *
+ * The rule that keeps it that way: **nothing below may need to know something
+ * about the schema that the manifest does not publish.** Every decision here is
+ * made from a flag the tree carries (`alias`, `model`, `union`, `relation`,
+ * `truncated`), from a payload's stated `kind`, or from a published argument
+ * type. There is no table of op names, no inferred wrapper shape, and no type
+ * guessed from a JavaScript value.
+ *
+ * ---------------------------------------------------------------------------
+ * Arguments are variables, not literals
+ * ---------------------------------------------------------------------------
+ *
+ * The manifest publishes each argument's declared GraphQL type
+ * (`ops.<op>.argTypes`), so an argument is emitted as a variable definition and
+ * its value travels in `variables`:
+ *
+ *     query PageFindMany($orderBy: [PageOrderByInput]) { pages(orderBy: $orderBy) { … } }
+ *
+ * That is not a nicety. A printer working from argument NAMES alone has to
+ * infer each value's literal form from the JavaScript value it holds, which is
+ * exact for strings, numbers, booleans and objects and **ambiguous for enums**:
+ * `orderBy: { createdAt: DESC }` needs `DESC` unquoted and the client holds the
+ * string `'DESC'`, indistinguishable from `naturalKey: "DESC"`. Putting the
+ * value in `variables` does not resolve the ambiguity, it removes it — the
+ * executor coerces against the declared input type, which is the same path the
+ * server's own `compileArgs` took so that no caller byte is spliced into query
+ * text.
+ *
+ * The second-order win is that the document text no longer varies with the
+ * argument VALUE, so a persisted-query registry holds one entry per op instead
+ * of one per argument tuple. Argument names are emitted in sorted order for the
+ * same reason: two callers passing the same arguments in a different object
+ * literal order must hash to one entry.
+ *
+ * An argument the manifest publishes no type for is REFUSED. Falling back to
+ * inferring a literal would reinstate the defect above under a condition no
+ * caller can see.
+ */
+import type { FoirManifestOp, FoirManifestRelation, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionUnion } from './manifest';
+/**
+ * One model, as the printer needs it.
+ *
+ * A structural subset of `FoirManifestModel`, deliberately — so the two ways of
+ * getting here are the same shape and there is one code path, not two:
+ *
+ *   - `foir types` bakes it into `foirSelections`, the runtime half of the
+ *     generated module, and the client never fetches anything.
+ *   - the fallback fetches `GET /v1/manifest` at construction and passes
+ *     `manifest.models` straight in, because a `FoirManifestModel` already
+ *     satisfies this interface.
+ */
+export interface FoirSelectionModel {
+    /** GraphQL type name, e.g. `'Page'`. Used when a polymorphic relation needs fragments. */
+    typeName: string;
+    /** Op name → root field, argument types and the resolved shape of the result. */
+    ops?: Readonly<Record<string, FoirManifestOp>>;
+    /** The complete-by-default selection for this model's own record payload. */
+    selection?: FoirManifestSelection;
+    /** Relations a caller may `include`. Needed to resolve an include's target. */
+    relations?: readonly FoirManifestRelation[];
+}
+/**
+ * One namespace, as the printer needs it.
+ *
+ * A namespace op is a `FoirManifestOp` exactly as a model op is, which is what
+ * makes `foir.ns.search.searchRecords()` and `foir.page.findMany()` the same
+ * code path below rather than two printers that agree by inspection.
+ */
+export interface FoirSelectionNamespace {
+    /** Op token → root field, argument types and the resolved shape of the result. */
+    ops?: Readonly<Record<string, FoirManifestOp>>;
+}
+/** Model key → its selection. What `foir types` emits as `foirSelections`. */
+export type FoirSelections = Readonly<Record<string, FoirSelectionModel>>;
+/** Namespace name → its ops. What `foir types` emits as `foirNamespaceSelections`. */
+export type FoirNamespaceSelections = Readonly<Record<string, FoirSelectionNamespace>>;
+/** Union type name → its expansion. What `foir types` emits as `foirSelectionUnions`. */
+export type FoirSelectionUnions = Readonly<Record<string, FoirManifestSelectionUnion>>;
+/** Everything the printer reads. `FoirManifest` satisfies it as-is. */
+export interface FoirSelectionSource {
+    models: FoirSelections;
+    namespaces?: FoirNamespaceSelections;
+    selectionUnions?: FoirSelectionUnions;
+}
+/**
+ * `_id` is emitted whatever the caller asked for — the server's own
+ * `protectedSelectionFields` does the same, and a record you cannot address is
+ * not a useful answer. Named here so `pick` adds it back and `omit` refuses it.
+ *
+ * Exported because the subject registry reads it back off the response: every
+ * record in a response carries this key precisely because no narrowing can
+ * remove it, and that guarantee is this constant's, not the registry's.
+ */
+export declare const PROTECTED_ROOT_FIELD = "_id";
+/**
+ * Print a complete selection body from a resolved tree, with no narrowing.
+ *
+ * The one entry point for a caller that has a `ManifestSelection` and wants the
+ * whole of it — today, the subscription transport, whose payload trees the
+ * manifest publishes exactly as it publishes a model's.
+ *
+ * It exists so there is ONE implementation of "walk a resolved tree and emit
+ * braces". Every rule a reader would otherwise have to re-derive lives in
+ * `printFields`: relations are include-governed and skipped, a `truncated` field
+ * degrades to `__typename` rather than an illegal empty body, a union emits
+ * `__typename` plus one inline fragment per member, a `model` reference expands
+ * to that model's published tree, and an alias prints as `alias: key`. A second
+ * walk elsewhere in this package would be correct on the day it was written and
+ * wrong on the day any of those changed.
+ *
+ * `isRoot` is false: the `_id` protection is a property of a MODEL's root
+ * selection, and an event payload has no records in it to address.
+ */
+export declare function printFoirSelectionBody(fields: readonly FoirManifestSelectionField[], unions: FoirSelectionUnions, models?: FoirSelections): string;
+/**
+ * Where a payload puts a record, and which model it is.
+ *
+ * `record` names one outright, AT THE PAYLOAD ROOT — an empty path. An `object`
+ * payload reaches one through a `model` reference at some depth (`edges.node`,
+ * `record`), and the path is the RESPONSE keys to it, so an aliased field
+ * contributes its alias rather than its key.
+ *
+ * The empty path is therefore not merely a position: it is the manifest saying
+ * this op's result IS one record, which is what the subject registry reads as
+ * "the caller addressed this record by name".
+ */
+export interface FoirRecordPath {
+    /** Response keys from the root field's value down to the record. */
+    path: readonly string[];
+    /** Model key whose published `selection` is printed at that position. */
+    modelKey: string;
+}
+/** One printed operation, and what the transport needs to route it. */
+export interface FoirDocumentPlan {
+    /** The document text. Also the thing that gets hashed for APQ. */
+    document: string;
+    /** The argument values, sent beside the document. Empty when the op takes none. */
+    variables: Record<string, unknown>;
+    /** True when the op lives on the Mutation root. Decides the route and the keyword. */
+    mutation: boolean;
+    /** The single root field the response is keyed by. */
+    rootField: string;
+    /**
+     * Fields this document selects, in the unit the server's complexity ceiling is
+     * denominated in — the same number `CompiledQuery.Fields` carries on the
+     * server side.
+     *
+     * Measured while printing rather than derived afterwards, and exposed rather
+     * than kept private so it is TESTABLE against the document it describes: a
+     * counter nobody can compare to the artefact is a counter that drifts from it.
+     *
+     * OPTIONAL because a plan is not only something this file returns — a
+     * hand-built one is a real pattern for executing a document the printer did
+     * not produce, and requiring the count there would mean requiring a caller to
+     * invent a number about a document this code never measured. Everything
+     * `planFoirModelCall` / `planFoirNamespaceCall` return sets it.
+     */
+    fields?: number;
+    /**
+     * Where the records this document selects sit in the response, and which
+     * model each one is.
+     *
+     * Read by the subject registry (`subjects.ts`) to answer "what did this page
+     * fetch" without inspecting the response's shape — the manifest already said
+     * where the records would be, so hunting for objects carrying an `_id` would
+     * be re-deriving something published.
+     *
+     * OPTIONAL for the same reason `fields` is: a hand-built plan for a document
+     * this printer never produced has no published payload to read positions off,
+     * and inventing them would put subjects against records nobody can vouch for.
+     * Absent means "this call records nothing", never "this call fetched nothing".
+     */
+    records?: readonly FoirRecordPath[];
+}
+/** What a model call carries, already split out of the caller's flat query object. */
+export interface FoirCall {
+    model: string;
+    op: string;
+    args: Record<string, unknown>;
+    include?: Record<string, unknown>;
+    omit?: readonly string[];
+    pick?: readonly string[];
+    /** Union levels to expand. See `FoirNamespaceCall.depth`. */
+    depth?: number;
+}
+/** What a namespace call carries. Same shape, addressed by namespace. */
+export interface FoirNamespaceCall {
+    namespace: string;
+    op: string;
+    args: Record<string, unknown>;
+    include?: Record<string, unknown>;
+    omit?: readonly string[];
+    pick?: readonly string[];
+    /**
+     * How many union levels to expand, default `1`.
+     *
+     * A block union's members can themselves carry block unions, and the server
+     * refuses to expand a union already on the current path — so the complete
+     * document stops one level in and says so, publishing the union name it
+     * stopped in front of. Each level above 1 spends one of those stopping points.
+     *
+     * It is a BUDGET rather than a setting, though a much larger one since
+     * TTS-1448: on a real project the same op measures 318 fields at level 1, 468
+     * at level 2 and 618 at level 3, against a server ceiling of 10,000. Those
+     * were 837 / 3,513 / 14,217 while a union position was charged every member it
+     * could hold rather than the one a value can be.
+     *
+     * What a level costs is one more expansion at each STOPPING POINT inside the
+     * expansion, so it still compounds where a member carries several union-typed
+     * fields — and it no longer grows at all with how many members the union has.
+     * Where a level does cross the ceiling, `planCall` refuses and names the
+     * count, rather than letting the server answer with a number the caller
+     * cannot act on.
+     */
+    depth?: number;
+}
+/**
+ * Turn a model call into a document.
+ *
+ * Every op is printable or REFUSED. There is no third answer: an op the
+ * manifest describes no payload for is one this client would have to invent a
+ * shape for, and inventing one is what this design exists to stop.
+ */
+export declare function planFoirModelCall(source: FoirSelectionSource, call: FoirCall): FoirDocumentPlan;
+/**
+ * Turn a namespace call into a document.
+ *
+ * Identical to `planFoirModelCall` below the addressing, and deliberately the
+ * same function underneath: a namespace op is a `FoirManifestOp` carrying a
+ * payload exactly as a model op is, so `foir.ns.search.searchRecords()` is
+ * printed by the code that prints `foir.page.findMany()` rather than by a
+ * second printer that agrees with it by inspection.
+ */
+export declare function planFoirNamespaceCall(source: FoirSelectionSource, call: FoirNamespaceCall): FoirDocumentPlan;
+/** True when a hand-written document is a mutation, so it never takes the shared lane. */
+export declare function isFoirMutationDocument(documentText: string): boolean;

package/dist/data/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `@foir/sdk/data` — the typed data client.
+ *
+ * A typed client over the same GraphQL endpoint `@foir/sdk/client` posts to,
+ * shaped by the credential you hand it. It sends a GraphQL document like every
+ * other consumer — one execution surface, the same executor, the same scope
+ * checks, the same response cache — but you never write one: the document is
+ * printed from the selection tree the manifest publishes for that op.
+ *
+ * What you get over the hand-written GraphQL path: no `.graphql` documents, no
+ * `graphql-codegen` step, and **no `graphql` dependency at all**. Printing a
+ * pre-resolved tree is string building. 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 * as generated from './foir.generated';
+ *
+ * const foir = createFoirClient({
+ *   apiUrl: 'https://api.foir.dev',
+ *   apiKey: process.env.PLATFORM_API_KEY!,
+ *   generated,
+ * });
+ *
+ * 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('{ designTokens { name value } }');
+ * ```
+ *
+ * `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, FoirManifestOpPayload, FoirManifestRelation, FoirManifestScalar, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionMember, FoirManifestSelectionUnion, FoirManifestSubscription, FoirManifestSubscriptionArgScope, FoirManifestUnclassifiedField, } from './manifest';
+export { planFoirModelCall, planFoirNamespaceCall } from './document';
+export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
+export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
+export type { FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Reference, Richtext, Video, } from './builtins';
+/**
+ * Pre-TTS-1391 spellings. The `<Name>Block` wrappers and the `<Name>Value`
+ * split are the same thing as the types above — an item IS its value — so each
+ * of these is an alias, not a separate shape.
+ *
+ * `MediaBlock`, `TextBlock`, `FlexibleBlock` and `FoirBlockMeta` are NOT here:
+ * they described a wrapper, a member and an envelope the platform no longer
+ * emits, so there is nothing for them to alias. See `builtins.ts`.
+ */
+export type { FileBlock, GeoPointValue, ImageBlock, ImageValue, ReferenceBlock, ReferenceValue, RichtextBlock, RichtextValue, VideoBlock, VideoValue, } from './builtins';
+export { foirDataEndpoint, foirRoute } from './transport';
+export type { FoirClientConfig, FoirGeneratedModule, FoirLane, FoirLaneReason, FoirRouteDecision, FoirRouteInput, FoirSchemaDrift, } from './transport';
+export { foirSocketEndpoint, FoirSocketTransport } from './ws-transport';
+export type { FoirReconnectPolicy, FoirSubscribeRequest, FoirSubscription, FoirSubscriptionHandlers, FoirWebSocketFactory, FoirWebSocketLike, } from './ws-transport';
+export { printSubscriptionDocument } from './subscription-document';
+export type { FoirSubscriptionArgument, PrintSubscriptionDocumentInput, } from './subscription-document';
+export type { FoirExecutionSubscribeOptions, FoirJobProgressEvent, FoirModelSubscriptions, FoirNamespaceSubscriptions, FoirNotificationEvent, FoirOperationExecutionEvent, FoirRecordChangedEvent, } from './subscriptions';
+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';