@fabrika/app 0.9.0-dev.1 → 0.9.0-dev.3

package/types/src/jobs/runner.d.ts

@@ -0,0 +1,145 @@
+import type { IamMembership } from '@fabrika/auth';
+import { type ContractArtifact } from '@fabrika/auth-core';
+import type { CapabilityAuthority } from '@fabrika/db/capability';
+import { type DataAccess, type FrameworkTables } from '@fabrika/db/framework';
+import { type StoredFileKinds } from '../files/kinds';
+import { type CapabilityMint } from '../implement/capability';
+import type { ContractDatabase } from '../implement/implement';
+import type { SignedTokens } from '../implement/tokens';
+import { type AppUrl } from '../implement/urls';
+import { type WorkloadCredential } from '../implement/workload';
+import { type MailTransports } from './mail';
+import type { OperationsReporter } from './report';
+/**
+ * The lease outlives an attempt's deadline by this much: the runner renews or finishes a timed-out attempt's lease,
+ * and no other run takes it over meanwhile. The attempt's writes stop at its deadline regardless.
+ */
+export declare const LEASE_GRACE_MS = 60000;
+/** How often the serving process checks every job for a crashed run and for a schedule that stopped. */
+export declare const JOB_CHECK_INTERVAL_MS = 60000;
+/**
+ * Why a run failed. Fixed codes only: an application error's name and message may carry a secret, so neither is
+ * ever logged or returned. Only the report to Operations carries them, scrubbed (ADR-0059).
+ */
+export type JobFailureCode = 'timeout' | 'lease_lost' | 'handler_failed'
+/** The data layer refused a statement or an operation tree (`QueryRefusedError`): its reason names why. */
+ | 'query_refused'
+/** A capability or a handle was refused: forged, ended, of other work, or of another kind than the call takes. */
+ | 'capability_refused' | 'driver_failed' | 'crashed'
+/** IAM refused the job's key: the attempt mints no capability. */
+ | 'unauthorized'
+/** IAM could not be asked for the job's token. */
+ | 'iam_unavailable'
+/** The process stopped a kicked run while shutting down; the schedule runs the job again. */
+ | 'stopped'
+/** The transport refused a message the handler did not catch; `reason` is the `EmailDeliveryError` code. */
+ | 'mail_failed';
+export type JobRunResult = {
+    readonly status: 'succeeded';
+    readonly attempts: number;
+}
+/** `reason` is a framework refusal's catalog key (`query_refused`, `capability_refused`), present only for one. */
+ | {
+    readonly status: 'failed';
+    readonly attempts: number;
+    readonly code: JobFailureCode;
+    readonly reason?: string;
+}
+/** Another run holds the lease: an overlapping run does not start. */
+ | {
+    readonly status: 'skipped';
+};
+/** The runner's waits; the lease's times are always the database's. */
+export interface JobClock {
+    /** Resolves after `ms`, or as soon as `signal` aborts. */
+    wait(ms: number, signal: AbortSignal): Promise<void>;
+    /** In [0, 1): the jitter of a retry's backoff. */
+    random(): number;
+}
+export interface JobRunOptions {
+    readonly clock?: JobClock;
+    /** Where failures and missed runs go; by default the one `boot` built from `FABRIKA_OPERATIONS_DSN`. */
+    readonly reporter?: OperationsReporter;
+}
+/**
+ * A job the framework runs itself under a reserved name (`FILE_SCAN_JOB`): no handler, no key, no capability, one
+ * attempt. It holds its lease like an application job, and every write of its run is fenced by it.
+ */
+export interface FrameworkJob {
+    readonly name: string;
+    readonly schedule: string;
+    readonly timeoutMs: number;
+    /** One run; `signal` aborts when the attempt's deadline passes. A throw fails the run. */
+    run(reporter: OperationsReporter, signal: AbortSignal): Promise<void>;
+}
+/** The contract's jobs, bound to their handlers by `boot`, and the framework's own. */
+export interface ContractJobs {
+    /** The contract's `c.cron` jobs; `run` also takes the name of a framework job the contract needs. */
+    readonly names: readonly string[];
+    run(name: string, options?: JobRunOptions): Promise<JobRunResult>;
+    /**
+     * Registers every job (its first-seen time), reports a run that crashed and a job that has not succeeded within
+     * twice its period. The serving process calls it every `JOB_CHECK_INTERVAL_MS`; it never throws.
+     */
+    check(options?: Pick<JobRunOptions, 'reporter'>): Promise<void>;
+}
+/** A run that cannot start: an unknown job. Its message is framework-authored. */
+export declare class JobError extends Error {
+    readonly name = "JobError";
+}
+export declare const systemClock: JobClock;
+/** Where `fabrika app dev` shows what a handler threw, on the developer's own machine; nothing else sets one. */
+export type HandlerErrorSink = (where: string, error: unknown) => void;
+export interface JobBindingInput {
+    readonly artifact: ContractArtifact;
+    /** The handler tree `boot` binds; a job's handler is `handlers.jobs.<name>`. */
+    readonly handlers: unknown;
+    readonly database: ContractDatabase | null;
+    /** The framework side of `@fabrika/db`, bound by `boot`; `null` when the application has no such layer. */
+    readonly framework: FrameworkTables | null;
+    readonly ownedDimensions: ReadonlySet<string>;
+    /** Where failures and missed runs go: Operations, or the server log without a DSN. */
+    readonly reporter: OperationsReporter;
+    /** `job:<name>` → the job's key; `boot` refuses a job without one. */
+    readonly credentials: ReadonlyMap<string, WorkloadCredential>;
+    /** The runtime's capability mint, which `boot` alone holds. */
+    readonly mint: CapabilityMint;
+    /** The mini-ORM of the bound `scoped(tables)` layer, behind a staged-kit job's `ctx.db`. */
+    readonly data: DataAccess | null;
+    /** The contract's file kinds, behind a staged-kit job's `ctx.files.put` and `.open`; `null` without any. */
+    readonly fileKinds?: StoredFileKinds | null;
+    /** The framework's own jobs this contract needs: the scan of its `scan: true` file kinds, and the file sweep. */
+    readonly frameworkJobs?: readonly FrameworkJob[];
+    /** IAM's membership operations, which a job that `issues` links asks; `null` when the adapter supplies none. */
+    readonly membership: IamMembership | null;
+    /** The runtime's authority, which a `Ref` passed to IAM must resolve with. */
+    readonly capabilities: CapabilityAuthority;
+    /** Each dimension's containers, nearest first: a link's chain. */
+    readonly containers: ReadonlyMap<string, readonly string[]>;
+    /** What a job's handler threw, for `fabrika app dev`; without it the error is only its fixed code. */
+    readonly revealHandlerErrors?: HandlerErrorSink;
+    /** The transports of the jobs that declare `mailer`, which `boot` resolved. */
+    readonly mail: MailTransports;
+    /** The environment's signed tokens, which a job that declares `signs` signs with. */
+    readonly tokens?: SignedTokens;
+    /** `ctx.url`: absolute links to the application's own procedures; without it every link is refused. */
+    readonly url?: AppUrl;
+}
+export interface BoundJobs {
+    readonly jobs: ContractJobs;
+    /** The handler ids the jobs took (`jobs.<name>`), so `boot` finds no undeclared handler among them. */
+    readonly declared: readonly string[];
+    /**
+     * Kicks the contract job `name`, as a site's `ctx.kick` does after its commit: a run under the job's own key
+     * now, or the shared pending flag for the run holding the lease, which then runs once more after it succeeded. It
+     * waits for no lock, settles when that work has ended and never rejects; the schedule stays the recovery path.
+     */
+    readonly kick: (name: string) => Promise<void>;
+    /**
+     * Aborts every kicked run in flight; a later kick starts none and only sets the pending flag, for a process that is
+     * not stopping; the schedule recovers their work.
+     */
+    readonly stopKicks: () => void;
+}
+/** Binds every declared job to its handler, or adds why it cannot run to `problems`. */
+export declare function bindJobs(input: JobBindingInput, problems: string[]): BoundJobs;

