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

package/types/src/client/contract.d.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod/v4';
+import { type AttachmentBrand } from '../contract/attachment';
+import { type ProcedureType } from '../contract/declaration';
+import type { AnyContract, InputSchema, Procedure, Schema } from '../contract/define';
+import { type ClientInput, type FileBrand } from '../contract/file';
+import { type BounceOption, type RpcFetch } from './transport';
+type SurfaceOf<C> = C extends {
+    readonly surface: infer S;
+} ? S : never;
+/** The mounts a client calls: RPC mounts and link mounts. */
+export type ClientMount<C> = {
+    [M in keyof SurfaceOf<C>]: SurfaceOf<C>[M] extends {
+        readonly kind: 'rpc' | 'link';
+    } ? M : never;
+}[keyof SurfaceOf<C>] & string;
+/**
+ * One procedure: its input as the caller writes it (defaults optional), its output as parsed, and the output schema
+ * it parses with (`@fabrika/app/react` reads a cached answer back through it).
+ */
+export type ProcedureCall<I, O extends Schema> = ([I] extends [InputSchema] ? (input: ClientInput<z.input<I>>) => Promise<z.output<O>> : (input?: Record<never, never>) => Promise<z.output<O>>) & {
+    readonly output: O;
+};
+export type ClientTree<T> = {
+    readonly [K in keyof T]: T[K] extends Procedure<'query' | 'mutation', infer I, infer O, unknown> ? O extends AttachmentBrand ? AttachmentProcedure<I> : O extends FileBrand<string> ? FileProcedure<I> : ProcedureCall<I, O> : ClientTree<T[K]>;
+};
+type MountOf<C, M> = SurfaceOf<C>[M & keyof SurfaceOf<C>];
+/** One function per procedure, and an `AttachmentProcedure` or `FileProcedure` per procedure that answers a file. */
+export type ContractClient<C, M> = MountOf<C, M> extends {
+    readonly procedures: infer T;
+} ? ClientTree<T> : never;
+/** The answer of a client procedure: `ResultOf<typeof api.tasks.get>`; a procedure that answers a file, a `DownloadedFile`. */
+export type ResultOf<F> = F extends (...args: never[]) => Promise<infer R> ? R : F extends AttachmentProcedure<unknown> | FileProcedure<unknown> ? DownloadedFile : never;
+/** The input of a client procedure as the caller writes it: `InputOf<typeof api.tasks.create>`. */
+export type InputOf<F> = F extends (...args: infer A) => Promise<unknown> ? A[0] : F extends AttachmentProcedure<infer I> | FileProcedure<infer I> ? DownloadInput<I>[0] : never;
+export interface ClientOptions {
+    /** The application's origin; procedure paths are joined to it. Defaults to the page's own origin. */
+    readonly baseUrl?: string;
+    /** Override `fetch` (tests, a script). Defaults to the global `fetch`. */
+    readonly fetch?: RpcFetch;
+    /**
+     * A `px_` key, sent as `Authorization: Bearer`. A request with a key carries no cookie. In a browser the key goes
+     * only to the page's own origin.
+     */
+    readonly key?: string;
+    /** On a 401 that carries a login URL, send the browser to sign in instead of throwing. */
+    readonly bounceOnAuth?: BounceOption;
+}
+/** A link mount's caller is the holder of its share key, which every request presents. */
+export interface LinkClientOptions extends ClientOptions {
+    readonly key: string;
+}
+type OptionsFor<C, M> = SurfaceOf<C>[M & keyof SurfaceOf<C>] extends {
+    readonly kind: 'link';
+} ? [options: LinkClientOptions] : [options?: ClientOptions];
+/**
+ * What a value of a client tree is, kept beside it so the value stays a plain function or record: a procedure's
+ * `<mount>.<path>`, its type and input schema, or a group's prefix. `@fabrika/app/react` keys its cache by it.
+ */
+export interface ClientNode {
+    readonly mount: string;
+    /** The dotted path below the mount; `''` for the client itself. */
+    readonly path: string;
+    readonly procedure: {
+        readonly type: ProcedureType;
+        readonly input: Schema | null;
+    } | null;
+}
+/** The node a value of a client tree is, or `null` for any other value. */
+export declare function clientNodeOf(value: unknown): ClientNode | null;
+/**
+ * The URL a page's ALTCHA widget fetches the challenge of `procedure` from (`GET /__fabrika/challenge/<action>`), on the
+ * client's `baseUrl`. Throws for a procedure whose `admission.challenge` is not `provider: 'altcha'`.
+ */
+export declare function challengeUrl(procedure: object): string;
+declare const attachmentInput: unique symbol;
+/**
+ * An attachment procedure of a client: not a function, because its answer is a file. `download(api.<procedure>,
+ * input)` fetches and saves it.
+ */
+export interface AttachmentProcedure<I> {
+    /** `<mount>.<path>` */
+    readonly id: string;
+    /** The file name the contract declares. */
+    readonly filename: string;
+    /** Carries the input schema for `download`; never present at runtime. */
+    readonly [attachmentInput]?: I;
+}
+/**
+ * A procedure whose output is a file (`file('<kind>')`): not a function, because its answer is a file.
+ * `download(api.<procedure>, input)` fetches it with the caller's credential, and a GET one's `url(input)` is where a
+ * same-origin page links to it (`<img src>`, `<a download>`).
+ */
+export interface FileProcedure<I> {
+    /** `<mount>.<path>` */
+    readonly id: string;
+    /**
+     * The URL of the file a GET procedure answers, for a page signed in on the same origin. A client with a key has none:
+     * a key never goes into a URL, so it downloads instead.
+     */
+    url(...input: DownloadInput<I>): string;
+    /** Carries the input schema for `download`; never present at runtime. */
+    readonly [attachmentInput]?: I;
+}
+/** A downloaded file: a `File`, and the page's offer to save it. */
+export declare class DownloadedFile extends File {
+    /** The file as a `Blob`. */
+    blob(): Blob;
+    /** Offers the file as a download under its name; nothing where there is no page. */
+    save(): void;
+}
+/** The mount and path of an attachment procedure of a client, or `null` for any other value. */
+export declare function attachmentAt(value: unknown): {
+    readonly mount: string;
+    readonly path: string;
+} | null;
+/** The input `download` takes: the procedure's, or none. */
+export type DownloadInput<I> = [I] extends [InputSchema] ? [input: z.input<I>] : [input?: Record<never, never>];
+/**
+ * Calls a procedure that answers a file (an attachment, or a `file('<kind>')` output) with the caller's credential, and
+ * answers the file: `blob()`, `stream()`, `save()`. An attachment is also offered as a download in a browser, under the
+ * declared name. A refusal is an `RpcError`.
+ */
+export declare function download<I>(procedure: AttachmentProcedure<I> | FileProcedure<I>, ...input: DownloadInput<I>): Promise<DownloadedFile>;
+/** `download` of any file procedure of a client, its input unchecked: the provider's `useDownload` runs it. */
+export declare function downloadFile(procedure: object, input: unknown): Promise<DownloadedFile>;
+/**
+ * The client of mount `mount` of `contract`: one function per declared procedure. A link mount's client sends its
+ * share key as a bearer, so `options.key` is required there.
+ */
+export declare function createClient<const C extends AnyContract, const M extends ClientMount<C>>(contract: C, mount: M, ...rest: OptionsFor<C, M>): ContractClient<C, M>;
+export {};

