@fabrika/app 0.8.2 → 0.9.0-cloudflare.2

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'>;

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

@@ -0,0 +1,52 @@
+import type { AuthContext, Scope } from '@fabrika/auth';
+import type { StandardSchemaV1 } from '../standard-schema.js';
+import type { AuthRequirement, Procedure, Router, RouterDef } from './types.js';
+type Handler<TContext, TInput, TOutput> = (args: {
+    ctx: TContext;
+    input: TInput;
+}) => TOutput | Promise<TOutput>;
+/** Builder before an output schema is set — the terminal infers the output type from the handler. */
+export declare class ProcedureBuilder<TContext, TInput> {
+    private readonly _input;
+    private readonly _requirements;
+    constructor(_input: StandardSchemaV1<unknown, TInput>, _requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>);
+    /** Set the input schema — ANY Standard Schema validator (zod, valibot, arktype, …). Resets requirements. */
+    input<TNewInput>(schema: StandardSchemaV1<unknown, TNewInput>): ProcedureBuilder<TContext, TNewInput>;
+    /** Set an output schema → switch to the output builder (handler result validated against it). */
+    output<TOutput>(schema: StandardSchemaV1<unknown, TOutput>): OutputProcedureBuilder<TContext, TInput, TOutput>;
+    /**
+     * Record an authz requirement, checked BEFORE the handler runs (all must pass).
+     * Only available when the context carries `auth: AuthContext`.
+     */
+    require<TThis extends {
+        auth: AuthContext;
+    }>(this: ProcedureBuilder<TThis, TInput>, action: string, scopeResolver?: (input: TInput, ctx: TThis) => Scope | undefined): ProcedureBuilder<TThis, TInput>;
+    /** Terminal: a neutral handler (tagged `query`). Output type inferred from the return. */
+    handler<TOutput>(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+    /** Terminal: a `query`-tagged handler. Output type inferred from the return. */
+    query<TOutput>(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+    /** Terminal: a `mutation`-tagged handler. Output type inferred from the return. */
+    mutation<TOutput>(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+}
+/** Builder after `.output(schema)` — the terminal fixes the output to the schema type + validates it. */
+export declare class OutputProcedureBuilder<TContext, TInput, TOutput> {
+    private readonly _input;
+    private readonly _output;
+    private readonly _requirements;
+    constructor(_input: StandardSchemaV1<unknown, TInput>, _output: StandardSchemaV1<unknown, TOutput>, _requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>);
+    /** Record an authz requirement, checked BEFORE the handler runs (all must pass). */
+    require<TThis extends {
+        auth: AuthContext;
+    }>(this: OutputProcedureBuilder<TThis, TInput, TOutput>, action: string, scopeResolver?: (input: TInput, ctx: TThis) => Scope | undefined): OutputProcedureBuilder<TThis, TInput, TOutput>;
+    /** Terminal: a neutral handler (tagged `query`); result validated against the output schema. */
+    handler(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+    /** Terminal: a `query`-tagged handler; result validated against the output schema. */
+    query(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+    /** Terminal: a `mutation`-tagged handler; result validated against the output schema. */
+    mutation(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+}
+export declare function initRpc<TContext>(): {
+    procedure: ProcedureBuilder<TContext, void>;
+    router<TDef extends RouterDef>(def: TDef): Router<TDef>;
+};
+export {};

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

@@ -0,0 +1,23 @@
+import type { InferRouterClient, Procedure, Router, RouterDef } from './types.js';
+/** A type-only RPC procedure declaration for a portable API contract. */
+export interface RpcProcedureContract<TInput, TOutput> {
+    readonly '~rpc': {
+        readonly input: TInput;
+        readonly output: TOutput;
+    };
+}
+/** Client-facing view of a portable contract. */
+export type InferRpcContractClient<TContract> = TContract extends RpcProcedureContract<infer TInput, infer TOutput> ? (input: TInput) => Promise<TOutput> : TContract extends object ? {
+    [K in keyof TContract]: InferRpcContractClient<TContract[K]>;
+} : never;
+/** Client-facing view of either a server router or a portable contract. */
+export type InferRpcClient<TApi> = TApi extends {
+    readonly _tag: 'router';
+    readonly _def: RouterDef;
+} ? InferRouterClient<TApi> : InferRpcContractClient<TApi>;
+type RpcRouterDefinition<TContext, TContract> = {
+    readonly [K in keyof TContract]: TContract[K] extends RpcProcedureContract<infer TInput, infer TOutput> ? Procedure<TContext, TInput, TOutput> : TContract[K] extends object ? RpcRouterFor<TContext, TContract[K]> : never;
+};
+/** Server router shape required to implement a portable contract. */
+export type RpcRouterFor<TContext, TContract> = Router<RpcRouterDefinition<TContext, TContract>>;
+export {};

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

@@ -0,0 +1,11 @@
+import type { AnyRouter } from './types.js';
+/**
+ * Dispatch an RPC POST. The `ctx` is already built (with its `ctx.auth`, for example)
+ * by the server before this is called. One request is one call,
+ * `{ method, input }`.
+ */
+export declare function dispatchRpcRequest(args: {
+    router: AnyRouter;
+    ctx: unknown;
+    request: Request;
+}): Promise<Response>;

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

@@ -0,0 +1,62 @@
+import type { AuthContext, Scope } from '@fabrika/auth';
+import type { StandardSchemaV1 } from '../standard-schema.js';
+/** `query` and `mutation` are metadata today — the dispatcher treats them identically. */
+export type ProcedureKind = 'query' | 'mutation';
+/**
+ * A recorded authorization requirement. `scopeResolver` is declared as a METHOD
+ * (bivariant params) on purpose, so a concrete `Procedure<C, I, O>` stays
+ * assignable to `AnyProcedure`.
+ */
+export interface AuthRequirement<TContext, TInput> {
+    readonly action: string;
+    scopeResolver?(input: TInput, ctx: TContext): Scope | undefined;
+}
+export interface Procedure<TContext, TInput, TOutput> {
+    readonly _tag: 'procedure';
+    readonly kind: ProcedureKind;
+    readonly input: StandardSchemaV1<unknown, TInput>;
+    readonly output: StandardSchemaV1<unknown, TOutput> | null;
+    readonly requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>;
+    handler(args: {
+        ctx: TContext;
+        input: TInput;
+    }): Promise<TOutput> | TOutput;
+}
+export interface AnyProcedure {
+    readonly _tag: 'procedure';
+    readonly kind: ProcedureKind;
+    readonly input: StandardSchemaV1;
+    readonly output: StandardSchemaV1 | null;
+    readonly requirements: ReadonlyArray<AuthRequirement<unknown, unknown>>;
+    handler(args: {
+        ctx: unknown;
+        input: unknown;
+    }): Promise<unknown> | unknown;
+}
+export type RouterDef = {
+    readonly [key: string]: AnyProcedure | AnyRouter;
+};
+export interface Router<TDef extends RouterDef> {
+    readonly _tag: 'router';
+    readonly _def: TDef;
+}
+export type AnyRouter = Router<RouterDef>;
+/** Re-export the auth contract used by procedure requirements. */
+export type { AuthContext, Scope };
+/** Server-facing view of a router: each procedure as its handler signature. */
+export type InferRouter<TRouter> = TRouter extends {
+    _tag: 'router';
+    _def: infer TDef;
+} ? TDef extends RouterDef ? {
+    [K in keyof TDef]: TDef[K] extends Procedure<infer C, infer I, infer O> ? (args: {
+        ctx: C;
+        input: I;
+    }) => Promise<O> | O : TDef[K] extends Router<RouterDef> ? InferRouter<TDef[K]> : never;
+} : never : never;
+/** Client-facing view of a router: each procedure as `(input) => Promise<output>`. */
+export type InferRouterClient<TRouter> = TRouter extends {
+    _tag: 'router';
+    _def: infer TDef;
+} ? TDef extends RouterDef ? {
+    [K in keyof TDef]: TDef[K] extends Procedure<unknown, infer I, infer O> ? (input: I) => Promise<O> : TDef[K] extends Router<RouterDef> ? InferRouterClient<TDef[K]> : never;
+} : never : never;

package/types/src/service/define.d.ts

@@ -0,0 +1,42 @@
+import { type BodyAdmission, type InstallationCaller, type InstallationEndpointMethod, type InstallationEndpointRow, type InstallationEndpointTable } from '@fabrika/auth-core';
+/** A row as the builder writes it; the record key of `endpoints` becomes its id. */
+export type ServiceEndpointSpec = InstallationEndpointRow extends infer Row ? Row extends InstallationEndpointRow ? Omit<Row, 'id'> : never : never;
+/** One installation service's table, with the row ids as a type so its handlers can be checked against them. */
+export interface ServiceArtifact<Id extends string = string> extends InstallationEndpointTable {
+    /** The service's IAM app id; never `<app>@<env>`. */
+    readonly id: string;
+    readonly endpoints: readonly (InstallationEndpointRow & {
+        readonly id: Id;
+    })[];
+}
+export interface ServiceEndpointOptions {
+    readonly callers: readonly [InstallationCaller, ...InstallationCaller[]];
+    /** The request body the row admits; omitted admits none. */
+    readonly admission?: BodyAdmission;
+    /** The scopes an OAuth resource token must carry; required exactly when `callers` holds `oauth`. */
+    readonly scopes?: readonly string[];
+}
+export interface ServiceContractBuilder {
+    /** A liveness endpoint: anonymous, and served without `X-Fabrika-Endpoint`. */
+    health(method: InstallationEndpointMethod, path: string): ServiceEndpointSpec;
+    /** An endpoint the service authenticates itself; the proxy reads no credential and keeps `Authorization`. */
+    protocol(method: InstallationEndpointMethod, path: string): ServiceEndpointSpec;
+    /** A credentialed endpoint: a listed caller kind, and no permission (`authenticated`). */
+    service(method: InstallationEndpointMethod, path: string, options: ServiceEndpointOptions): ServiceEndpointSpec;
+}
+export interface ServiceContractDeclaration<Id extends string> {
+    /** `null` is a row this composition does not serve: the table has no row there, and its handler is never called. */
+    readonly endpoints: Readonly<Record<Id, ServiceEndpointSpec | null>>;
+    /** Literal prefixes a path under which reaches only a row declared under it. */
+    readonly reservedPrefixes: readonly string[];
+}
+export declare class ServiceContractError extends Error {
+    readonly name = "ServiceContractError";
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/**
+ * Declare one installation service's endpoint table. Validated here, once: an id that is an application environment,
+ * an `oauth` caller without its scopes (or scopes without it), and every table the matcher would refuse.
+ */
+export declare function defineServiceContract<const Id extends string>(id: string, declare: (s: ServiceContractBuilder) => ServiceContractDeclaration<Id>): ServiceArtifact<Id>;

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

@@ -0,0 +1,3 @@
+export { dispatchRpcRequest } from '../rpc/dispatcher.js';
+export { defineServiceContract, type ServiceArtifact, type ServiceContractBuilder, type ServiceContractDeclaration, ServiceContractError, type ServiceEndpointOptions, type ServiceEndpointSpec, } from './define.js';
+export { serveService, type ServeServiceOptions, type ServiceHandler, type ServiceHandlers, ServiceHandlersError, type ServiceRequest, } from './serve.js';

package/types/src/service/serve.d.ts

@@ -0,0 +1,28 @@
+import type { FetchService, RequestExecutionContext } from '../fetch.js';
+import type { ServiceArtifact } from './define.js';
+export interface ServiceRequest<Env> {
+    readonly request: Request;
+    /** The `:name` segments of the selected path, percent-decoded. */
+    readonly params: Readonly<Record<string, string>>;
+    readonly env: Env;
+    readonly exec: RequestExecutionContext;
+}
+export type ServiceHandler<Env> = (input: ServiceRequest<Env>) => Response | Promise<Response>;
+/** One handler per declared row id, also for a row this composition left out; that one is never called. */
+export type ServiceHandlers<Id extends string, Env> = {
+    readonly [K in Id]: ServiceHandler<Env>;
+};
+export interface ServeServiceOptions<Env> {
+    /** Map a value a handler threw to a response. Defaults to the structural error mapping. */
+    readonly onError?: (error: unknown, request: Request, env: Env) => Response;
+}
+export declare class ServiceHandlersError extends Error {
+    readonly name = "ServiceHandlersError";
+}
+/**
+ * Serve a service contract. Per request: a non-canonical path is a 400, a request no row selects a 404, a `service`
+ * row reached without the proxy's `X-Fabrika-Endpoint` for that row and its digest a 503; then the row's handler. A
+ * `protocol` or `health` row ignores the header, because the service authenticates it itself and it also arrives
+ * unfronted (ADR-0022 rule 5).
+ */
+export declare function serveService<Id extends string, Env>(service: ServiceArtifact<Id>, handlers: ServiceHandlers<Id, Env>, options?: ServeServiceOptions<Env>): FetchService<Env>;

package/types/src/spa-fallback.d.ts

@@ -0,0 +1,2 @@
+/** A GET or HEAD whose last path segment has no extension, or one that asks for HTML (a navigation to `/notes/v1.2`). */
+export declare function isPageRoute(request: Request): boolean;

package/types/src/standard-schema.d.ts

@@ -0,0 +1,55 @@
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}

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

@@ -0,0 +1,95 @@
+import type { PermissionEntry, PrincipalAffiliation } from '@fabrika/auth-core';
+import type { ActionOf, AnyContract, DimensionOf, RoleOf } from '../contract/define';
+/** `app` is the connector of another application: its key reaches only the exports that application consumes. */
+export type TestCallerKind = 'human' | 'machine' | 'link' | 'app';
+export interface TestScope<D extends string = string> {
+    readonly type: D;
+    readonly value: string;
+}
+/** An action, or a role whose actions IAM grants together; without a scope it is global. */
+export type TestGrant<C> = {
+    readonly action: ActionOf<C>;
+    readonly scope?: TestScope<DimensionOf<C>>;
+} | {
+    readonly role: RoleOf<C>;
+    readonly scope?: TestScope<DimensionOf<C>>;
+};
+export interface TestCallerOptions {
+    /** Defaults to `human`. */
+    readonly kind?: TestCallerKind;
+    /** How a human signs in: the IAM session (default) or a `px_` key bound to the person. Other kinds use a key. */
+    readonly via?: 'session' | 'key';
+    readonly id?: string;
+    readonly label?: string;
+    /** A human's address (`ctx.principal.email`), normalized as IAM stores it. Only a human has one. */
+    readonly email?: string;
+    /**
+     * Defaults to `internal`. An `external` human holds only roles the contract declares `external`, as IAM resolves it
+     * (ADR-0051); the kit refuses any other grant for one.
+     */
+    readonly affiliation?: PrincipalAffiliation;
+    /**
+     * An operator disabled the principal in IAM: a member directory lists and finds it with `disabled: true`, and the kit's
+     * IAM signs no token for its session or key, so its requests are refused as IAM refuses a disabled principal's.
+     */
+    readonly disabled?: boolean;
+    /**
+     * When the person last signed in to the application (unix seconds), as IAM records it at the handoff; absent, never.
+     * A member directory answers it to a holder of `members.manage` only. Only a human signs in.
+     */
+    readonly lastSignInAt?: number;
+    /** The consuming application's id, for an `app` caller. */
+    readonly app?: string;
+    /**
+     * What a `link` caller's key is bound to: the link mount, and the object first, then each value containing it. A link
+     * caller without one holds a key bound to nothing, which no procedure admits.
+     */
+    readonly link?: TestLink;
+}
+export interface TestLink {
+    readonly mount: string;
+    readonly chain: readonly TestScope[];
+}
+interface TestCallerCredential {
+    /** The principal id, or the share key's credential id for a link. */
+    readonly id: string;
+    /** `internal` for every caller but an `external` human. */
+    readonly affiliation: PrincipalAffiliation;
+    /** `true` for a principal an operator disabled; `false` for every other caller, a link holder included. */
+    readonly disabled: boolean;
+    /** A human's last sign-in to the application (`TestCallerOptions.lastSignInAt`); `null` for one that never did and every other caller. */
+    readonly lastSignInAt: number | null;
+    readonly perms: readonly PermissionEntry[];
+    /** The `px_` key a key caller presents as a bearer; `null` for a session. */
+    readonly key: string | null;
+    /** The `Cookie` header a signed-in browser sends; `null` for a key caller. */
+    readonly cookie: string | null;
+}
+/** A person, a script or another application's connector: a principal with a label. */
+export interface LabelledTestCaller extends TestCallerCredential {
+    readonly kind: Exclude<TestCallerKind, 'link'>;
+    /** The consuming application of an `app` caller, `null` for every other kind. */
+    readonly app: string | null;
+    readonly link: null;
+    readonly label: string;
+    /** A human's normalized address, which its token carries; `null` for a script and a connector. */
+    readonly email: string | null;
+}
+/** A person, whose token carries its address: `ctx.principal.email` of its requests. */
+export interface PersonTestCaller extends LabelledTestCaller {
+    readonly kind: 'human';
+    readonly email: string;
+}
+/** The holder of a share link: an anonymous key, which carries no label. */
+export interface LinkTestCaller extends TestCallerCredential {
+    readonly kind: 'link';
+    readonly app: null;
+    /** The link mount and chain the key is bound to; `null` for a key bound to nothing. */
+    readonly link: TestLink | null;
+    readonly label: null;
+    readonly email: null;
+}
+export type TestCaller = LabelledTestCaller | LinkTestCaller;
+/** The permissions `grants` resolve to: a role becomes each of its actions in the role's scope. */
+export declare function resolveGrants<C extends AnyContract>(contract: C, grants: readonly TestGrant<C>[]): PermissionEntry[];
+export {};

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

@@ -0,0 +1,11 @@
+import type { RpcFetch } from '../client/transport';
+import type { ChallengeFetch } from '../implement/challenge';
+/** The token Turnstile's always-passing test widget (site key `1x00000000000000000000AA`) hands out every time. */
+export declare const TURNSTILE_TEST_TOKEN = "XXXX.DUMMY.TOKEN.XXXX";
+/** Turnstile's siteverify that passes every token: a fresh answer for the host and the form the check expects. */
+export declare const passingChallenge: ChallengeFetch;
+/**
+ * Fetches a challenge from `url` through `fetch` and solves it as the widget does, answering the payload the page puts
+ * into `challengeToken`. The kit issues the cheapest challenge, so this takes milliseconds.
+ */
+export declare function solveChallengeAt(fetch: RpcFetch, url: string): Promise<string>;

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

@@ -0,0 +1,97 @@
+import { type EmailDeliveryErrorCode, type EmailDeliveryOutcome } from '@fabrika/email';
+import type { AnyContract, DimensionOf } from '../contract/define';
+import type { ContractImplementation } from '../implement/implement';
+import type { PersonTestCaller, TestCaller } from './caller';
+import { type TestKit, type TestKitOptions } from './kit';
+import type { SentInvitation, TestMembership } from './membership';
+/** Someone the author clicks through the application as: a person the seed made with `dev.testCaller`. */
+export interface DevPersona {
+    /** Shown on the picker's card and in the toolbar, unique among the personas: `Petra`. */
+    readonly name: string;
+    /** One short line of who this is: `Staff of the design workspace`. */
+    readonly description?: string;
+    readonly caller: PersonTestCaller;
+}
+/** A page a link holder opens: a link the seed issued through the application's own endpoint. */
+export interface DevLink {
+    readonly title: string;
+    readonly description?: string;
+    /** The URL the application answered, a path of its origin: `/s/#px_…`. */
+    readonly url: string;
+}
+/** A scope value the seed made, with the name a person knows it by: `{ value: 'w1', label: 'Design team' }`. */
+export interface DevScopeValue {
+    readonly value: string;
+    readonly label: string;
+}
+/** What a seed answers; every part is optional. */
+export interface DevSeedResult<C extends AnyContract> {
+    readonly personas?: readonly DevPersona[];
+    readonly links?: readonly DevLink[];
+    /** The values of each dimension the seed made, which the picker offers for a membership role. */
+    readonly scopes?: {
+        readonly [D in DimensionOf<C>]?: readonly DevScopeValue[];
+    };
+}
+/** The origin `fabrika app dev` captures every request to: an outside provider's stand-in, named by its path. */
+export declare const DEV_OUTBOX_ORIGIN = "https://outbox.invalid";
+/** A request the application sent to `DEV_OUTBOX_ORIGIN` under `fabrika app dev`: its body, never its headers. */
+export interface DevOutboxMessage {
+    readonly id: number;
+    readonly method: string;
+    /** The path it was sent to: `/mail`. */
+    readonly path: string;
+    readonly contentType: string | null;
+    readonly body: string;
+}
+/** A message a job handed to the kit's mail stand-in, as `fabrika app dev` shows it. */
+export interface DevMail {
+    /** Its position among the handoffs, from 1. */
+    readonly id: number;
+    /** When it was handed off, ISO 8601. */
+    readonly at: string;
+    readonly to: string;
+    readonly subject: string;
+    readonly text: string;
+    readonly html: string | null;
+    readonly replyTo: string | null;
+    readonly fromName: string | null;
+    /** The idempotency key as the job passed it. */
+    readonly key: string;
+    /** The key the transport got: `key` behind the application environment's prefix. */
+    readonly transportKey: string;
+    readonly answer: 'accepted' | EmailDeliveryErrorCode;
+    readonly outcome: 'accepted' | EmailDeliveryOutcome;
+    /** Whether this handoff put the message in the inbox; a repeat under its key does not. */
+    readonly delivered: boolean;
+}
+/** What `fabrika app dev` stands in for outside the application, for the seed to read. */
+export interface DevOutside {
+    /** Every request sent to `DEV_OUTBOX_ORIGIN` so far, oldest first. */
+    outbox(): readonly DevOutboxMessage[];
+    /** Every message a job handed to the mail stand-in so far, oldest first. */
+    mails(): readonly DevMail[];
+}
+/**
+ * The default export of `dev/seed.ts`: it receives the application's test kit, the API its tests use, writes through the
+ * endpoints, and answers who and what the picker offers. `outside` reads what the application sent to the dev outbox
+ * and every message a job handed to the mail stand-in, oldest first.
+ */
+export type DevSeed<C extends AnyContract> = (dev: TestKit<C>, outside: DevOutside) => Promise<DevSeedResult<C>> | DevSeedResult<C>;
+export interface DevKit<C extends AnyContract> {
+    readonly kit: TestKit<C>;
+    /** The person `value` is when this kit made it; `undefined` for any other value. */
+    personOf(value: unknown): PersonTestCaller | undefined;
+    /** The roles a caller of this kit holds now: its grants, with what the application assigned and revoked through IAM. */
+    membershipsOf(caller: TestCaller): readonly TestMembership[];
+    /** The invitation e-mails the stand-in IAM sent, in the order it first sent them. */
+    invitations(): readonly SentInvitation[];
+    /** Every message the application's jobs handed to the mail stand-in, oldest first; one refused before the handoff is absent. */
+    mails(): readonly DevMail[];
+}
+/**
+ * The test kit of `app` with its stand-in IAM, and what `fabrika app dev` shows of it. A challenge passes
+ * (`passingChallenge`) unless `options.challengeFetch` answers it, and admits the test widget's token
+ * (`TURNSTILE_TEST_TOKEN`) at every call; any other token is single use, as deployed.
+ */
+export declare function devKit<C extends AnyContract>(app: ContractImplementation<C>, options?: Omit<TestKitOptions, 'membership'>): DevKit<C>;