package/types/src/jobs/schedule.d.ts

@@ -0,0 +1,15 @@
+export interface CronSchedule {
+    readonly minutes: ReadonlySet<number>;
+    readonly hours: ReadonlySet<number>;
+    readonly daysOfMonth: ReadonlySet<number>;
+    readonly months: ReadonlySet<number>;
+    readonly daysOfWeek: ReadonlySet<number>;
+    /** Both day fields name days: a day is due when either matches (Vixie cron). */
+    readonly eitherDay: boolean;
+}
+/** The schedule of a five-field expression, or `null` when it is not one this runner reads. */
+export declare function parseCron(expression: string): CronSchedule | null;
+/** The latest `count` due minutes at or before `at`, newest first; fewer when the schedule is that rare. */
+export declare function previousDue(schedule: CronSchedule, at: Date, count: number): Date[];
+/** The time between the two latest due minutes at or before `at`, or `null` when there are not two in the window. */
+export declare function periodAt(schedule: CronSchedule, at: Date): number | null;

package/types/src/jobs/scrub.d.ts

@@ -0,0 +1,12 @@
+import type { CapturedEnvironment } from '../implement/environment';
+export declare const REDACTED = "[redacted]";
+/** A shorter value is no credential the platform generates, and scrubbing it would mangle ordinary text. */
+export declare const MIN_SECRET_LENGTH = 8;
+export interface Scrubber {
+    scrub(text: string): string;
+}
+/** Every value of `environment` that is a secret, with the user and password of a URL-shaped one. */
+export declare function secretValues(environment: CapturedEnvironment): string[];
+export declare function secretScrubber(secrets: readonly string[]): Scrubber;
+/** The scrubber of one application environment: its secrets' values, then the credential patterns. */
+export declare function environmentScrubber(environment: CapturedEnvironment): Scrubber;