package/types/src/client/error-reporting.d.ts

@@ -0,0 +1,66 @@
+import type { RpcFetch } from './transport';
+/** One stack frame in Sentry's shape, the file a script URL. */
+export interface BrowserFrame {
+    readonly filename: string;
+    readonly function?: string;
+    readonly lineno: number;
+    readonly colno: number;
+    /** A frame of a script of the page's own origin. */
+    readonly in_app: boolean;
+}
+/** Where the page reports, read from its browser config. */
+export interface ReportingTarget {
+    /** The ingest's envelope endpoint, authenticated by the DSN's public key in its query, as the Sentry SDK sends it. */
+    readonly envelopeUrl: string;
+    readonly release: string | null;
+    readonly environment: string | null;
+}
+/** What the reporter listens on and reads the page's address from: `window` in a page. */
+export interface ReportingPage {
+    addEventListener(type: 'error' | 'unhandledrejection', listener: (event: Event) => void): void;
+    removeEventListener(type: 'error' | 'unhandledrejection', listener: (event: Event) => void): void;
+    readonly location: {
+        readonly origin: string;
+        readonly pathname: string;
+    };
+}
+/** A page that keeps failing stops reporting here; Operations rate-limits the whole source, not one page. */
+export declare const MAX_REPORTS_PER_PAGE = 20;
+/**
+ * The envelope endpoint of an ingest DSN `https://<key>@<host>/<project>`, or `null` for any other value. The server's
+ * reporter parses the same DSN (`jobs/report.ts`); it is server code, so a page does not import it.
+ */
+export declare function envelopeUrlOf(dsn: string): string | null;
+/** The reporting target the browser config names, or `null` when it names no usable DSN. */
+export declare function reportingTargetOf(config: unknown): ReportingTarget | null;
+/**
+ * The frames of a V8, SpiderMonkey or JavaScriptCore `stack`, oldest call first as Sentry orders them, the
+ * `MAX_FRAMES` nearest the throw kept. A frame whose file is no URL (an `eval`, a native function) is left out.
+ */
+export declare function parseBrowserStack(stack: string, origin: string): BrowserFrame[];
+type Mechanism = 'onerror' | 'onunhandledrejection';
+interface ReportedException {
+    readonly type: string;
+    readonly value: string;
+    readonly mechanism: {
+        readonly type: Mechanism;
+        readonly handled: false;
+    };
+    readonly stacktrace?: {
+        readonly frames: readonly BrowserFrame[];
+    };
+}
+/** The envelope of one error event. The page's address goes without its query and fragment, which may carry a key. */
+export declare function browserEnvelope(exception: ReportedException, target: ReportingTarget, page: ReportingPage['location'], now: Date): string;
+/**
+ * Listen for the page's uncaught errors and unhandled rejections and send each to `target`; answers the uninstall.
+ * An error equal to the one just sent is not sent again, and the page sends at most `MAX_REPORTS_PER_PAGE`. A failed
+ * delivery is dropped: reporting never throws into the page.
+ */
+export declare function installErrorReporting(page: ReportingPage, target: ReportingTarget, send: RpcFetch): () => void;
+/**
+ * Read the browser config at `configUrl` and install reporting when it names a DSN; answers the uninstall, or `null`
+ * when nothing was installed. A missing, refused or unreadable config (local development, a test) installs nothing.
+ */
+export declare function startErrorReporting(configUrl: string, fetch: RpcFetch, page: ReportingPage): Promise<(() => void) | null>;
+export {};

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

