@foir/sdk 0.7.0 → 0.8.0

package/dist/data/subjects.d.ts

@@ -0,0 +1,221 @@
+/**
+ * The subject registry — which records this client fetched.
+ *
+ * ---------------------------------------------------------------------------
+ * What it is for
+ * ---------------------------------------------------------------------------
+ *
+ * An annotation surface — a comment widget, a feedback button, a review prompt
+ * — has to say what it is about. Every tool that does this anchors to a URL or
+ * to a CSS selector, and both break the moment the page is redesigned, the
+ * route changes, or the reader is served a different locale or variant.
+ *
+ * A page rendered through this client does not have that problem, because the
+ * client already knows: it printed the document, it named the model, and every
+ * record in the response carries `_id` (the selection model protects it — see
+ * `PROTECTED_ROOT_FIELD`). So the anchor can be the RECORD, which survives all
+ * three, and it can be derived rather than configured.
+ *
+ * ```ts
+ * const subjects = createFoirSubjectRegistry();
+ * const foir = createFoirClient({ apiUrl, apiKey, generated, subjects });
+ *
+ * await foir.article.findUnique({ naturalKey: 'about-us' });
+ * subjects.subject(); // { modelKey: 'article', recordId: 'kx7p…' }
+ * ```
+ *
+ * Nothing here maps a URL, and nothing here may start to. A registry that fell
+ * back to the address bar would reintroduce exactly the fragility the record
+ * anchor exists to remove, and it would do so silently — the anchor would look
+ * identical and would point somewhere else after the next redesign.
+ *
+ * ---------------------------------------------------------------------------
+ * Why it is opt-in, and off unless you build one
+ * ---------------------------------------------------------------------------
+ *
+ * A list of the records a page fetched is a DISCLOSURE SURFACE. It names
+ * content by model key and id, including records a visitor never saw rendered —
+ * a draft pulled for an editor, a related record fetched and then filtered out
+ * in the template, the twelve nav pages behind a menu. Handing that to whatever
+ * else runs on the page (an analytics tag, an embedded widget, a browser
+ * extension) is a decision with consequences, and it is not this package's
+ * decision to make.
+ *
+ * So it is not a flag that defaults to false — it is an OBJECT the host
+ * constructs and owns. There is no configuration that turns it on by accident,
+ * the host holds the only reference, and its lifetime is the host's: a registry
+ * built per request on an edge runtime cannot outlive that request, which is the
+ * same reason nothing in this client keeps module-level state.
+ *
+ * The corollary is the one warning worth repeating: a registry built at MODULE
+ * scope on a multi-tenant edge worker is shared across tenants, exactly like a
+ * module-level response cache would be. Build one per client.
+ *
+ * ---------------------------------------------------------------------------
+ * Where the subjects come from
+ * ---------------------------------------------------------------------------
+ *
+ * From the plan, not from the response's shape. `planCall` derives the record
+ * positions from the payload the manifest published (`FoirDocumentPlan.records`)
+ * — the same walk that decides where `pick`/`omit` land — so the registry reads
+ * the response at the positions the server said records would be, rather than
+ * hunting for objects that happen to carry an `_id`.
+ */
+import { type FoirDocumentPlan } from './document';
+/**
+ * One thing an annotation can be about.
+ *
+ * `recordId` / `modelKey` and not `id` / `model`, matching
+ * `FoirRecordChangedEvent` in `subscriptions.ts`: a subscription event and a
+ * fetched subject name the same pair, and two spellings of one pair is how a
+ * consumer ends up writing an adapter between two halves of one SDK.
+ */
+export interface FoirSubject {
+    /** The record's model key, e.g. `article`. */
+    modelKey: string;
+    /** The record's `_id`. */
+    recordId: string;
+    /**
+     * A human label for the record, when one is available. See
+     * `FoirSubjectOptions.label` for where it comes from and why the client does
+     * not pick a field on its own.
+     */
+    label?: string;
+}
+/**
+ * How a record reached the registry.
+ *
+ * NOT a heuristic: it is read off the op's published payload. A payload whose
+ * kind is `record` IS one record, which means the caller addressed one record by
+ * name (`findUnique`, `create`, a lookup); a record reached through a field of
+ * an `object` payload arrived inside something — a connection's `edges.node`, a
+ * search wrapper's `record`.
+ *
+ * That distinction is what lets `subject()` answer at all. A page renders FROM
+ * the record it addressed and merely LISTS the rest, and the manifest already
+ * says which is which, so the client does not have to guess from result counts
+ * or field names.
+ */
+export type FoirSubjectOrigin = 'record' | 'collection';
+/** What `FoirSubjectRegistry.add` takes. */
+export interface FoirSubjectEntry {
+    modelKey: string;
+    recordId: string;
+    /**
+     * Defaults to `record`, which is what a hand-seeded entry means: you named
+     * this record deliberately. The data path passes the origin it read off the
+     * plan.
+     */
+    origin?: FoirSubjectOrigin;
+    /**
+     * The record as it arrived, for the labeller to read. Optional, because a
+     * host seeding a subject from an id has no record object to hand.
+     */
+    record?: Readonly<Record<string, unknown>>;
+    /** An explicit label. Wins over the labeller and over `_naturalKey`. */
+    label?: string;
+}
+export interface FoirSubjectOptions {
+    /**
+     * Turn a record into the label a widget shows: `"About Us"` rather than
+     * `article/kx7p…`.
+     *
+     * There is no default that reads one of your fields, and that is deliberate.
+     * The manifest publishes a model's scalars and their types; it does not
+     * publish which one is the title, because there is no such concept — one
+     * project calls it `title`, the next `name`, the next `headline`. A client
+     * that picked `title` when it saw one would label most projects correctly and
+     * mislabel the rest, silently, in the one string a reader actually reads.
+     *
+     * So the field is yours to name, in one line:
+     *
+     * ```ts
+     * createFoirSubjectRegistry({
+     *   label: (record) => (record.title as string) ?? null,
+     * });
+     * ```
+     *
+     * Return `null` or `undefined` for "no label" — the subject is still
+     * recorded, just without one. It must not throw: see `recordFoirSubjects`.
+     */
+    label?: (record: Readonly<Record<string, unknown>>, subject: FoirSubject) => string | null | undefined;
+}
+export interface FoirSubjectRegistry {
+    /**
+     * Record one subject.
+     *
+     * The data path calls this for you. Call it yourself to seed a subject this
+     * client did not fetch — a server-rendered page whose record was read on the
+     * server, or a record that arrived through `foir.raw()`, which prints no
+     * published payload and therefore has no record positions to read.
+     */
+    add(entry: FoirSubjectEntry): void;
+    /**
+     * Every record recorded so far, de-duplicated on `modelKey` + `recordId` and
+     * ordered least-recently-fetched first — so the last entry is the last record
+     * this client saw, whether or not it was addressed by name.
+     *
+     * This is what a widget offers when it wants to let the reader choose, and it
+     * is the honest answer for a page whose data all came out of lists.
+     */
+    fetched(): readonly FoirSubject[];
+    /**
+     * The subject to annotate: your override if you set one, otherwise the last
+     * record this client addressed BY NAME.
+     *
+     * One rule, and no case analysis behind it. A record that only ever appeared
+     * inside a list is never promoted — a page that fetched twelve nav entries and
+     * nothing else has no subject, and saying so is better than picking one of the
+     * twelve. Use `fetched()` or `setSubject()` there.
+     */
+    subject(): FoirSubject | undefined;
+    /**
+     * Pin the subject, overriding whatever was fetched. `null` drops the override
+     * and goes back to the fetched answer.
+     */
+    setSubject(subject: FoirSubject | null): void;
+    /**
+     * Forget everything: the recorded records AND the override.
+     *
+     * A single-page app must call this when it navigates. Without it the registry
+     * accumulates every record the session ever touched and `subject()` keeps
+     * answering with a record from a page the reader has left.
+     */
+    clear(): void;
+    /**
+     * Run `listener` after every change, and return the function that stops it.
+     *
+     * For a widget mounted before the data resolves. Listeners run synchronously
+     * in registration order; one that throws does not stop the others, and the
+     * failure is reported rather than dropped (see `recordFoirSubjects`).
+     */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Build a registry.
+ *
+ * Per client, never at module scope — see the file header. It is handed to
+ * `createFoirClient` as `subjects`, and the host keeps the same reference to
+ * read from.
+ */
+export declare function createFoirSubjectRegistry(options?: FoirSubjectOptions): FoirSubjectRegistry;
+/**
+ * Record what one call fetched.
+ *
+ * A no-op without a registry, which is what "off by default" means at runtime:
+ * a client built without `subjects` walks nothing and allocates nothing.
+ *
+ * # Errors are not swallowed here
+ *
+ * The only things that can fail are the host's own: a `label` function, or a
+ * `subscribe` listener. Both are re-thrown, wrapped in a message that says the
+ * REQUEST succeeded so the failure cannot be read as a transport fault.
+ *
+ * Catching them would be worse than it looks. A subject that silently failed to
+ * record does not degrade to "no annotation offered" — it degrades to the
+ * PREVIOUS subject still being the answer, so the widget offers to comment on
+ * the record the reader was looking at a moment ago. A loud failure in a
+ * function the host wrote is strictly better than an annotation filed against
+ * the wrong record.
+ */
+export declare function recordFoirSubjects(registry: FoirSubjectRegistry | undefined, plan: Pick<FoirDocumentPlan, 'records'>, result: unknown): void;

package/dist/data/subscription-document.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Printing a subscription document from a resolved selection tree.
+ *
+ * ---------------------------------------------------------------------------
+ * Why this file is thin
+ * ---------------------------------------------------------------------------
+ *
+ * The body of a subscription document is a selection body like any other, and
+ * `document.ts` already walks one: relations skipped, `truncated` degraded to
+ * `__typename`, unions expanded to `__typename` plus an inline fragment per
+ * member, aliases printed as `alias: key`. Those rules belong to the tree, not
+ * to the operation type, so this file does NOT re-implement them — it calls
+ * `printFoirSelectionBody` and adds only what is genuinely different about a
+ * subscription: the `subscription` keyword, the variable declarations, and the
+ * single root field.
+ *
+ * That split is deliberate. This file previously carried its own copy of the
+ * walk, written before `document.ts` existed; two implementations of one rule
+ * set in one directory is the parallel construction this epic exists to remove,
+ * and the copy would have been correct only until the next rule changed.
+ *
+ * Nothing here inspects a GraphQL type, and nothing here may start to. The
+ * server resolves the tree once per schema version — unions expanded, aliases
+ * assigned, cycles broken, budget counted — so printing is string building. If
+ * this ever needs to know what a field IS, the tree is under-specified and the
+ * fix belongs in the manifest.
+ *
+ * ---------------------------------------------------------------------------
+ * Why it is not APQ
+ * ---------------------------------------------------------------------------
+ *
+ * The HTTP lane hashes its document and sends the hash, because it re-sends the
+ * same document on every request. graphql-ws sends the document ONCE, in the
+ * `subscribe` frame, and the server then pushes events over it for the life of
+ * the subscription. The wire-cost argument does not apply to a stream, so the
+ * document goes whole and the server needs no registry to serve it.
+ */
+import { type FoirSelectionUnions } from './document';
+import type { FoirManifestSelection } from './manifest';
+/**
+ * One argument a subscription root field is called with, bound to a variable.
+ *
+ * Variables rather than inline literals because the values are caller data:
+ * inlining would mean escaping a string into a document, which is the one place
+ * a client can construct an injection. The `subscribe` frame carries a
+ * `variables` object beside the query, so there is no reason to inline.
+ */
+export interface FoirSubscriptionArgument {
+    /** Argument name, e.g. `modelKey`. */
+    name: string;
+    /** GraphQL type for the variable declaration, e.g. `String!`. */
+    type: string;
+}
+export interface PrintSubscriptionDocumentInput {
+    /** The Subscription root field to select. */
+    field: string;
+    /** Operation name, for readability in server logs and dev tools. */
+    operationName: string;
+    /** Arguments the field takes, in the order they should be declared. */
+    args?: readonly FoirSubscriptionArgument[];
+    /** The payload's resolved selection. */
+    selection: FoirManifestSelection;
+    /** Union expansions the selection references by name. */
+    unions?: FoirSelectionUnions;
+}
+/**
+ * Print a complete subscription document.
+ *
+ * Deterministic: the same inputs always produce the same bytes, because the
+ * server sorts union members and emits fields in a stable order. That matters
+ * for readable diffs in tests and for anything that ever wants to recognise a
+ * document, and it costs nothing to preserve — so this must never reorder
+ * anything it is handed.
+ */
+export declare function printSubscriptionDocument(input: PrintSubscriptionDocumentInput): string;

package/dist/data/subscriptions.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Subscription addressing — the five Subscription root fields, reached through
+ * the client shape that already exists.
+ *
+ * ```ts
+ * const live = foir.page.onChange({ onData: (e) => revalidate(e.recordId) });
+ * const inbox = foir.ns.notifications.onNotification({ onData: show });
+ * const run = foir.ns.operations.onExecution({ id, onData: render });
+ * live.unsubscribe();
+ * ```
+ *
+ * ---------------------------------------------------------------------------
+ * Why the addressing is what it is
+ * ---------------------------------------------------------------------------
+ *
+ * `recordChanged` takes the model as an ARGUMENT, and the argument is exactly
+ * what the client's model accessor already carries — `foir.page` IS
+ * `modelKey: "page"`. So it hangs off the model, and the one argument the
+ * server gates on is supplied by the address rather than by the caller. That is
+ * also why a model the credential may not watch is a compile-time absence
+ * rather than a runtime refusal: it is not in `FoirSchema`.
+ *
+ * The other four are project-independent platform surfaces, so they hang off
+ * the namespace that owns them: `notification` under `notifications`,
+ * `jobProgress` and both execution streams under `operations`.
+ *
+ * Every subscription method is named `on…`, so a call site that opens a stream
+ * is distinguishable at a glance from one that awaits a value — and no
+ * generated op name can collide, because the server never emits a root field
+ * called `on…`.
+ *
+ * ---------------------------------------------------------------------------
+ * Where the document comes from
+ * ---------------------------------------------------------------------------
+ *
+ * From `GET /v1/manifest`, through the CLIENT's memoised loader — the same one
+ * the query path falls back to and the drift check reads. Each subscription
+ * carries a resolved selection tree, which `subscription-document.ts` prints
+ * with the same walk the query path prints models with.
+ *
+ * A subscribing client therefore fetches the descriptor once even when
+ * `config.selections` was supplied, because `selections` carries MODEL trees and
+ * nothing generates subscription ones yet. That is a real cost and it is stated
+ * rather than hidden — but it is ONE fetch, memoised across every subscription
+ * and shared with the query path, sitting behind a long-lived socket. `client.ts`
+ * rejects a round trip in front of every query for good reason; in front of a
+ * socket that will live for minutes it is noise.
+ */
+import type { FoirManifest } from './manifest';
+import type { FoirClientConfig } from './transport';
+import { type FoirSubscription, type FoirSubscriptionHandlers } from './ws-transport';
+/** `recordChanged` — a record in one model was created, updated or removed. */
+export interface FoirRecordChangedEvent {
+    recordId: string;
+    modelKey: string;
+    /** `created`, `updated`, `published`, `unpublished` or `deleted`. */
+    action: string;
+    /** Actor, when a user made the change. Absent for system and service callers. */
+    userId?: string | null;
+    /** The durable event this projects — the same id a webhook delivery carries. */
+    eventId?: string | null;
+    /** Event family name, e.g. `RECORD_UPDATED`. The name a hook subscribes to. */
+    event?: string | null;
+    /**
+     * Platform sequence, assigned in commit order and monotonic per project.
+     * Apply last-write-wins: keep the highest seq applied per record and discard
+     * anything at or below it.
+     */
+    seq?: number | null;
+}
+/** `notification` — one notification for the subscribing user. */
+export interface FoirNotificationEvent {
+    userId: string;
+    /** `notification`, `announcement` or `mention`. */
+    type: string;
+    title?: string | null;
+}
+/** `jobProgress` — a background job's lifecycle. */
+export interface FoirJobProgressEvent {
+    jobId: string;
+    queue?: string | null;
+    /** `started`, `progress`, `completed` or `failed`. */
+    status: string;
+    /** 0-100 when reported. */
+    progress?: number | null;
+    error?: string | null;
+}
+/** `operationExecution` / `operation{Op}Execution` — one execution's progress. */
+export interface FoirOperationExecutionEvent {
+    id: string;
+    /** `pending`, `dispatched`, `running`, `completed`, `failed`, `cancelled` or `timed_out`. */
+    status: string;
+    /** 0-100; null on terminal events. */
+    progressPct?: number | null;
+    progressMessage?: string | null;
+    progressMetadata?: unknown;
+    progressUpdatedAt?: string | null;
+    /** Present on `status: completed`. Typed per operation only on the typed field. */
+    resultJson?: unknown;
+    /** Present on `status: failed` or `timed_out`. */
+    errorJson?: unknown;
+}
+/** Options for `foir.ns.operations.onExecution`. */
+export type FoirExecutionSubscribeOptions = FoirSubscriptionHandlers<FoirOperationExecutionEvent> & {
+    /** Execution id, as returned by `execute<Op>`. */
+    id: string;
+    /**
+     * Operation key, to subscribe to that operation's TYPED stream
+     * (`operation{Op}Execution`) instead of the generic one.
+     *
+     * The key is matched against the field names the manifest publishes rather
+     * than converted into one: the server owns the PascalCase rule, and
+     * re-deriving it here is the naming drift the SDK contract forbids. An
+     * operation with no typed subscription fails with the list of fields that do
+     * exist, rather than silently opening the generic stream under a name the
+     * caller did not ask for.
+     */
+    operation?: string;
+};
+/** The subscriptions a model accessor carries. */
+export interface FoirModelSubscriptions {
+    /**
+     * Stream changes to this model's records.
+     *
+     * The socket refuses a model this credential may not read, but the model is
+     * not in `FoirSchema` in that case, so the refusal is a type error first.
+     */
+    onChange(handlers: FoirSubscriptionHandlers<FoirRecordChangedEvent>): FoirSubscription;
+}
+/**
+ * The subscriptions one namespace carries, by name.
+ *
+ * Keyed on the namespace NAME rather than added to every namespace, because
+ * `foir.ns.search.onNotification` should not type-check. The empty branch is
+ * what every other namespace gets.
+ */
+export type FoirNamespaceSubscriptions<NK> = NK extends 'notifications' ? {
+    /** Stream this caller's own notifications. Scoped server-side; no arguments. */
+    onNotification(handlers: FoirSubscriptionHandlers<FoirNotificationEvent>): FoirSubscription;
+} : NK extends 'operations' ? {
+    /** Stream background-job lifecycle events for this project. */
+    onJobProgress(handlers: FoirSubscriptionHandlers<FoirJobProgressEvent>): FoirSubscription;
+    /** Stream one operation execution's progress until it reaches a terminal state. */
+    onExecution(options: FoirExecutionSubscribeOptions): FoirSubscription;
+} : {};
+/** Does this (address, property) pair name a subscription rather than an op? */
+export declare function isModelSubscriptionMethod(name: string): boolean;
+export declare function isNamespaceSubscriptionMethod(namespace: string, name: string): boolean;
+/**
+ * The runtime half: resolves a call site to a route, prints its document from
+ * the manifest, and hands it to the socket.
+ *
+ * One instance per client, created lazily — a client that never subscribes
+ * neither fetches a manifest nor opens a socket.
+ */
+export declare class FoirSubscriptionRouter {
+    private readonly transport;
+    private readonly loadManifest;
+    /**
+     * `loadManifest` is the client's own memoised descriptor loader, passed in
+     * rather than rebuilt. One client is one credential and one descriptor; a
+     * fetcher of our own would race the query path's for the same bytes and could
+     * end up holding a different schema version than the documents the query path
+     * is printing from.
+     */
+    constructor(config: FoirClientConfig, loadManifest: () => Promise<FoirManifest>);
+    dispose(): void;
+    /** `foir.<model>.onChange(...)`. */
+    model(modelKey: string, method: string, input: Record<string, unknown>): FoirSubscription;
+    /** `foir.ns.<namespace>.on…(...)`. */
+    namespace(namespace: string, method: string, input: Record<string, unknown>): FoirSubscription;
+    /**
+     * Resolve the route's document and subscribe.
+     *
+     * The handle is returned synchronously and the manifest fetch runs behind it,
+     * so a caller can hold and cancel a subscription before the descriptor has
+     * arrived. Cancelling in that window is honoured: `cancelled` is checked
+     * after the await, and the inner handle is never created.
+     */
+    private open;
+}