package/types/src/jobs/types.d.ts

@@ -0,0 +1,92 @@
+import type { EmailDeliveryResult, EmailSenderCapabilities } from '@fabrika/email';
+import type { CronJob, DimensionOf } from '../contract/define';
+import type { FileRef } from '../contract/file';
+import type { AppCapability, Ref, Within } from '../implement/capability';
+import type { AppUrl } from '../implement/urls';
+/** Who a job's writes are stamped with (`createdBy`): the job itself, never a person. */
+export interface JobPrincipal {
+    readonly kind: 'job';
+    /** `job:<name>`. */
+    readonly id: string;
+    readonly job: string;
+}
+/**
+ * What a job handler gets. A capability is minted for a declared action only when the token IAM signed for the job's
+ * key at the start of the attempt carries it, with the job's `scope: 'app'`, and only while this attempt holds the
+ * job's lease: a capability of another attempt is refused, and so is every write after the attempt timed out or lost
+ * the lease.
+ */
+export interface JobContext<A extends string, D extends string> {
+    readonly principal: JobPrincipal;
+    /** This attempt's id; it is also the holder of the job's lease. */
+    readonly runId: string;
+    /** 1 for the first attempt, one more for each retry. */
+    readonly attempt: number;
+    /** Aborted when the attempt times out or loses its lease. */
+    readonly signal: AbortSignal;
+    /** Every value of `dimension`, for a declared action: what a list or an aggregate takes. */
+    within<const Act extends A, const Dim extends D>(action: Act, dimension: Dim): Within<Dim, Act>;
+    /** One object of `dimension` for a declared action, located now: what a write takes. A missing object is NotFound. */
+    ref<const Act extends A, const Dim extends D>(action: Act, dimension: Dim, id: string): Promise<Ref<Dim, Act>>;
+    /** A declared action, application-wide: what `ctx.db.app('<action>')` reads and writes the application tables with. */
+    app<const Act extends A>(action: Act): AppCapability<Act>;
+    /** An absolute link to a procedure of this application: `ctx.url('api.mail.unsubscribe', { query: { t } })`. */
+    readonly url: AppUrl;
+}
+/** One message a job sends. The framework prefixes `idempotencyKey` before the transport sees it. */
+export interface AppMailMessage {
+    readonly to: string;
+    readonly subject: string;
+    readonly text: string;
+    readonly html?: string;
+    /** 1..200 visible ASCII characters, unique per message within this application environment. */
+    readonly idempotencyKey: string;
+    readonly replyTo?: string;
+    readonly fromName?: string;
+    /**
+     * A one-click unsubscribe (RFC 8058): the transport writes `List-Unsubscribe` and `List-Unsubscribe-Post`. `url` is
+     * an `https:` link, usually `ctx.url` of a public procedure that verifies a signed token.
+     */
+    readonly unsubscribe?: {
+        readonly url: string;
+    };
+    /**
+     * Files the message carries: references this attempt holds and may read, as `ctx.files.open` takes them. Only a
+     * `live` file is sent; the bytes of all of them together stay within the transport's `maxAttachmentBytes`, and a
+     * transport without it refuses the message. The idempotency key covers the attachments.
+     */
+    readonly attachments?: readonly FileRef[];
+}
+/** `ctx.mail` of a job that declares `mailer`. */
+export interface AppMail {
+    /**
+     * false where the installation has no mail transport (`FABRIKA_EMAIL_PROVIDER=none`, or a local one without any):
+     * every `send` fails `mail_not_configured`, outcome `not_sent`. An outbox then leaves its rows queued and spends no
+     * attempt; they leave on the first run after the operator adds a transport and the application is deployed again.
+     */
+    readonly available: boolean;
+    /** What the transport promises: whether a repeat under one key is deduplicated, sync or queued acceptance. */
+    readonly capabilities: EmailSenderCapabilities;
+    /**
+     * Hands one message to the transport. Rejects with `EmailDeliveryError`; its `outcome` says whether the message may
+     * have left. `signal` adds to the attempt's own `ctx.signal`, which always aborts the send.
+     */
+    send(message: AppMailMessage, signal?: AbortSignal): Promise<EmailDeliveryResult>;
+    /** `mayRetryDelivery` over this transport: true only for an `EmailDeliveryError` that is safe to send again. */
+    mayRetry(error: unknown): boolean;
+}
+export type JobHandler<A extends string, D extends string> = (args: {
+    readonly ctx: JobContext<A, D>;
+}) => void | Promise<void>;
+type JobsOf<C> = C extends {
+    readonly surface: {
+        readonly jobs: infer J;
+    };
+} ? J : never;
+/** `{ jobs: { <name>: handler } }` for a contract that declares jobs, and nothing for one that declares none. */
+export type JobHandlersOf<C> = [JobsOf<C>] extends [never] ? unknown : {
+    readonly jobs: {
+        readonly [K in keyof JobsOf<C>]: JobsOf<C>[K] extends CronJob<infer A> ? JobHandler<A, DimensionOf<C>> : never;
+    };
+};
+export {};