@@ -0,0 +1,4 @@
+export { type PageCaller, parsePageCaller } from './caller';
+export { type AttachmentProcedure, challengeUrl, type ClientMount, type ClientOptions, type ClientTree, type ContractClient, createClient, download, DownloadedFile, type DownloadInput, type FileProcedure, type InputOf, type LinkClientOptions, type ProcedureCall, type ResultOf, } from './contract';
+export { shareKey } from './share';
+export { type BounceOption, RpcError, type RpcFetch } from './transport';

package/types/src/client/rpc.d.ts

@@ -0,0 +1,14 @@
+import type { InferRpcClient } from '../rpc/contract.js';
+import { type BounceOption, type RpcFetch } from './transport.js';
+export interface RpcClientOptions {
+    /** Endpoint the RPC proxy POSTs to (e.g. `/rpc`). */
+    readonly baseUrl: string;
+    /**
+     * Auto-redirect to SSO on a sign-in 401 (`type: 'auth'` + `loginUrl`) instead of throwing.
+     * `true` uses sane defaults; pass `{ sessionKey, windowMs }` to tune the re-entry guard.
+     */
+    readonly bounceOnAuth?: BounceOption;
+    /** Override `fetch` (tests / non-browser). Defaults to the global `fetch`. */
+    readonly fetch?: RpcFetch;
+}
+export declare function createRpcClient<TApi>(opts: RpcClientOptions): InferRpcClient<TApi>;

package/types/src/client/share.d.ts

@@ -0,0 +1,2 @@
+/** The key the share link carried, or `null` outside a share SPA or when the link had none. */
+export declare function shareKey(): string | null;

