@fabrika/app 0.8.2 → 0.9.0-cloudflare.2

package/src/testing/kit.ts

@@ -16,13 +16,16 @@ import {
 	FABRIKA_IAM_ISSUER,
 	FABRIKA_TOKEN_KEYS,
 	type IamMembershipRpc,
+	type IamTerminalRpc,
 	isNormalizedMailbox,
 	type Jwks,
 	MAX_ACCESS_TOKEN_BYTES,
+	MAX_APPLICATION_TOKEN_BYTES,
 	normalizeEmailIdentity,
 	type PermissionEntry,
 	PROXY_TOKEN_HEADER,
 	SESSION_COOKIE,
+	type TerminalFailure,
 	TOKEN_ALG,
 	UNTRUSTED_FORWARD_HEADERS,
 	workloadKeyVariable,
@@ -78,6 +81,14 @@ import {
 import { endpointProxy } from './proxy'
 
 export const TEST_ISSUER = 'https://iam.test'
+
+/** The kit's IAM without a terminal: no identification is open, so every one is `not_found`. */
+const noIdentification = (): Promise<TerminalFailure> => Promise.resolve({ ok: false, reason: 'not_found' })
+const NO_IDENTIFICATIONS: IamTerminalRpc = Object.freeze({
+	inspectIdentification: noIdentification,
+	assertIdentity: noIdentification,
+	cancelIdentification: noIdentification,
+})
 export const TEST_ENVIRONMENT = 'test'
 const KEY_ID = 'test-key'
 const TOKEN_TTL_SECONDS = 300
@@ -112,6 +123,11 @@ export interface TestKitOptions {
 	 * kit's proxy obtains each delegation grant from it. Without it the kit's IAM answers them under IAM's rules.
 	 */
 	readonly membership?: IamMembershipRpc
+	/**
+	 * IAM's identifications at a terminal (ADR-0067), for a contract that declares one. Without it the kit's IAM knows no
+	 * open identification: `inspect` answers null and `assert` `not_found`.
+	 */
+	readonly terminals?: IamTerminalRpc
 	/**
 	 * Each import's owner, by the import's name: its origin and edge key, which the platform writes as the import's
 	 * framework variables, and how a request reaches it — usually the owner kit's `fetch`.
@@ -428,6 +444,7 @@ export function bootTestKit<C extends AnyContract>(
 		...dev,
 		...(options.revealHandlerErrors === undefined ? {} : { revealHandlerErrors: options.revealHandlerErrors }),
 		membership,
+		terminals: options.terminals ?? (artifact.terminal === undefined ? undefined : NO_IDENTIFICATIONS),
 		connectBindings,
 		workloadTokens,
 		mailStandIn: options.mail === 'none' ? 'none' : mail,
@@ -523,7 +540,7 @@ export function bootTestKit<C extends AnyContract>(
 
 	const scope = <D extends DimensionOf<C>>(dimension: D, value: string): TestScope<D> => Object.freeze({ type: dimension, value })
 
-	/** The caller's token, or why IAM signs none: a disabled principal, or a token above `MAX_ACCESS_TOKEN_BYTES`. */
+	/** The caller's token, or why IAM signs none: a disabled principal, or a token above IAM's bound for it. */
 	async function mint(caller: TestCaller): Promise<{ readonly ok: true; readonly token: string; readonly expiresAt: number } | MintRefusal> {
 		if (caller.disabled) return { ok: false, reason: 'disabled' }
 		const now = Math.floor(Date.now() / 1000)
@@ -542,7 +559,8 @@ export function bootTestKit<C extends AnyContract>(
 		})
 		const { privateKey } = await signing
 		const token = await new SignJWT({ ...claims }).setProtectedHeader({ alg: TOKEN_ALG, kid: KEY_ID }).sign(privateKey)
-		if (token.length > MAX_ACCESS_TOKEN_BYTES) return { ok: false, reason: 'token_too_large' }
+		// IAM bounds a workload's own token as any installation token, and a token the proxy injects at the application's.
+		if (token.length > (caller.app === null ? MAX_APPLICATION_TOKEN_BYTES : MAX_ACCESS_TOKEN_BYTES)) return { ok: false, reason: 'token_too_large' }
 		byToken.set(token, { caller, expiresAt: claims.exp })
 		return { ok: true, token, expiresAt: claims.exp }
 	}

package/src/testing/proxy.ts

@@ -19,7 +19,7 @@ import {
 	type TokenCache,
 } from '@fabrika/proxy-core'
 import { applyCrossOriginHeaders, crossOriginHeaders } from '@fabrika/proxy-core/headers'
-import { contractProxyTable } from '@fabrika/proxy-core/manifest'
+import { contractProxyEntry, contractProxyTable } from '@fabrika/proxy-core/manifest'
 
 /** What the proxy did with a request: answered it itself, or forwarded it with what only the proxy may set. */
 export type ProxyOutcome =
@@ -66,14 +66,14 @@ const ASSERTED_HEADERS = [PROXY_TOKEN_HEADER, REQUEST_ID_HEADER, ENDPOINT_HEADER
 export function endpointProxy(options: EndpointProxyOptions): TestProxy {
 	const verify = createVerifyService({
 		manifest: {
-			apps: [{
+			apps: [contractProxyEntry({
 				id: options.appId,
 				hosts: [options.host],
 				upstream: 'app',
 				scheme: 'https',
-				...contractProxyTable(options.artifact),
-				...(options.crossOrigins === undefined || options.crossOrigins.length === 0 ? {} : { crossOrigins: [...options.crossOrigins] }),
-			}],
+				table: contractProxyTable(options.artifact),
+				...(options.crossOrigins === undefined ? {} : { crossOrigins: options.crossOrigins }),
+			})],
 		},
 		iam: options.iam,
 		issuer: options.issuer,

package/types/src/agent-skill.d.ts

@@ -0,0 +1,29 @@
+export declare const APP_AGENT_SKILL_NAME = "fabrika-app";
+export interface AppAgentSkillReference {
+    /** The file's path in the skill directory, `references/<topic>.md`: the path `SKILL.md` names it by. */
+    readonly path: string;
+    /** The topic `get_app_rules` answers it under: its file name without `.md`. */
+    readonly topic: string;
+    readonly text: string;
+}
+export interface AppAgentSkill {
+    /** The `version` of the frontmatter: the version of the `@fabrika/app` that ships it. */
+    readonly version: string;
+    /** The whole `SKILL.md`, frontmatter included: what a skill directory holds. */
+    readonly text: string;
+    /** `SKILL.md` without the frontmatter. */
+    readonly body: string;
+    /** The reference files, by path. */
+    readonly references: readonly AppAgentSkillReference[];
+}
+/** The skill of this package. */
+export declare function readAppAgentSkill(): AppAgentSkill;
+/** The skill in `skillDir`, the `skill/` directory of an installed `@fabrika/app`. */
+export declare function readAppAgentSkillAt(skillDir: string): AppAgentSkill;
+/**
+ * The skill of the `@fabrika/app` an application installed: the nearest `node_modules/@fabrika/app` from `appRoot`
+ * up, as Bun resolves the package. `null` when the application has not installed it.
+ */
+export declare function installedAppAgentSkill(appRoot: string): AppAgentSkill | null;
+/** The `AGENTS.md` of an application repository: the skill's body, then each reference file. */
+export declare function renderAgentsFile(skill: AppAgentSkill): string;

package/types/src/build-recipe.d.ts

@@ -0,0 +1,70 @@
+export { CONTRACT_APP_ID_PATTERN } from './contract/app-id.js';
+export { FILE_SCAN_JOB, FILE_SWEEP_JOB } from './files/job-names.js';
+/** The TypeScript release of the platform's type check; the application's own `typescript` is not run. */
+export declare const PLATFORM_TYPESCRIPT_VERSION = "5.9.3";
+/** A `c.cron` job name, which a crontab line carries unquoted. */
+export declare const CONTRACT_JOB_NAME_PATTERN: RegExp;
+/** Five cron fields of digits and `*`, `/`, `,`, `-` only. */
+export declare const CRON_SCHEDULE_PATTERN: RegExp;
+/** What one contract application's recipe depends on. `contractRecipe` refuses a value that a shell would read as more. */
+export interface ContractRecipeInput {
+    readonly appId: string;
+    /** The `@fabrika/check` release whose reader read the application (ADR-0062). */
+    readonly checkRelease: string;
+    /** The absolute directory the build runs in: the checker reads the source there. */
+    readonly sourceRoot: string;
+    /** The absolute directory the built application runs from: each generated script starts there. */
+    readonly runtimeRoot: string;
+    /** With a database, every container migrates and checks its schema before the server starts. */
+    readonly database: boolean;
+    /** Whether the build uploads its source maps, last and never failing the build. */
+    readonly sourceMaps: boolean;
+    readonly jobs: readonly {
+        readonly name: string;
+        readonly schedule: string;
+    }[];
+    /** The contract declares a file collection: the sweep of removed files is scheduled. */
+    readonly files: boolean;
+    /** A file collection scans its uploads: the scan pass is scheduled. */
+    readonly scan: boolean;
+}
+/** One build step: a command run in the source root, or a generated file written there, line by line. */
+export type ContractBuildStep = {
+    readonly run: string;
+} | {
+    readonly write: string;
+    readonly lines: readonly string[];
+};
+/** One check of the build: a command run in the source root that fails the build. */
+export interface ContractCheck {
+    readonly name: 'tests' | 'tsc' | 'fabrika-check';
+    readonly command: string;
+}
+export interface ContractRecipe {
+    /** The steps after the authored SPA commands, in order. */
+    readonly build: readonly ContractBuildStep[];
+    /** The checks among `build`, in its order. */
+    readonly checks: readonly ContractCheck[];
+    /** The generated scripts every container runs before `start`, in order; any failure stops the activation. */
+    readonly init: readonly string[];
+    /** The generated script that starts the server, which only `exec`s it. */
+    readonly start: string;
+    /** The command the start script `exec`s, run from the runtime root. */
+    readonly serve: readonly string[];
+    /** The command that migrates the application's database, run from the runtime root. */
+    readonly migrate: readonly string[];
+    /** The jobs to schedule, each on one container; a command runs from the runtime root. */
+    readonly jobs: readonly {
+        readonly schedule: string;
+        readonly command: string;
+    }[];
+}
+/**
+ * The recipe of one contract application. The application's tests run first: they are authored code, so everything
+ * after them is reinstalled, regenerated or checked again. They run `--isolate`, as the application skill runs them: a
+ * test file's DOM globals otherwise leak into the next file. `tsc` runs before the checker, as in the skill's loop: the
+ * usual quick fix of a type error is a cast or an `any`, which only the checker refuses, so the checker is the last word
+ * on the code. The build has no database, so the schema checks run as init scripts, after the migrations and before the
+ * readiness window opens.
+ */
+export declare function contractRecipe(input: ContractRecipeInput): ContractRecipe;

package/types/src/build.d.ts

@@ -0,0 +1,29 @@
+/** An application root with this file is a contract application. The paths equal `@fabrika/check`'s layout. */
+export declare const CONTRACT_FILE = "fabrika.contract.ts";
+/** Relative to the application root. */
+export declare const GENERATED_ENTRY_FILE = "fabrika/entry.generated.ts";
+/** The module whose default export is `serve(contract, …)`, relative to the application root. */
+export declare const IMPLEMENTATION_FILE = "src/app.ts";
+/** The application's migrations as a module, relative to the application root: a Worker reads no file system. */
+export declare const GENERATED_MIGRATIONS_FILE = "fabrika/migrations.generated.ts";
+/** Where an application keeps its migrations, relative to its root; `fabrika db new` writes there. */
+export declare const MIGRATIONS_DIRECTORY = "db/migrations";
+export type EntryRuntime = 'bun' | 'cloudflare';
+export * from './build-recipe.js';
+export { CLOUDFLARE_APPLICATION_BINDING, CLOUDFLARE_APPLICATION_CLASS, CLOUDFLARE_ASSETS_BINDING, CLOUDFLARE_FILES_BINDING, } from './cloudflare/names.js';
+/** The entrypoint source for one runtime. */
+export declare function generatedEntry(runtime: EntryRuntime): string;
+/** Writes the entrypoint under `root` and returns its path; the Cloudflare one also writes the migrations module it imports. */
+export declare function writeGeneratedEntry(root: string, runtime: EntryRuntime): Promise<string>;
+/** The application's migrations under `root`, every `.sql` file of `db/migrations` by name; none without the directory. */
+export declare function applicationMigrations(root: string): Promise<readonly {
+    readonly name: string;
+    readonly sql: string;
+}[]>;
+/** The migrations module source: the files' names and texts, verbatim, so their checksums stay the files'. */
+export declare function generatedMigrations(migrations: readonly {
+    readonly name: string;
+    readonly sql: string;
+}[]): string;
+/** Writes the migrations module under `root` and returns its path. */
+export declare function writeGeneratedMigrations(root: string): Promise<string>;

package/types/src/bun.d.ts

@@ -0,0 +1,66 @@
+import type { FileObjectStore } from '@fabrika/platform';
+import type { FetchService, RequestExecutionContext } from './fetch.js';
+import { type IamKeySource } from './implement/boot.js';
+import { type CrashEvents } from './implement/crashes.js';
+import { type ContractImplementation } from './implement/implement.js';
+import { type JobRunOptions, type JobRunResult } from './jobs/runner.js';
+export { diskAssets } from './disk-assets.js';
+export { clamscanArguments, type ClamscanOptions, clamscanScanner } from './files/clamscan.js';
+export { markProductionProcess } from '@fabrika/db/production';
+export interface ManagedBunHandlerOptions {
+    /** Required sink for rejected background tasks. Do not log raw errors or secret-bearing values. */
+    onBackgroundError(error: unknown): void;
+    executionContext?: never;
+}
+export interface ExternalBunHandlerOptions {
+    /** Existing supervised process context. Its owner remains responsible for draining it. */
+    executionContext: RequestExecutionContext;
+    onBackgroundError?: never;
+}
+export type BunHandlerOptions = ManagedBunHandlerOptions | ExternalBunHandlerOptions;
+export interface BunHandler {
+    fetch(request: Request): Promise<Response>;
+    /** Wait until every task registered through `waitUntil()` has settled. */
+    drain(): Promise<void>;
+}
+export declare function createBunHandler<Env>(app: FetchService<Env>, env: Env, options: BunHandlerOptions): BunHandler;
+/** IAM's public key set at the issuer's `/.well-known/jwks.json`, for a process with no IAM binding. */
+export declare function issuerJwks(issuer: unknown): IamKeySource;
+export interface ContractServer {
+    /** The port the server listens on; `PORT=0` picks a free one. */
+    readonly port: number;
+    /** Stops accepting requests and waits for the ones in flight. */
+    stop(): Promise<void>;
+}
+/**
+ * The stored files' object storage (Zerops object storage, path-style), when the platform wrote its variables;
+ * a partial set stops the boot. The credentials are never quoted in a message.
+ */
+export declare function openFileStorage(framework: Readonly<Record<string, string>>): FileObjectStore | undefined;
+/** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
+export type ImplementationLoader = () => Promise<{
+    readonly default: ContractImplementation;
+}>;
+export interface ContractServerOptions {
+    /** Where the process hears of an uncaught exception or an unhandled rejection; `process` by default. */
+    readonly crashes?: CrashEvents;
+    /** What posts a report to Operations' ingest; `fetch` by default. */
+    readonly operationsFetch?: (request: Request) => Promise<Response>;
+}
+/**
+ * Captures the framework's variables and scrubs them from the process, then imports the application, boots it and
+ * serves it on `PORT` (default 3000), on every interface: the project's private network is how the proxy reaches
+ * it. Called only by the generated entrypoint, with `process.env`. SIGTERM drains. Given the provisioning credential,
+ * it is the launcher instead: it never loads the application and re-runs the entrypoint as the runtime role.
+ * With an Operations DSN, a startup that throws is reported before it is rethrown, and so is a crash once it serves.
+ */
+export declare function serveContract(load: ImplementationLoader, env: Readonly<Record<string, string | undefined>>, options?: ContractServerOptions): Promise<ContractServer>;
+/** The application module at `path`, imported when the loader runs; its default export must be what `serve` returned. */
+export declare function implementationAt(path: string): ImplementationLoader;
+/**
+ * One run of the job `name` (`fabrika job run <name>`, the crontab's command): the framework's variables are captured
+ * and scrubbed before the application loads, exactly as `serveContract` does, then `boot` binds the job and the run
+ * takes its lease. The connection closes when the run ends. Given the provisioning credential, it re-runs the command
+ * as the runtime role, as `serveContract` does.
+ */
+export declare function runContractJob(load: ImplementationLoader, env: Readonly<Record<string, string | undefined>>, name: string, options?: JobRunOptions): Promise<JobRunResult>;

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

@@ -0,0 +1,19 @@
+import { z } from 'zod/v4';
+declare const PageCallerSchema: z.ZodObject<{
+    label: z.ZodString;
+    email: z.ZodString;
+    actions: z.ZodObject<{
+        /** The actions held as a global grant, so in every value. */
+        app: z.ZodArray<z.ZodString>;
+        /** Each scope value the person holds something in, with those actions; sorted by dimension, then value. */
+        scopes: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            value: z.ZodString;
+            actions: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PageCaller = z.infer<typeof PageCallerSchema>;
+/** The caller document as the framework answers it; throws on any other value. */
+export declare function parsePageCaller(value: unknown): PageCaller;
+export {};

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/application.d.ts

@@ -0,0 +1,42 @@
+import { type SqliteStorage } from '@fabrika/db/sqlite';
+import { type CrashEvents } from '../implement/crashes.js';
+import type { ContractImplementation } from '../implement/implement.js';
+import { type OpsStorage } from './ops.js';
+/** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
+export type ImplementationLoader = () => Promise<{
+    readonly default: ContractImplementation;
+}>;
+/** One of the application's SQLite migrations, as `fabrika app build` bundles them from `db/migrations`. */
+export interface ApplicationMigration {
+    readonly name: string;
+    readonly sql: string;
+}
+export interface ContractWorkerOptions {
+    /** The application's own SQLite migrations, applied as the bundle `app` after the framework's `fabrika`. */
+    readonly migrations?: readonly ApplicationMigration[];
+    /** 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>;
+}
+/**
+ * Marks the Worker's minute tick, with its `scheduledTime`. The Worker's `fetch` removes it from every request it
+ * forwards, so only its own `scheduled` handler reaches the tick.
+ */
+export declare const TICK_HEADER = "X-Fabrika-Tick";
+/** What the object needs of its `ctx.storage`; a Durable Object's `DurableObjectStorage` fits it. */
+export type ApplicationStorage = SqliteStorage & OpsStorage;
+/** What the object needs of its `DurableObjectState`. */
+export interface ApplicationState {
+    readonly storage: ApplicationStorage;
+    blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+    waitUntil(promise: Promise<unknown>): void;
+}
+/** What the object classes of this isolate boot: the generated entrypoint's `createContractWorker` registers it. */
+export declare function registerApplication(load: ImplementationLoader, options: ContractWorkerOptions): void;
+/** The application environment's one object. The Worker's generated entrypoint exports it as `FabrikaApplication`. */
+export declare class FabrikaApplication {
+    #private;
+    constructor(state: ApplicationState, env: Readonly<Record<string, unknown>>);
+    fetch(request: Request): Promise<Response>;
+}