package/types/src/react/caller.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from 'react';
+import type { PageCaller } from '../client/caller';
+/** A scope value as the token names it: `{ type: 'org', value: 'acme' }`. */
+export interface CallerScope {
+    readonly type: string;
+    readonly value: string;
+}
+export interface Caller {
+    readonly label: string;
+    readonly email: string;
+    /**
+     * Whether the token grants `action`: without `scope`, app-wide or in any scope value; with `scope`, app-wide or in
+     * that value itself. A grant on a container is not seen from a value inside it (the page knows no chain): ask at
+     * the dimension the person holds the role in.
+     */
+    can(action: string, scope?: CallerScope): boolean;
+}
+/** The caller of a parsed document; exported for a page that reads the document itself. */
+export declare function callerOf(document: PageCaller): Caller;
+/** The page's caller, or `null` while the document loads and when it could not be read (a public SPA answers 401). */
+export declare function useCaller(): Caller | null;
+export interface CanProps {
+    readonly action: string;
+    readonly scope?: CallerScope;
+    /** Shown instead, also while the caller document loads; nothing by default. */
+    readonly fallback?: ReactNode;
+    readonly children?: ReactNode;
+}
+/** Renders its children when the caller's token grants `action` (see `Caller.can`). Never the access check. */
+export declare function Can({ action, scope, fallback, children }: CanProps): ReactNode;

package/types/src/react/errors.d.ts