package/types/src/client/transport.d.ts

@@ -0,0 +1,42 @@
+export declare class RpcError extends Error {
+    readonly type: string;
+    readonly issues?: unknown;
+    readonly loginUrl?: string;
+    readonly httpStatus?: number;
+    constructor(payload: {
+        type: string;
+        message: string;
+        issues?: unknown;
+        loginUrl?: string;
+        httpStatus?: number;
+    });
+}
+/** Minimal Fetch API surface required by the RPC client. */
+export type RpcFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Auto-redirect to SSO on a sign-in 401 (`type: 'auth'` + `loginUrl`) instead of throwing.
+ * `true` uses sane defaults; pass `{ sessionKey, windowMs }` to tune the re-entry guard.
+ */
+export type BounceOption = boolean | {
+    sessionKey?: string;
+    windowMs?: number;
+};
+export interface BounceConfig {
+    readonly sessionKey: string;
+    readonly windowMs: number;
+}
+export declare function resolveBounce(scope: string, opt: BounceOption | undefined): BounceConfig | null;
+/**
+ * Sends one request and answers the envelope's `result`; every failure is an `RpcError`, and so is every answer that is
+ * not 2xx, whatever its body holds. `init` builds the request inside the guard, so an input that does not serialize
+ * rejects like a failed request instead of throwing.
+ */
+export declare function exchange(doFetch: RpcFetch, url: string, init: () => RequestInit, bounce: BounceConfig | null): Promise<unknown>;
+/**
+ * Sends one request whose success is a file and answers its bytes and its `Content-Disposition`; a failure is read from
+ * its `{ error }` envelope.
+ */
+export declare function exchangeFile(doFetch: RpcFetch, url: string, init: () => RequestInit, bounce: BounceConfig | null): Promise<{
+    readonly body: Blob;
+    readonly disposition: string | null;
+}>;

package/types/src/cloudflare.d.ts