@@ -0,0 +1,40 @@
+export type FabrikaError = {
+    readonly kind: 'unauthenticated';
+    readonly message: string;
+    /** Where the proxy sends the person to sign in; `null` when the answer carried none. */
+    readonly loginUrl: string | null;
+} | {
+    readonly kind: 'forbidden';
+    readonly message: string;
+} | {
+    readonly kind: 'conflict';
+    readonly message: string;
+} | {
+    readonly kind: 'validation';
+    readonly message: string;
+    /** The first message for each refused field, by its dotted input path (`title`, `lines.0.amount`). */
+    readonly fields: Readonly<Record<string, string>>;
+} | {
+    readonly kind: 'not-found';
+    readonly message: string;
+} | {
+    readonly kind: 'other';
+    readonly message: string;
+    /** The HTTP status; `0` when the request never got an answer. */
+    readonly status: number;
+};
+export type FabrikaErrorKind = FabrikaError['kind'];
+interface Issue {
+    readonly path: string;
+    readonly message: string;
+}
+/** The first message per path: a field shows one line. */
+export declare function fieldsOf(issues: readonly Issue[]): Readonly<Record<string, string>>;
+/**
+ * A refused call as the union, read structurally off the client's `RpcError` (`httpStatus`, `type`, `issues`,
+ * `loginUrl`); any other thrown value (a bug in the page) is `other` with status `0`.
+ */
+export declare function toFabrikaError(error: unknown): FabrikaError;
+/** The message for one field of a validation error, or `undefined`: what a form shows under that field. */
+export declare function fieldError(error: FabrikaError | null, path: string): string | undefined;
+export {};

package/types/src/react/hooks.d.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod/v4';
+import type { AttachmentProcedure, DownloadedFile, DownloadInput, FileProcedure } from '../client/contract';
+import type { Schema } from '../contract/define';
+import { type FabrikaError } from './errors';
+import type { InputArgument, InvalidateTarget, PagedProcedure, PageInput, TypedProcedure } from './types';
+/** Pass as the input to wait: the query sends nothing until its input is known. */
+export declare const skip: unique symbol;
+export type QueryState<T> = {
+    readonly fetching: boolean;
+    refetch(): Promise<void>;
+} & ({
+    readonly status: 'idle';
+    readonly data: undefined;
+    readonly error: null;
+} | {
+    readonly status: 'loading';
+    readonly data: undefined;
+    readonly error: null;
+} | {
+    readonly status: 'success';
+    readonly data: T;
+    readonly error: null;
+}
+/** `data` keeps the last answer when a refetch failed. */
+ | {
+    readonly status: 'error';
+    readonly data: T | undefined;
+    readonly error: FabrikaError;
+});
+export interface QueryOptions {
+    /**
+     * While a new input's answer loads, keep the previous input's answer as `success` data, with `fetching` true: an
+     * offset list (`{ items, total }`) whose `limit` or `offset` changes keeps its rows on screen.
+     */
+    readonly keepPrevious?: boolean;
+}
+/**
+ * The answer of a query, cached by procedure and input: every view of one call shares one request, and a mutation
+ * that invalidates it refetches it. Pass `skip` as the input to wait for a value the input needs.
+ */
+export declare function useQuery<O extends Schema>(procedure: TypedProcedure<Record<never, never> | undefined, O>, input?: typeof skip): QueryState<z.output<O>>;
+export declare function useQuery<I, O extends Schema>(procedure: TypedProcedure<I, O>, input: I | typeof skip, options?: QueryOptions): QueryState<z.output<O>>;
+export interface InfiniteQueryOptions {
+    /** How many pages the first load reads: `1` (the default) or every page (`'all'`, for a picker's options). */
+    readonly pages?: number | 'all';
+}
+export interface InfiniteQueryState<Item> {
+    readonly status: 'idle' | 'loading' | 'success' | 'error';
+    /** Every item of the loaded pages, in order. */
+    readonly items: readonly Item[];
+    readonly error: FabrikaError | null;
+    readonly hasMore: boolean;
+    readonly fetching: boolean;
+    readonly loadingMore: boolean;
+    loadMore(): Promise<void>;
+    refetch(): Promise<void>;
+    /** After a failed later page, asks for that page again; after a failed first load, loads again. */
+    retry(): Promise<void>;
+}
+/**
+ * A cursor list (`{ items, next }`, input `after`): the loaded pages as one list and `loadMore` for the next page. A
+ * refetch reads as many pages as are loaded again, from the first cursor.
+ */
+export declare function useInfiniteQuery<I extends {
+    readonly after?: string;
+} | undefined, Item>(procedure: PagedProcedure<I, Item>, input: PageInput<I> | typeof skip, options?: InfiniteQueryOptions): InfiniteQueryState<Item>;
+/** What `useDownload`'s `mutate` takes: the attachment procedure's input, or none. */
+export type DownloadArgument<I> = DownloadInput<I>[0];
+/**
+ * The download of an attachment procedure (`api.reports.export`) through the provider's client of its mount, so a test
+ * that hands the provider a client over the kit downloads over the kit. `mutate(input)` saves the file in a browser and
+ * answers it as `data`; a refusal is the state's `error`, as for `useMutation`. It refetches nothing.
+ */
+export declare function useDownload<I>(procedure: AttachmentProcedure<I> | FileProcedure<I>): MutationState<DownloadArgument<I>, DownloadedFile>;
+export type MutationResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: FabrikaError;
+};
+export interface MutationState<I, T> {
+    readonly status: 'idle' | 'pending' | 'success' | 'error';
+    readonly pending: boolean;
+    readonly data: T | undefined;
+    readonly error: FabrikaError | null;
+    /** Runs the call; never throws: a refusal is `{ ok: false, error }` and the state's `error`. */
+    mutate(input: I): Promise<MutationResult<T>>;
+    reset(): void;
+}
+export interface MutationOptions<T> {
+    /**
+     * What to refetch after a success or a `conflict`: procedures and groups of the client. Without it the procedure's own group
+     * (`api.deals` for `api.deals.create`); `[]` refetches nothing.
+     */
+    readonly invalidates?: readonly InvalidateTarget[];
+    readonly onSuccess?: (data: T) => void;
+}
+/**
+ * A mutation of the client: `mutate(input)` checks the input with the procedure's schema (a refused input is a
+ * `validation` error and sends nothing), calls it, and after a success refetches what `invalidates` names.
+ */
+export declare function useMutation<I, O extends Schema>(procedure: TypedProcedure<I, O>, options?: MutationOptions<z.output<O>>): MutationState<InputArgument<I>, z.output<O>>;
+/**
+ * A call that is no client procedure yet (a file upload until the client covers file collections), with the same
+ * state and error union as a mutation. It refetches only what `invalidates` names.
+ */
+export declare function useAction<I, T>(run: (input: I) => Promise<T>, options?: MutationOptions<T>): MutationState<I, T>;
+/** Refetches every shown query under the procedures or groups given, and forgets the cached rest. */
+export declare function useInvalidate(): (...targets: readonly InvalidateTarget[]) => Promise<void>;

package/types/src/react/index.d.ts

@@ -0,0 +1,5 @@
+export { type Caller, callerOf, type CallerScope, Can, type CanProps, useCaller } from './caller';
+export { type FabrikaError, type FabrikaErrorKind, fieldError, toFabrikaError } from './errors';
+export { type DownloadArgument, type InfiniteQueryOptions, type InfiniteQueryState, type MutationOptions, type MutationResult, type MutationState, type QueryOptions, type QueryState, skip, useAction, useDownload, useInfiniteQuery, useInvalidate, useMutation, useQuery, } from './hooks';
+export { FabrikaProvider, type FabrikaProviderProps } from './provider';
+export type { ClientGroup, ClientProcedure, InputArgument, InvalidateTarget, PageAnswer, PagedProcedure, PageInput, ProcedureInput, ProcedureResult, TypedProcedure, } from './types';

package/types/src/react/provider.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode } from 'react';
+import { type PageCaller } from '../client/caller';
+import { type ClientNode, type DownloadedFile } from '../client/contract';
+import { type RpcFetch } from '../client/transport';
+import { type FabrikaError } from './errors';
+import { QueryStore, type StoreTarget } from './store';
+export type CallerState = {
+    readonly status: 'loading';
+} | {
+    readonly status: 'ready';
+    readonly caller: PageCaller;
+} | {
+    readonly status: 'error';
+    readonly error: FabrikaError;
+};
+/** The caller document, read once per provider when a view first asks for it. */
+export declare class CallerSource {
+    #private;
+    private readonly url;
+    private readonly fetch;
+    state: CallerState;
+    constructor(url: string, fetch: RpcFetch);
+    subscribe(listener: () => void): () => void;
+}
+export interface Fabrika {
+    readonly store: QueryStore;
+    readonly caller: CallerSource;
+    /** The call of `procedure` on the provider's client of its mount. */
+    target(procedure: unknown, hook: string): ResolvedProcedure;
+    /** The download of attachment `procedure` on the provider's client of its mount. */
+    attachment(procedure: unknown, hook: string): (input: unknown) => Promise<DownloadedFile>;
+}
+export interface ResolvedProcedure extends StoreTarget {
+    readonly node: ClientNode;
+}
+export interface FabrikaProviderProps {
+    /** The clients of the mounts the page calls, as `createClient` made them; read at the first render. */
+    readonly clients: readonly object[];
+    /** The prefix of the SPA mount the page is served from: the caller document is `<spa>/__fabrika-me.json`. */
+    readonly spa?: string;
+    /**
+     * What the caller document, the browser config and the error reports are fetched with; the global `fetch` by default
+     * (a test passes the kit's).
+     */
+    readonly fetch?: RpcFetch;
+    /**
+     * Report the page's uncaught errors and unhandled rejections to Operations, through the DSN and release the mount
+     * serves at `<spa>/__fabrika-config.json`; `true` by default. Without a DSN nothing is reported.
+     */
+    readonly reportErrors?: boolean;
+    readonly children?: ReactNode;
+}
+export declare function FabrikaProvider({ clients, spa, fetch: fetchGiven, reportErrors, children }: FabrikaProviderProps): ReactNode;
+export declare function useFabrika(hook: string): Fabrika;
+/** The prefix a mutation invalidates by default: the group it lies in (`api.deals` for `api.deals.create`). */
+export declare function parentOf(node: ClientNode): string;
+/** The prefix of a procedure or a group, for `invalidate`. */
+export declare function prefixOf(target: unknown): string;