@@ -0,0 +1,49 @@
+import type { FetchService, RequestExecutionContext } from './fetch.js';
+import { type CrashEvents } from './implement/crashes.js';
+import type { ContractImplementation } from './implement/implement.js';
+export { markProductionProcess } from '@fabrika/db/production';
+/** Minimal structural view of a Workers `ExecutionContext`. */
+export interface CloudflareExecutionContext extends RequestExecutionContext {
+    passThroughOnException(): void;
+}
+/** Minimal structural view of a Workers cron `ScheduledController`. */
+export interface CloudflareScheduledController {
+    readonly scheduledTime: number;
+    readonly cron: string;
+    noRetry(): void;
+}
+/** Minimal structural view of a Workers queue `MessageBatch`. */
+export interface CloudflareMessageBatch {
+    readonly queue: string;
+    readonly messages: ReadonlyArray<unknown>;
+}
+export interface CloudflareWorkerOptions<Env> {
+    scheduled?: (controller: CloudflareScheduledController, env: Env, exec: CloudflareExecutionContext) => Promise<void>;
+    queue?: (batch: CloudflareMessageBatch, env: Env, exec: CloudflareExecutionContext) => Promise<void>;
+}
+export interface CloudflareWorker<Env> {
+    fetch(request: Request, env: Env, exec: CloudflareExecutionContext): Promise<Response>;
+    scheduled?(controller: CloudflareScheduledController, env: Env, exec: CloudflareExecutionContext): Promise<void>;
+    queue?(batch: CloudflareMessageBatch, env: Env, exec: CloudflareExecutionContext): Promise<void>;
+}
+/** Adapt a runtime-neutral `{ fetch }` service to a Workers module export. */
+export declare function createCloudflareWorker<Env>(app: FetchService<Env>, options?: CloudflareWorkerOptions<Env>): CloudflareWorker<Env>;
+/** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
+export type ImplementationLoader = () => Promise<{
+    readonly default: ContractImplementation;
+}>;
+export interface ContractWorkerOptions {
+    /** Where the isolate hears of an unhandled rejection; the global `unhandledrejection` event by default. */
+    readonly rejections?: CrashEvents;
+    /** What posts a report to Operations' ingest; `fetch` by default. */
+    readonly operationsFetch?: (request: Request) => Promise<Response>;
+}
+/**
+ * A Worker module for a contract application, called only by the generated entrypoint. A Worker receives its
+ * environment with the first request, so the framework captures it, scrubs the process environment and only then
+ * imports the application and boots it, once per environment object. With an Operations DSN, the first failed boot
+ * of an isolate is reported, and once one booted, every unhandled rejection of the isolate is, within a budget.
+ */
+export declare function createContractWorker(load: ImplementationLoader, options?: ContractWorkerOptions): {
+    fetch(request: Request, env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<Response>;
+};

package/types/src/contract/artifact-schema.d.ts

@@ -0,0 +1,8 @@
+import { type ContractArtifact, type OutputShape, type SchemaShape } from '@fabrika/auth-core';
+import { z } from 'zod/v4';
+/** A `SchemaShape` read back as JSON. */
+export declare const schemaShapeSchema: z.ZodType<SchemaShape>;
+export declare const outputShapeSchema: z.ZodType<OutputShape>;
+export declare const contractArtifactSchema: z.ZodType<ContractArtifact>;
+/** Parses JSON that should be a contract artifact; throws a `ZodError` naming every mismatch. */
+export declare function parseContractArtifact(value: unknown): ContractArtifact;

package/types/src/contract/attachment.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod/v4';
+import { type AttachmentDeclaration } from './declaration';
+import type { InputSchema, NotLoose, Schema } from './define';
+declare const ATTACHMENT: unique symbol;
+/** What `attachment()` adds to the rows' array schema: its declaration and its row schema. */
+export interface AttachmentMark {
+    readonly declaration: AttachmentDeclaration;
+    readonly row: InputSchema;
+}
+/** An attachment output of rows `R`: the handler returns `z.input<R>[]`, and the caller receives a file. */
+export type Attachment<R extends InputSchema> = z.ZodArray<R> & AttachmentBrand;
+/** What tells an attachment output from a JSON one in the types. */
+export interface AttachmentBrand {
+    readonly [ATTACHMENT]: AttachmentMark;
+}
+export interface AttachmentOptions<R> {
+    /**
+     * `'csv'`: RFC 4180, UTF-8 with a byte order mark, a header line of the row's field names. `'xlsx'`: one sheet, the
+     * header row of the field names, then a number, boolean or text cell per value, and a date cell for a string whose
+     * schema is `z.iso.date()` or `z.iso.datetime()`.
+     */
+    readonly format: 'csv' | 'xlsx';
+    /** The file name the browser saves: `[A-Za-z0-9._-]`, ending in `.csv` or `.xlsx`, as the format. */
+    readonly filename: string;
+    /** The row schema: a strict object of scalar fields, in the file's column order. */
+    readonly row: R;
+    /** The encoded file's limit; an encoding over it fails the invocation and sends no body. */
+    readonly maxBytes: number;
+    /** At most this many rows; 10 000 when left out. */
+    readonly maxRows?: number;
+}
+/**
+ * The output of a procedure that answers a file of `row`s. Like every builder it validates nothing: `compileContract`
+ * and the checker refuse a format, a name, a limit or a column outside what an attachment may be.
+ */
+export declare function attachment<R extends InputSchema>(options: AttachmentOptions<R & NotLoose<R>>): Attachment<R>;
+/** The rows' array schema marked with `declaration`; the static reader builds the evaluated value with it. */
+export declare function attachmentOutput<R extends InputSchema>(row: R, declaration: AttachmentDeclaration): Attachment<R>;
+/** The mark of an `attachment()` output, or `null` for any other schema. */
+export declare function attachmentOf(schema: Schema): AttachmentMark | null;
+export {};

package/types/src/contract/build.d.ts

@@ -0,0 +1,12 @@
+import { type ContractArtifact, type FileShape, type SchemaShape, type TablePolicyArtifact } from '@fabrika/auth-core';
+import { type ContractDeclaration } from './declaration';
+/** Turnstile's `action`: the procedure's endpoint id, which the verification expects back. */
+/** Validates a described contract against its table policies and normalizes it; throws `ContractError` with every problem. */
+export declare function buildArtifact(contract: ContractDeclaration<SchemaShape>, tables: Readonly<Record<string, TablePolicyArtifact>>): ContractArtifact;
+/** Whether a schema holds a file anywhere. */
+export declare function containsFile(shape: SchemaShape): boolean;
+/** The file fields of an input, by name: the parts a multipart body carries beside its JSON. */
+export declare function fileFieldsOf(input: SchemaShape | null): ReadonlyMap<string, FileShape & {
+    readonly many: boolean;
+    readonly max: number;
+}>;

package/types/src/contract/compile.d.ts

@@ -0,0 +1,11 @@
+import type { ContractArtifact, SchemaShape, TablePolicyArtifact } from '@fabrika/auth-core';
+import { type Tables } from '@fabrika/db/tables';
+import { type ContractDeclaration } from './declaration';
+import type { AnyContract } from './define';
+/**
+ * The normalized artifact of a contract and its table policies: what `defineTables` returned (`src/db/tables.ts`),
+ * or the artifact form of each policy.
+ */
+export declare function compileContract<DB, P>(contract: AnyContract, tables: Tables<DB, P> | Readonly<Record<string, TablePolicyArtifact>>): ContractArtifact;
+/** The contract with its schemas read as shapes; throws `ContractError` for a schema outside the subset. */
+export declare function describeContract(contract: AnyContract): ContractDeclaration<SchemaShape>;

package/types/src/contract/connect.d.ts

@@ -0,0 +1,51 @@
+import { type ContractArtifact, type ExportDescription } from '@fabrika/auth-core';
+import { z } from 'zod/v4';
+import type { InputSchema, Schema } from './define';
+/** One vendored procedure: the zod schemas `fabrika connect add` generated from the owner's description. */
+export interface SnapshotProcedure {
+    readonly input: InputSchema | null;
+    readonly output: Schema;
+}
+/**
+ * The vendored description of another application's export, as `fabrika connect add` writes it to
+ * `fabrika/connect/<app>.<export>.v<version>.ts`. The consumer passes it to `implement({ connect })` and imports its
+ * digest into the contract.
+ */
+export interface ConnectSnapshot {
+    readonly app: string;
+    readonly export: string;
+    readonly version: number;
+    readonly audience: string;
+    readonly digest: string;
+    /** By the procedure's dotted path in the export. */
+    readonly procedures: {
+        readonly [path: string]: SnapshotProcedure;
+    };
+}
+/** The description the owner serves for `name`, or `null` when the artifact declares no such export. */
+export declare function exportDescription(artifact: ContractArtifact, name: string): ExportDescription | null;
+/**
+ * The description a snapshot's schemas describe now, with the digest of that. A snapshot whose recomputed digest is
+ * not its own `digest` was edited after `fabrika connect add` wrote it. Throws `ContractError` for a schema outside
+ * the contract subset.
+ */
+export declare function describeSnapshot(snapshot: ConnectSnapshot): ExportDescription;
+/** The parser of a description another application served; the digest is checked by `parseExportDescription`. */
+export declare const exportDescriptionSchema: z.ZodType<ExportDescription>;
+/** A served description, parsed, whose digest is the digest of what it describes; throws `ContractError` otherwise. */
+export declare function parseExportDescription(value: unknown): ExportDescription;
+/**
+ * What an owner's change of one export version breaks for a consumer that imports `procedures` of it: a removed
+ * procedure, an input that accepts less, a changed output, or a changed audience. An output may not even gain a field,
+ * because the consumer parses every answer against its vendored schema, whose objects are strict; an input object may
+ * gain optional fields. Every other change is a new version. Empty when the change is compatible.
+ */
+export declare function incompatibleChanges(before: ExportDescription, after: ExportDescription, procedures: readonly string[]): string[];
+/**
+ * What `after` breaks for the callers of each mount `before` promises `compatibility: 'backward'`: a procedure it
+ * removes (including its generated challenge endpoint), an input or a query that accepts less, another output, another
+ * HTTP shape (method, path, body codec), file answer or access (its kind, callers, requirement and cross-origin form), or a
+ * mount moved. The promise binds the
+ * publication that drops it too, so a breaking change is a new mount beside the old one. Empty when compatible.
+ */
+export declare function incompatibleMountChanges(before: ContractArtifact, after: ContractArtifact): string[];