package/types/src/react/store.d.ts

@@ -0,0 +1,68 @@
+import type { FabrikaError } from './errors';
+/** A procedure as the store calls it: its id (`<mount>.<path>`) and the call of the provider's client. */
+export interface StoreTarget {
+    readonly id: string;
+    readonly run: (input: unknown) => Promise<unknown>;
+}
+export type QueryStatus = 'loading' | 'success' | 'error';
+export interface QuerySnapshot {
+    readonly status: QueryStatus;
+    readonly data: unknown;
+    readonly error: FabrikaError | null;
+    /** A request of this entry is in flight: the first load, a refetch or the next page. */
+    readonly fetching: boolean;
+}
+export interface PagesSnapshot {
+    readonly status: QueryStatus;
+    readonly items: readonly unknown[];
+    readonly next: string | null;
+    readonly error: FabrikaError | null;
+    readonly fetching: boolean;
+    readonly loadingMore: boolean;
+}
+/** One page of a cursor list, as every list procedure of the paved road answers it. */
+export interface Page {
+    readonly items: readonly unknown[];
+    readonly next: string | null;
+}
+type Listener = () => void;
+/** JSON with sorted keys, so two inputs that are the same value are the same key. */
+export declare function stableKey(value: unknown): string;
+/** `<mount>.<path>` lies under `prefix` when it is the prefix itself or one of its descendants. */
+export declare function under(id: string, prefix: string): boolean;
+declare abstract class Entry<S> {
+    #private;
+    readonly target: StoreTarget;
+    readonly input: unknown;
+    snapshot: S;
+    protected sequence: number;
+    constructor(target: StoreTarget, input: unknown, initial: S);
+    get watched(): boolean;
+    subscribe(listener: Listener): () => void;
+    protected publish(snapshot: S): void;
+    abstract load(): Promise<void>;
+}
+export declare class QueryEntry extends Entry<QuerySnapshot> {
+    private readonly mapError;
+    constructor(target: StoreTarget, input: unknown, mapError: (error: unknown) => FabrikaError);
+    load(): Promise<void>;
+}
+export declare class PagesEntry extends Entry<PagesSnapshot> {
+    #private;
+    private readonly mapError;
+    constructor(target: StoreTarget, input: unknown, pages: number, mapError: (error: unknown) => FabrikaError);
+    /** Loads the first `#pages` pages again, from the first cursor. */
+    load(): Promise<void>;
+    /** Appends the next page; nothing while a request is in flight or when the list has no more. */
+    loadMore(): Promise<void>;
+}
+export declare class QueryStore {
+    #private;
+    private readonly mapError;
+    constructor(mapError: (error: unknown) => FabrikaError);
+    query(target: StoreTarget, input: unknown): QueryEntry;
+    pages(target: StoreTarget, input: unknown, pages: number): PagesEntry;
+    /** Refetches every entry under one of `prefixes` that a view shows, and forgets the rest, so their next view loads. */
+    invalidate(prefixes: readonly string[]): Promise<void>;
+}
+export {};

package/types/src/react/testing.d.ts

@@ -0,0 +1,28 @@
+export interface InstalledDom {
+    /** Closes the window and removes its globals; call it from the test file's `afterAll`. */
+    uninstall(): Promise<void>;
+}
+export interface DomOptions {
+    /** The page's address; `http://app.test/` by default. A router needs a real origin. */
+    readonly url?: string;
+}
+/**
+ * Installs happy-dom's window as the globals, keeping Bun's fetch, abort, URL, blob, file and form classes, with
+ * navigation off: a download's link click leaves the page where it is, so a later test of the file still has it. Call
+ * it in a module the test file imports first: React reads `window` when it loads.
+ */
+export declare function installDom(options?: DomOptions): InstalledDom;
+type Control = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+/** The one input, textarea or select whose accessible name is `label`; throws when there is none or more than one. */
+export declare function controlByLabel(label: string, within?: ParentNode): Control;
+/**
+ * Types `value` into the control labelled `label`, as React reads a person typing: it focuses the control, sets the
+ * value past React's tracking, and sends `input`, `change` and `keyup`. A select takes the option's value.
+ */
+export declare function type(label: string, value: string, within?: ParentNode): Promise<void>;
+/** Waits, letting React render, until the text of `within` holds `text`; throws after `timeoutMs` (2 s by default). */
+export declare function waitForText(text: string, options?: {
+    readonly within?: Element;
+    readonly timeoutMs?: number;
+}): Promise<void>;
+export {};

package/types/src/react/types.d.ts

@@ -0,0 +1,33 @@
+import type { z } from 'zod/v4';
+import type { Schema } from '../contract/define';
+/** A query or mutation of a client that `createClient` built. */
+export type ClientProcedure = ((input: never) => Promise<unknown>) & {
+    readonly output: Schema;
+};
+/** A group of a client tree (`api.deals`), or the client itself: every procedure under it. */
+export interface ClientGroup {
+    readonly [name: string]: unknown;
+}
+/** What `invalidate` takes: one procedure, or a group for every procedure under it. */
+export type InvalidateTarget = ClientProcedure | ClientGroup;
+/** The input as the caller writes it; `undefined` admitted for a procedure that takes none. */
+export type ProcedureInput<F extends ClientProcedure> = F extends (input: infer I) => Promise<unknown> ? I : never;
+/** A procedure by its input `I` and output schema `O`: what the hooks take, so both are inferred from the call. */
+export type TypedProcedure<I, O extends Schema> = ((input: I) => Promise<unknown>) & {
+    readonly output: O;
+};
+/** An input argument that may be left out when the procedure takes no input. */
+export type InputArgument<I> = undefined extends I ? I | void : I;
+/** The answer, as the procedure's output schema parses it. */
+export type ProcedureResult<F extends ClientProcedure> = z.output<F['output']>;
+/** The answer of a cursor list: `{ items, next }`. */
+export interface PageAnswer<Item> {
+    readonly items: readonly Item[];
+    readonly next: string | null;
+}
+/** A procedure that pages: input `after`, answer `{ items, next }`. */
+export type PagedProcedure<I, Item> = ((input: I) => Promise<unknown>) & {
+    readonly output: z.core.$ZodType<PageAnswer<Item>>;
+};
+/** The input of a paged procedure without its cursor: the hook sends `after` itself. */
+export type PageInput<I> = undefined extends I ? Omit<NonNullable<I>, 'after'> | void : Omit<I, 'after'>;