@crvouga/mockingbird-service-paddle 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,1836 @@
+import { Server } from 'node:http';
+import { Hono } from 'hono';
+
+/**
+ * The single source of time for a service.
+ *
+ * Every timestamp a mock writes reads from here, so a suite moves time instead of
+ * sleeping: appointment windows, result delays and expiries become reachable in
+ * milliseconds. A frozen clock also makes timestamps reproducible from a seed.
+ */
+type ClockState$1 = {
+    /** Current epoch milliseconds. */
+    now: number;
+    /** True while time does not advance on its own. */
+    frozen: boolean;
+    /** Milliseconds this clock adds to its underlying source. */
+    offsetMs: number;
+};
+type Clock$1 = {
+    now(): number;
+    /** Pin the clock to an exact instant, keeping it frozen if it already was. */
+    set(epochMs: number): void;
+    /** Move the clock forward, or back with a negative delta. */
+    advance(deltaMs: number): void;
+    /** Stop time at the current instant. */
+    freeze(): void;
+    /** Resume from the current instant. */
+    unfreeze(): void;
+    /** Drop back to the underlying source, live. */
+    reset(): void;
+    state(): ClockState$1;
+};
+
+/** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
+type SqliteValue$2 = null | number | bigint | string | Uint8Array | boolean;
+/** Mutation counters returned by {@link SqliteStatement.run}. */
+type SqliteRunResult$2 = {
+    changes: number;
+    lastInsertRowid: number | bigint;
+};
+/**
+ * Prepared statement bound to a {@link SqliteClient}.
+ *
+ * Pass bind values as rest arguments on each call (no sticky `bind()`).
+ */
+interface SqliteStatement$2 {
+    run(...params: SqliteValue$2[]): SqliteRunResult$2;
+    all<T = Record<string, unknown>>(...params: SqliteValue$2[]): T[];
+    get<T = Record<string, unknown>>(...params: SqliteValue$2[]): T | undefined;
+}
+/**
+ * Sync SQLite client port owned by Mockingbird.
+ *
+ * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
+ * `bun:sqlite` instances all work when they expose this surface.
+ */
+interface SqliteClient$2 {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement$2;
+    transaction<T>(fn: () => T): T;
+}
+
+/**
+ * Seeded pseudo-random numbers, so anything a mock invents — ids, jitter, which
+ * request a percentage fault hits — is reproducible from a seed.
+ *
+ * mulberry32: small, fast, and stable across runtimes, which matters more here
+ * than statistical quality.
+ */
+type Rng$1 = {
+    /** Next value in `[0, 1)`. */
+    next(): number;
+    /** Next integer in `[min, max]`. */
+    int(min: number, max: number): number;
+    /** Restart the stream from its seed. */
+    reset(): void;
+    /** Serializable engine state used by deterministic checkpoints. */
+    state(): number;
+    /** Restore a state previously returned by {@link state}. */
+    setState(state: number): void;
+    seed: number;
+};
+
+/**
+ * A deliberate failure injected in front of an operation.
+ *
+ * This is how a suite reaches the vendor's failure modes without the vendor: the
+ * quota error that only appears when a shared sandbox is full, the 429 that only
+ * appears under load, the 5xx that proves a retry path works.
+ */
+type FaultRule$1 = {
+    /** Stable id, so a suite can retire exactly the rule it added. */
+    id: string;
+    /** Fault only this operation. Omit to match every operation. */
+    operationId?: string;
+    /** Fault only this HTTP method, case-insensitive. Omit to match every method. */
+    method?: string;
+    /** Fault only paths starting with this prefix. Omit to match every path. */
+    pathPrefix?: string;
+    /**
+     * Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
+     * an in-process caller usually wants, and what a parallel worker usually does not:
+     * rules added through `POST /__admin/faults` default to the calling namespace.
+     */
+    namespace?: string;
+    /**
+     * Status of the injected response. Omit for a rule that only delays (`delayMs` /
+     * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
+     * the request then still reaches the service.
+     */
+    status?: number;
+    /** Response body, serialized as JSON. A string is sent as-is. */
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** Retire the rule after this many faults. Omit to keep it until removed. */
+    count?: number;
+    /** Fault this fraction of matching requests, `0`–`1`. Default `1`. */
+    rate?: number;
+    /** Hold the response back this long, to exercise timeouts. */
+    delayMs?: number;
+    /** Alias of `delayMs`. */
+    latencyMs?: number;
+    /**
+     * Drop the connection instead of answering: an in-process `fetch` rejects with a
+     * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
+     */
+    drop?: boolean;
+    /**
+     * A named service behaviour to switch on for the matching request instead of (or
+     * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
+     * read it with `faultEffects(request)`.
+     */
+    effect?: string;
+    /** Parameters for `effect`. */
+    params?: Record<string, unknown>;
+    /** From the preset this rule was expanded from, if any. */
+    preset?: string;
+};
+/** A fault that fired for one request. */
+type FaultHit$1 = {
+    id: string;
+    /** The injected response; absent when the rule only delays, drops, or sets an effect. */
+    response?: Response;
+    drop?: boolean;
+    effect?: {
+        name: string;
+        params: Record<string, unknown>;
+    };
+};
+/** What a request looks like to the fault matcher. */
+type FaultCandidate$1 = {
+    operationId: string | undefined;
+    method: string;
+    path: string;
+    namespace: string;
+};
+type FaultRegistry$1 = {
+    add(rule: FaultRule$1): FaultRule$1;
+    list(): (FaultRule$1 & {
+        remaining: number | null;
+        hits: number;
+    })[];
+    remove(id: string): boolean;
+    clear(): void;
+    /**
+     * Every fault this request should get, in rule order, stopping at the first that answers
+     * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
+     * each matching rule's remaining uses.
+     */
+    take(candidate: FaultCandidate$1): Promise<FaultHit$1[]>;
+};
+
+/** A stable identifier for a point in a {@link Timeline}. */
+type CheckpointId$1 = string;
+/** An immutable node in a timeline's checkpoint DAG. */
+type Checkpoint$1<T> = Readonly<{
+    id: CheckpointId$1;
+    branch: string;
+    parent: CheckpointId$1 | null;
+    /** Logical time supplied by the timeline's injected clock. */
+    at: number;
+    value: T;
+}>;
+type TimelineOptions$1 = {
+    /** Logical clock used to stamp checkpoints. Defaults to a deterministic counter. */
+    now?: () => number;
+    /** Maximum retained checkpoints. Branch heads are never collected. Default 1,000. */
+    maxCheckpoints?: number;
+    /** Customize deterministic checkpoint IDs. */
+    id?: (sequence: number) => CheckpointId$1;
+};
+type CommitOptions$1 = {
+    branch?: string;
+    /** Parent checkpoint. Defaults to the selected branch's current head. */
+    parent?: CheckpointId$1 | null;
+};
+type ForkOptions$1 = {
+    /** Checkpoint to fork from. Defaults to the main branch's head. */
+    from?: CheckpointId$1;
+};
+/**
+ * Small, storage-agnostic checkpoint DAG shared by service runtimes. Its values may be immutable
+ * records, namespace images, or copy-on-write SQL engine snapshots.
+ *
+ * Values are retained by reference. Engines can therefore use persistent/COW snapshots while
+ * simpler services can use immutable values. IDs and GC order are deterministic, and all IO
+ * (the logical clock) is injected.
+ */
+declare class Timeline$1<T> {
+    readonly maxCheckpoints: number;
+    private readonly now;
+    private readonly makeId;
+    private readonly nodes;
+    private readonly heads;
+    /** Unreferenced nodes in the exact order they became collectible. */
+    private readonly evictable;
+    /** Branch heads plus explicit retainers. Absent means zero. */
+    private readonly references;
+    private readonly explicitPins;
+    private sequence;
+    constructor(options?: TimelineOptions$1);
+    /** Capture a new immutable value and move `branch` to it. */
+    commit(value: T, options?: CommitOptions$1): Checkpoint$1<T>;
+    /** Create a branch pointer without copying its checkpoint value. */
+    fork(branch: string, options?: ForkOptions$1): Checkpoint$1<T> | undefined;
+    /** Move a branch pointer to an existing checkpoint. */
+    checkout(branch: string, id: CheckpointId$1): Checkpoint$1<T>;
+    get(id: CheckpointId$1): Checkpoint$1<T>;
+    head(branch?: string): Checkpoint$1<T> | undefined;
+    hasBranch(branch: string): boolean;
+    branches(): Readonly<Record<string, CheckpointId$1>>;
+    checkpoints(): readonly Checkpoint$1<T>[];
+    /** Number of retained checkpoints without allocating an array. */
+    get size(): number;
+    /** Pin a checkpoint independently of branch heads (used by compatibility snapshot handles). */
+    retain(id: CheckpointId$1): Checkpoint$1<T>;
+    /** Release one explicit pin. Branch heads remain pinned until moved or deleted. */
+    release(id: CheckpointId$1): boolean;
+    deleteBranch(branch: string): boolean;
+    /**
+     * Deterministically discard oldest unpinned checkpoints. Collection is O(number removed):
+     * commits never scan pinned nodes or the retained history. Parents are metadata rather than a
+     * storage dependency, so a retained node remains usable after pruning.
+     */
+    gc(max?: number): CheckpointId$1[];
+    private collect;
+    private moveHead;
+    private addReference;
+    private removeReference;
+    private assertBranch;
+}
+
+/**
+ * Anything that can answer a Fetch `Request` with a `Response`.
+ *
+ * Every Mockingbird service implements this, and every runtime adapter consumes it.
+ * It is the only contract shared across the whole graph.
+ */
+interface FetchAPI$2 {
+    fetch(request: Request): Promise<Response>;
+}
+
+/**
+ * One problem with a request body, at a dotted path (`patient.address.city`, `items.0.sku`).
+ * `kind` is `media_type` when the body is present but its media type is not one the operation
+ * accepts (a `415` on most vendors), `syntax` when it could not be decoded, `required` when
+ * the operation needs a body and none arrived, and `schema` for a contract violation.
+ */
+type BodyIssue$1 = {
+    path: string;
+    message: string;
+    kind?: "media_type" | "syntax" | "required" | "schema";
+};
+
+/**
+ * What the mock received from a request it rejected, so a 4xx can be attributed after the
+ * fact (an empty body, a missing `content-type`, a schema violation) without logging the body.
+ */
+type RejectedRequest$1 = {
+    /** The raw `content-type` header, or `null` when the request sent none. */
+    contentType: string | null;
+    /** Bytes of body received from `content-length` (`0` for none), or `null` when the client sent no length (a streamed / chunked body). */
+    bodyBytes: number | null;
+    /** The raw `transfer-encoding` header (`chunked`), or `null`. */
+    transferEncoding: string | null;
+};
+/** One handled request, as the structured log sees it. */
+type RequestLog$1 = {
+    service: string;
+    namespace: string;
+    operationId: string | undefined;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    /** True when the path matched no operation in the contract. */
+    unmatched: boolean;
+    /** Set when a fault rule produced the response. */
+    faultId?: string;
+    /** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
+    ids?: Record<string, string>;
+    /** Set when the service created a resource the request referred to but that did not exist. */
+    adopted?: boolean;
+    /** Set on a rejection (status ≥ 400) the mock produced itself, never on a scripted fault. */
+    request?: RejectedRequest$1;
+    /** The validation issues behind a rejection, when the service found any. */
+    issues?: BodyIssue$1[];
+};
+type MetricsReport$1 = {
+    requests: number;
+    /** Counts keyed `<operationId> <status>`. */
+    byOperation: Record<string, number>;
+    /**
+     * Paths that matched no operation, most frequent first.
+     *
+     * This is the early-warning signal: a consumer calling something the mock does
+     * not implement shows up here as a count, before it fails a suite as a 404.
+     */
+    unmatched: {
+        method: string;
+        path: string;
+        count: number;
+    }[];
+    faults: number;
+    totalDurationMs: number;
+};
+type Metrics$1 = {
+    record(entry: RequestLog$1): void;
+    report(): MetricsReport$1;
+    reset(): void;
+};
+
+/** One journal entry: a request log stamped with when (on the mock clock) it was handled. */
+type JournalEntry$1 = RequestLog$1 & {
+    at: string;
+};
+type JournalQuery$1 = {
+    /** Only this namespace. Omit for every namespace, oldest first across all of them. */
+    namespace?: string;
+    operationId?: string;
+    status?: number;
+    /** Only entries at or after this instant (epoch ms). */
+    since?: number;
+    /** At most this many, the most recent kept. */
+    limit?: number;
+};
+type Journal$1 = {
+    readonly size: number;
+    record(entry: JournalEntry$1): void;
+    list(query?: JournalQuery$1): JournalEntry$1[];
+    /** Forget one namespace's entries, or every namespace's. */
+    clear(namespace?: string): void;
+};
+
+/** Credential → namespace mapping behind `PUT /__admin/credentials`. */
+type CredentialRegistry$1 = {
+    set(credential: string, namespace: string): void;
+    get(credential: string): string | undefined;
+    remove(credential: string): boolean;
+    clear(): void;
+    entries(): {
+        credential: string;
+        namespace: string;
+    }[];
+};
+
+/**
+ * A point-in-time copy of everything a service namespace holds.
+ *
+ * All service state lives in the two core tables keyed by namespace, so a snapshot
+ * is generic: any service gets per-test rollback without knowing its own schema.
+ * Restoring is much cheaper than rebuilding a namespace from a corpus.
+ */
+type NamespaceSnapshot$1 = {
+    namespace: string;
+    records: {
+        collection: string;
+        id: string;
+        seq: number;
+        value: string;
+    }[];
+    sequences: {
+        name: string;
+        kind: string;
+        value: number;
+    }[];
+};
+
+declare const STATE_FIELD_KINDS$1: readonly ["string", "number", "boolean", "null", "object", "array", "unknown"];
+type StateFieldKind$1 = (typeof STATE_FIELD_KINDS$1)[number];
+/** JSON-safe annotations a bespoke admin UI may read. The default UI shows them as text. */
+type StateMeta$1 = Readonly<Record<string, string | number | boolean | null>>;
+type StateField$1 = {
+    name: string;
+    kind: StateFieldKind$1;
+    optional: boolean;
+    description?: string;
+    /** One level of nested object fields. */
+    fields?: StateField$1[];
+    meta?: StateMeta$1;
+};
+type StateCollectionView$1 = {
+    name: string;
+    label: string;
+    description?: string;
+    count: number;
+    /** `mixed` when a declaration and stored rows both contribute fields. */
+    source: "declared" | "inferred" | "mixed";
+    fields: StateField$1[];
+    meta?: StateMeta$1;
+};
+/** The shape of one namespace, for an admin UI that has never seen the service before. */
+type StateView$1 = {
+    namespace: string;
+    storageNamespace: string;
+    collections: StateCollectionView$1[];
+};
+
+type WebhookEndpoint$1 = {
+    /** Stable id; generated when omitted. */
+    id?: string;
+    url: string;
+    secret?: string;
+    /** Event types to deliver; omit or include `"*"` for every type. */
+    events?: string[];
+    /** Deliver only messages whose tags include all of these (e.g. `{ account: "mso" }`). */
+    tags?: Record<string, string>;
+    /** The public URL the receiver verifies signatures against (Twilio), when it differs. */
+    signUrl?: string;
+    headers?: Record<string, string>;
+};
+type WebhookMessage$1 = {
+    id: string;
+    namespace: string;
+    type: string;
+    body: string;
+    contentType: string;
+    tags: Record<string, string>;
+    headers?: Record<string, string>;
+    /** Wall-clock ISO-8601 time of publication. */
+    publishedAt: string;
+};
+type WebhookAttempt$1 = {
+    attempt: number;
+    at: string;
+    status: number | null;
+    error: string | null;
+    durationMs: number;
+    /** Exact receiver response body, when one was returned. */
+    responseBody?: string | null;
+};
+type WebhookDelivery$1 = {
+    id: string;
+    messageId: string;
+    namespace: string;
+    type: string;
+    endpointId: string;
+    url: string;
+    state: "pending" | "delivered" | "failed" | "dropped";
+    attempts: WebhookAttempt$1[];
+};
+/** A delivery-level fault: what happens to the next `count` messages in a namespace. */
+type WebhookFault$1 = {
+    mode: "duplicate" | "reorder" | "drop";
+    /** Messages affected; default 1. */
+    count?: number;
+};
+type PublishInput$1 = {
+    namespace: string;
+    type: string;
+    /** Exact body; objects are JSON-encoded. */
+    body: string | Record<string, unknown> | unknown[];
+    /** Default `application/json`, or form-encoded when `form` is given. */
+    contentType?: string;
+    /** Form parameters, when the vendor posts `application/x-www-form-urlencoded`. */
+    form?: Record<string, string>;
+    tags?: Record<string, string>;
+    /** Message-specific delivery headers, captured as part of durable message state. */
+    headers?: Record<string, string>;
+    /** Message id; generated when omitted. */
+    id?: string;
+};
+type WebhookHub$1 = {
+    publish(input: PublishInput$1): WebhookMessage$1;
+    /** Replace a namespace's own endpoints (`PUT /__admin/webhook-endpoints`). */
+    setEndpoints(namespace: string, endpoints: WebhookEndpoint$1[]): WebhookEndpoint$1[];
+    /** The endpoints a namespace delivers to: its own, plus the global ones. */
+    endpoints(namespace: string): WebhookEndpoint$1[];
+    messages(namespace?: string): WebhookMessage$1[];
+    deliveries(namespace?: string): WebhookDelivery$1[];
+    replay(deliveryId: string): Promise<WebhookDelivery$1 | undefined>;
+    /** Run every pending retry (and release held reordered messages) now, and every retry those attempts schedule, until nothing is pending. */
+    flush(): Promise<void>;
+    /** Resolve once nothing is in flight. */
+    idle(): Promise<void>;
+    fault(namespace: string, fault: WebhookFault$1): void;
+    clear(namespace?: string): void;
+};
+
+/** What the runtime needs from a service: a Fetch handler it can reset. */
+type ServiceInstance$1 = FetchAPI$2 & {
+    reset(): Promise<void>;
+};
+type ServiceTimelineState$1 = Readonly<{
+    snapshot: NamespaceSnapshot$1;
+    clock: Readonly<ReturnType<Clock$1["state"]>>;
+    rngState: number;
+}>;
+type ServiceCheckpoint$1 = Checkpoint$1<ServiceTimelineState$1>;
+type ServiceRuntime$1<T extends ServiceInstance$1> = FetchAPI$2 & {
+    readonly name: string;
+    readonly sqlite: SqliteClient$2;
+    readonly clock: Clock$1;
+    readonly faults: FaultRegistry$1;
+    readonly metrics: Metrics$1;
+    readonly journal: Journal$1;
+    readonly rng: Rng$1;
+    readonly credentials: CredentialRegistry$1;
+    /** The webhook hub, when the service has outbound webhooks. */
+    readonly webhooks: WebhookHub$1 | undefined;
+    /** Expand a named preset into fault rules (and webhook faults) for `namespace`. */
+    applyPreset(name: string, namespace?: string, overrides?: Partial<FaultRule$1>): FaultRule$1[];
+    /** The instance behind `namespace` (the default one when omitted), created on first use. */
+    instance(namespace?: string): T;
+    /** Public names of every namespace created so far. */
+    namespaces(): string[];
+    /** Reset one namespace, or every namespace with `"*"`. */
+    reset(namespace?: string): Promise<void>;
+    snapshot(namespace?: string): NamespaceSnapshot$1;
+    restore(snapshot: NamespaceSnapshot$1, namespace?: string): void;
+    /** Capture the current branch. Mutating HTTP calls do this automatically. */
+    checkpoint(namespace?: string, branch?: string): ServiceCheckpoint$1;
+    /** Create an isolated branch, optionally from a historical checkpoint. */
+    branch(name: string, options?: {
+        namespace?: string;
+        at?: string;
+    }): ServiceCheckpoint$1;
+    /** Restore a branch, clock, and PRNG to a checkpoint. */
+    checkout(checkpoint: string, options?: {
+        namespace?: string;
+        branch?: string;
+    }): void;
+    /** Inspect the retained history for a namespace. */
+    timeline(namespace?: string): Timeline$1<ServiceTimelineState$1>;
+    /** Collections in one namespace: declared shape plus what the rows actually hold. */
+    state(namespace?: string): StateView$1;
+};
+
+type CliOption = {
+    type: "string" | "boolean";
+    description: string;
+    /** Shown in help; the value placeholder, e.g. `<port>`. */
+    value?: string;
+    default?: string | boolean;
+};
+type CliValues = Record<string, string | boolean | undefined>;
+type CommonServeOptions = {
+    adminKey: string | undefined;
+    seed: string | undefined;
+    onLog: ((entry: RequestLog$1) => void) | undefined;
+};
+/**
+ * What a service contributes to `serve`: how to build its runtime from CLI flags,
+ * and what to say at startup. Every service's `./server` entry exports one as
+ * `serveTarget`, which is also how `serve --config` finds services by name.
+ */
+type ServeTarget = {
+    name: string;
+    defaultPort: number;
+    /** Serve flags beyond the common ones. */
+    options?: Record<string, CliOption>;
+    create(values: CliValues, common: CommonServeOptions): Promise<ServiceRuntime$1<ServiceInstance$1>> | ServiceRuntime$1<ServiceInstance$1>;
+    /** Startup lines after the listen address, e.g. the loaded corpus version. */
+    banner?(runtime: ServiceRuntime$1<ServiceInstance$1>): string[];
+};
+
+/** A running server, with the address it actually bound. */
+type Listening = {
+    url: string;
+    port: number;
+    host: string;
+    server: Server;
+    close(): Promise<void>;
+};
+
+/**
+ * The single source of time for a service.
+ *
+ * Every timestamp a mock writes reads from here, so a suite moves time instead of
+ * sleeping: appointment windows, result delays and expiries become reachable in
+ * milliseconds. A frozen clock also makes timestamps reproducible from a seed.
+ */
+type ClockState = {
+    /** Current epoch milliseconds. */
+    now: number;
+    /** True while time does not advance on its own. */
+    frozen: boolean;
+    /** Milliseconds this clock adds to its underlying source. */
+    offsetMs: number;
+};
+type Clock = {
+    now(): number;
+    /** Pin the clock to an exact instant, keeping it frozen if it already was. */
+    set(epochMs: number): void;
+    /** Move the clock forward, or back with a negative delta. */
+    advance(deltaMs: number): void;
+    /** Stop time at the current instant. */
+    freeze(): void;
+    /** Resume from the current instant. */
+    unfreeze(): void;
+    /** Drop back to the underlying source, live. */
+    reset(): void;
+    state(): ClockState;
+};
+
+/** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
+type SqliteValue$1 = null | number | bigint | string | Uint8Array | boolean;
+/** Mutation counters returned by {@link SqliteStatement.run}. */
+type SqliteRunResult$1 = {
+    changes: number;
+    lastInsertRowid: number | bigint;
+};
+/**
+ * Prepared statement bound to a {@link SqliteClient}.
+ *
+ * Pass bind values as rest arguments on each call (no sticky `bind()`).
+ */
+interface SqliteStatement$1 {
+    run(...params: SqliteValue$1[]): SqliteRunResult$1;
+    all<T = Record<string, unknown>>(...params: SqliteValue$1[]): T[];
+    get<T = Record<string, unknown>>(...params: SqliteValue$1[]): T | undefined;
+}
+/**
+ * Sync SQLite client port owned by Mockingbird.
+ *
+ * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
+ * `bun:sqlite` instances all work when they expose this surface.
+ */
+interface SqliteClient$1 {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement$1;
+    transaction<T>(fn: () => T): T;
+}
+
+/** Every stored record carries a monotonically increasing sequence for stable ordering. */
+type Stored<T> = {
+    seq: number;
+    value: T;
+};
+type ListRecordsOptions<T> = {
+    /** Keep only records passing the predicate. */
+    where?: (value: T, seq: number) => boolean;
+    /** Sort order; default newest first. */
+    order?: "newest" | "oldest";
+};
+/**
+ * A SQLite-backed table of JSON records addressed by id. Ordering is by insertion
+ * sequence, never by id lexicographic order, so list semantics stay stable.
+ */
+declare class Collection<T> {
+    private readonly sqlite;
+    /** Storage namespace. Admin introspection uses this to ignore another namespace's tables. */
+    readonly namespace: string;
+    /** Table name inside the namespace. Stable across resets of the rows themselves. */
+    readonly collectionName: string;
+    constructor(sqlite: SqliteClient$1, 
+    /** Storage namespace. Admin introspection uses this to ignore another namespace's tables. */
+    namespace: string, 
+    /** Table name inside the namespace. Stable across resets of the rows themselves. */
+    collectionName: string);
+    private bumpCollectionSeq;
+    nextSequence(): number;
+    get(id: string): T | undefined;
+    has(id: string): boolean;
+    /** Insert a new record, assigning it the next sequence number. */
+    insert(id: string, value: T): Stored<T>;
+    /** Replace an existing record's value, keeping its position. */
+    update(id: string, value: T): Stored<T> | undefined;
+    delete(id: string): boolean;
+    /** How many records the collection holds, without reading them. */
+    count(): number;
+    list(options?: ListRecordsOptions<T>): Array<Stored<T> & {
+        id: string;
+    }>;
+}
+
+/**
+ * Seeded pseudo-random numbers, so anything a mock invents — ids, jitter, which
+ * request a percentage fault hits — is reproducible from a seed.
+ *
+ * mulberry32: small, fast, and stable across runtimes, which matters more here
+ * than statistical quality.
+ */
+type Rng = {
+    /** Next value in `[0, 1)`. */
+    next(): number;
+    /** Next integer in `[min, max]`. */
+    int(min: number, max: number): number;
+    /** Restart the stream from its seed. */
+    reset(): void;
+    /** Serializable engine state used by deterministic checkpoints. */
+    state(): number;
+    /** Restore a state previously returned by {@link state}. */
+    setState(state: number): void;
+    seed: number;
+};
+
+/**
+ * A deliberate failure injected in front of an operation.
+ *
+ * This is how a suite reaches the vendor's failure modes without the vendor: the
+ * quota error that only appears when a shared sandbox is full, the 429 that only
+ * appears under load, the 5xx that proves a retry path works.
+ */
+type FaultRule = {
+    /** Stable id, so a suite can retire exactly the rule it added. */
+    id: string;
+    /** Fault only this operation. Omit to match every operation. */
+    operationId?: string;
+    /** Fault only this HTTP method, case-insensitive. Omit to match every method. */
+    method?: string;
+    /** Fault only paths starting with this prefix. Omit to match every path. */
+    pathPrefix?: string;
+    /**
+     * Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
+     * an in-process caller usually wants, and what a parallel worker usually does not:
+     * rules added through `POST /__admin/faults` default to the calling namespace.
+     */
+    namespace?: string;
+    /**
+     * Status of the injected response. Omit for a rule that only delays (`delayMs` /
+     * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
+     * the request then still reaches the service.
+     */
+    status?: number;
+    /** Response body, serialized as JSON. A string is sent as-is. */
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** Retire the rule after this many faults. Omit to keep it until removed. */
+    count?: number;
+    /** Fault this fraction of matching requests, `0`–`1`. Default `1`. */
+    rate?: number;
+    /** Hold the response back this long, to exercise timeouts. */
+    delayMs?: number;
+    /** Alias of `delayMs`. */
+    latencyMs?: number;
+    /**
+     * Drop the connection instead of answering: an in-process `fetch` rejects with a
+     * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
+     */
+    drop?: boolean;
+    /**
+     * A named service behaviour to switch on for the matching request instead of (or
+     * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
+     * read it with `faultEffects(request)`.
+     */
+    effect?: string;
+    /** Parameters for `effect`. */
+    params?: Record<string, unknown>;
+    /** From the preset this rule was expanded from, if any. */
+    preset?: string;
+};
+/** A fault that fired for one request. */
+type FaultHit = {
+    id: string;
+    /** The injected response; absent when the rule only delays, drops, or sets an effect. */
+    response?: Response;
+    drop?: boolean;
+    effect?: {
+        name: string;
+        params: Record<string, unknown>;
+    };
+};
+/** What a request looks like to the fault matcher. */
+type FaultCandidate = {
+    operationId: string | undefined;
+    method: string;
+    path: string;
+    namespace: string;
+};
+type FaultRegistry = {
+    add(rule: FaultRule): FaultRule;
+    list(): (FaultRule & {
+        remaining: number | null;
+        hits: number;
+    })[];
+    remove(id: string): boolean;
+    clear(): void;
+    /**
+     * Every fault this request should get, in rule order, stopping at the first that answers
+     * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
+     * each matching rule's remaining uses.
+     */
+    take(candidate: FaultCandidate): Promise<FaultHit[]>;
+};
+
+/** A stable identifier for a point in a {@link Timeline}. */
+type CheckpointId = string;
+/** An immutable node in a timeline's checkpoint DAG. */
+type Checkpoint<T> = Readonly<{
+    id: CheckpointId;
+    branch: string;
+    parent: CheckpointId | null;
+    /** Logical time supplied by the timeline's injected clock. */
+    at: number;
+    value: T;
+}>;
+type TimelineOptions = {
+    /** Logical clock used to stamp checkpoints. Defaults to a deterministic counter. */
+    now?: () => number;
+    /** Maximum retained checkpoints. Branch heads are never collected. Default 1,000. */
+    maxCheckpoints?: number;
+    /** Customize deterministic checkpoint IDs. */
+    id?: (sequence: number) => CheckpointId;
+};
+type CommitOptions = {
+    branch?: string;
+    /** Parent checkpoint. Defaults to the selected branch's current head. */
+    parent?: CheckpointId | null;
+};
+type ForkOptions = {
+    /** Checkpoint to fork from. Defaults to the main branch's head. */
+    from?: CheckpointId;
+};
+/**
+ * Small, storage-agnostic checkpoint DAG shared by service runtimes. Its values may be immutable
+ * records, namespace images, or copy-on-write SQL engine snapshots.
+ *
+ * Values are retained by reference. Engines can therefore use persistent/COW snapshots while
+ * simpler services can use immutable values. IDs and GC order are deterministic, and all IO
+ * (the logical clock) is injected.
+ */
+declare class Timeline<T> {
+    readonly maxCheckpoints: number;
+    private readonly now;
+    private readonly makeId;
+    private readonly nodes;
+    private readonly heads;
+    /** Unreferenced nodes in the exact order they became collectible. */
+    private readonly evictable;
+    /** Branch heads plus explicit retainers. Absent means zero. */
+    private readonly references;
+    private readonly explicitPins;
+    private sequence;
+    constructor(options?: TimelineOptions);
+    /** Capture a new immutable value and move `branch` to it. */
+    commit(value: T, options?: CommitOptions): Checkpoint<T>;
+    /** Create a branch pointer without copying its checkpoint value. */
+    fork(branch: string, options?: ForkOptions): Checkpoint<T> | undefined;
+    /** Move a branch pointer to an existing checkpoint. */
+    checkout(branch: string, id: CheckpointId): Checkpoint<T>;
+    get(id: CheckpointId): Checkpoint<T>;
+    head(branch?: string): Checkpoint<T> | undefined;
+    hasBranch(branch: string): boolean;
+    branches(): Readonly<Record<string, CheckpointId>>;
+    checkpoints(): readonly Checkpoint<T>[];
+    /** Number of retained checkpoints without allocating an array. */
+    get size(): number;
+    /** Pin a checkpoint independently of branch heads (used by compatibility snapshot handles). */
+    retain(id: CheckpointId): Checkpoint<T>;
+    /** Release one explicit pin. Branch heads remain pinned until moved or deleted. */
+    release(id: CheckpointId): boolean;
+    deleteBranch(branch: string): boolean;
+    /**
+     * Deterministically discard oldest unpinned checkpoints. Collection is O(number removed):
+     * commits never scan pinned nodes or the retained history. Parents are metadata rather than a
+     * storage dependency, so a retained node remains usable after pruning.
+     */
+    gc(max?: number): CheckpointId[];
+    private collect;
+    private moveHead;
+    private addReference;
+    private removeReference;
+    private assertBranch;
+}
+
+/**
+ * Anything that can answer a Fetch `Request` with a `Response`.
+ *
+ * Every Mockingbird service implements this, and every runtime adapter consumes it.
+ * It is the only contract shared across the whole graph.
+ */
+interface FetchAPI$1 {
+    fetch(request: Request): Promise<Response>;
+}
+
+/** Options every provider constructor accepts. */
+type APIOptions = {
+    /** Sync SQLite client. Defaults to `@crvouga/mockingbird-service-sqlite`. */
+    sqlite?: SqliteClient$1;
+    /** Clock used for `created`-style fields. Default `Date.now`. */
+    now?: () => number;
+    /**
+     * Storage namespace for this instance's records. Instances sharing one SQLite
+     * client stay isolated when their namespaces differ. Defaults to the service name.
+     */
+    namespace?: string;
+};
+
+/**
+ * One problem with a request body, at a dotted path (`patient.address.city`, `items.0.sku`).
+ * `kind` is `media_type` when the body is present but its media type is not one the operation
+ * accepts (a `415` on most vendors), `syntax` when it could not be decoded, `required` when
+ * the operation needs a body and none arrived, and `schema` for a contract violation.
+ */
+type BodyIssue = {
+    path: string;
+    message: string;
+    kind?: "media_type" | "syntax" | "required" | "schema";
+};
+
+/**
+ * What the mock received from a request it rejected, so a 4xx can be attributed after the
+ * fact (an empty body, a missing `content-type`, a schema violation) without logging the body.
+ */
+type RejectedRequest = {
+    /** The raw `content-type` header, or `null` when the request sent none. */
+    contentType: string | null;
+    /** Bytes of body received from `content-length` (`0` for none), or `null` when the client sent no length (a streamed / chunked body). */
+    bodyBytes: number | null;
+    /** The raw `transfer-encoding` header (`chunked`), or `null`. */
+    transferEncoding: string | null;
+};
+/** One handled request, as the structured log sees it. */
+type RequestLog = {
+    service: string;
+    namespace: string;
+    operationId: string | undefined;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    /** True when the path matched no operation in the contract. */
+    unmatched: boolean;
+    /** Set when a fault rule produced the response. */
+    faultId?: string;
+    /** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
+    ids?: Record<string, string>;
+    /** Set when the service created a resource the request referred to but that did not exist. */
+    adopted?: boolean;
+    /** Set on a rejection (status ≥ 400) the mock produced itself, never on a scripted fault. */
+    request?: RejectedRequest;
+    /** The validation issues behind a rejection, when the service found any. */
+    issues?: BodyIssue[];
+};
+type MetricsReport = {
+    requests: number;
+    /** Counts keyed `<operationId> <status>`. */
+    byOperation: Record<string, number>;
+    /**
+     * Paths that matched no operation, most frequent first.
+     *
+     * This is the early-warning signal: a consumer calling something the mock does
+     * not implement shows up here as a count, before it fails a suite as a 404.
+     */
+    unmatched: {
+        method: string;
+        path: string;
+        count: number;
+    }[];
+    faults: number;
+    totalDurationMs: number;
+};
+type Metrics = {
+    record(entry: RequestLog): void;
+    report(): MetricsReport;
+    reset(): void;
+};
+
+/** One journal entry: a request log stamped with when (on the mock clock) it was handled. */
+type JournalEntry = RequestLog & {
+    at: string;
+};
+type JournalQuery = {
+    /** Only this namespace. Omit for every namespace, oldest first across all of them. */
+    namespace?: string;
+    operationId?: string;
+    status?: number;
+    /** Only entries at or after this instant (epoch ms). */
+    since?: number;
+    /** At most this many, the most recent kept. */
+    limit?: number;
+};
+type Journal = {
+    readonly size: number;
+    record(entry: JournalEntry): void;
+    list(query?: JournalQuery): JournalEntry[];
+    /** Forget one namespace's entries, or every namespace's. */
+    clear(namespace?: string): void;
+};
+
+/** Credential → namespace mapping behind `PUT /__admin/credentials`. */
+type CredentialRegistry = {
+    set(credential: string, namespace: string): void;
+    get(credential: string): string | undefined;
+    remove(credential: string): boolean;
+    clear(): void;
+    entries(): {
+        credential: string;
+        namespace: string;
+    }[];
+};
+
+/**
+ * A point-in-time copy of everything a service namespace holds.
+ *
+ * All service state lives in the two core tables keyed by namespace, so a snapshot
+ * is generic: any service gets per-test rollback without knowing its own schema.
+ * Restoring is much cheaper than rebuilding a namespace from a corpus.
+ */
+type NamespaceSnapshot = {
+    namespace: string;
+    records: {
+        collection: string;
+        id: string;
+        seq: number;
+        value: string;
+    }[];
+    sequences: {
+        name: string;
+        kind: string;
+        value: number;
+    }[];
+};
+
+declare const STATE_FIELD_KINDS: readonly ["string", "number", "boolean", "null", "object", "array", "unknown"];
+type StateFieldKind = (typeof STATE_FIELD_KINDS)[number];
+/** JSON-safe annotations a bespoke admin UI may read. The default UI shows them as text. */
+type StateMeta = Readonly<Record<string, string | number | boolean | null>>;
+type StateField = {
+    name: string;
+    kind: StateFieldKind;
+    optional: boolean;
+    description?: string;
+    /** One level of nested object fields. */
+    fields?: StateField[];
+    meta?: StateMeta;
+};
+type StateCollectionView = {
+    name: string;
+    label: string;
+    description?: string;
+    count: number;
+    /** `mixed` when a declaration and stored rows both contribute fields. */
+    source: "declared" | "inferred" | "mixed";
+    fields: StateField[];
+    meta?: StateMeta;
+};
+/** The shape of one namespace, for an admin UI that has never seen the service before. */
+type StateView = {
+    namespace: string;
+    storageNamespace: string;
+    collections: StateCollectionView[];
+};
+
+type WebhookEndpoint = {
+    /** Stable id; generated when omitted. */
+    id?: string;
+    url: string;
+    secret?: string;
+    /** Event types to deliver; omit or include `"*"` for every type. */
+    events?: string[];
+    /** Deliver only messages whose tags include all of these (e.g. `{ account: "mso" }`). */
+    tags?: Record<string, string>;
+    /** The public URL the receiver verifies signatures against (Twilio), when it differs. */
+    signUrl?: string;
+    headers?: Record<string, string>;
+};
+type WebhookMessage = {
+    id: string;
+    namespace: string;
+    type: string;
+    body: string;
+    contentType: string;
+    tags: Record<string, string>;
+    headers?: Record<string, string>;
+    /** Wall-clock ISO-8601 time of publication. */
+    publishedAt: string;
+};
+type WebhookAttempt = {
+    attempt: number;
+    at: string;
+    status: number | null;
+    error: string | null;
+    durationMs: number;
+    /** Exact receiver response body, when one was returned. */
+    responseBody?: string | null;
+};
+type WebhookDelivery = {
+    id: string;
+    messageId: string;
+    namespace: string;
+    type: string;
+    endpointId: string;
+    url: string;
+    state: "pending" | "delivered" | "failed" | "dropped";
+    attempts: WebhookAttempt[];
+};
+/** A delivery-level fault: what happens to the next `count` messages in a namespace. */
+type WebhookFault = {
+    mode: "duplicate" | "reorder" | "drop";
+    /** Messages affected; default 1. */
+    count?: number;
+};
+type PublishInput = {
+    namespace: string;
+    type: string;
+    /** Exact body; objects are JSON-encoded. */
+    body: string | Record<string, unknown> | unknown[];
+    /** Default `application/json`, or form-encoded when `form` is given. */
+    contentType?: string;
+    /** Form parameters, when the vendor posts `application/x-www-form-urlencoded`. */
+    form?: Record<string, string>;
+    tags?: Record<string, string>;
+    /** Message-specific delivery headers, captured as part of durable message state. */
+    headers?: Record<string, string>;
+    /** Message id; generated when omitted. */
+    id?: string;
+};
+type WebhookHub = {
+    publish(input: PublishInput): WebhookMessage;
+    /** Replace a namespace's own endpoints (`PUT /__admin/webhook-endpoints`). */
+    setEndpoints(namespace: string, endpoints: WebhookEndpoint[]): WebhookEndpoint[];
+    /** The endpoints a namespace delivers to: its own, plus the global ones. */
+    endpoints(namespace: string): WebhookEndpoint[];
+    messages(namespace?: string): WebhookMessage[];
+    deliveries(namespace?: string): WebhookDelivery[];
+    replay(deliveryId: string): Promise<WebhookDelivery | undefined>;
+    /** Run every pending retry (and release held reordered messages) now, and every retry those attempts schedule, until nothing is pending. */
+    flush(): Promise<void>;
+    /** Resolve once nothing is in flight. */
+    idle(): Promise<void>;
+    fault(namespace: string, fault: WebhookFault): void;
+    clear(namespace?: string): void;
+};
+
+/** What the runtime needs from a service: a Fetch handler it can reset. */
+type ServiceInstance = FetchAPI$1 & {
+    reset(): Promise<void>;
+};
+type ServiceTimelineState = Readonly<{
+    snapshot: NamespaceSnapshot;
+    clock: Readonly<ReturnType<Clock["state"]>>;
+    rngState: number;
+}>;
+type ServiceCheckpoint = Checkpoint<ServiceTimelineState>;
+type ServiceRuntime<T extends ServiceInstance> = FetchAPI$1 & {
+    readonly name: string;
+    readonly sqlite: SqliteClient$1;
+    readonly clock: Clock;
+    readonly faults: FaultRegistry;
+    readonly metrics: Metrics;
+    readonly journal: Journal;
+    readonly rng: Rng;
+    readonly credentials: CredentialRegistry;
+    /** The webhook hub, when the service has outbound webhooks. */
+    readonly webhooks: WebhookHub | undefined;
+    /** Expand a named preset into fault rules (and webhook faults) for `namespace`. */
+    applyPreset(name: string, namespace?: string, overrides?: Partial<FaultRule>): FaultRule[];
+    /** The instance behind `namespace` (the default one when omitted), created on first use. */
+    instance(namespace?: string): T;
+    /** Public names of every namespace created so far. */
+    namespaces(): string[];
+    /** Reset one namespace, or every namespace with `"*"`. */
+    reset(namespace?: string): Promise<void>;
+    snapshot(namespace?: string): NamespaceSnapshot;
+    restore(snapshot: NamespaceSnapshot, namespace?: string): void;
+    /** Capture the current branch. Mutating HTTP calls do this automatically. */
+    checkpoint(namespace?: string, branch?: string): ServiceCheckpoint;
+    /** Create an isolated branch, optionally from a historical checkpoint. */
+    branch(name: string, options?: {
+        namespace?: string;
+        at?: string;
+    }): ServiceCheckpoint;
+    /** Restore a branch, clock, and PRNG to a checkpoint. */
+    checkout(checkpoint: string, options?: {
+        namespace?: string;
+        branch?: string;
+    }): void;
+    /** Inspect the retained history for a namespace. */
+    timeline(namespace?: string): Timeline<ServiceTimelineState>;
+    /** Collections in one namespace: declared shape plus what the rows actually hold. */
+    state(namespace?: string): StateView;
+};
+
+/** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
+type SqliteValue = null | number | bigint | string | Uint8Array | boolean;
+/** Mutation counters returned by {@link SqliteStatement.run}. */
+type SqliteRunResult = {
+    changes: number;
+    lastInsertRowid: number | bigint;
+};
+/**
+ * Prepared statement bound to a {@link SqliteClient}.
+ *
+ * Pass bind values as rest arguments on each call (no sticky `bind()`).
+ */
+interface SqliteStatement {
+    run(...params: SqliteValue[]): SqliteRunResult;
+    all<T = Record<string, unknown>>(...params: SqliteValue[]): T[];
+    get<T = Record<string, unknown>>(...params: SqliteValue[]): T | undefined;
+}
+/**
+ * Sync SQLite client port owned by Mockingbird.
+ *
+ * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
+ * `bun:sqlite` instances all work when they expose this surface.
+ */
+interface SqliteClient {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+    transaction<T>(fn: () => T): T;
+}
+
+/**
+ * Anything that can answer a Fetch `Request` with a `Response`.
+ *
+ * Every Mockingbird service implements this, and every runtime adapter consumes it.
+ * It is the only contract shared across the whole graph.
+ */
+interface FetchAPI {
+    fetch(request: Request): Promise<Response>;
+}
+
+/**
+ * Stored records are the wire shape Paddle returns as `data` (snake_case), so a handler can
+ * serve them as-is and `include=` relations are layered on at response time.
+ */
+type Status = "active" | "archived";
+type CatalogType = "standard" | "custom";
+type Interval = "day" | "week" | "month" | "year";
+type CollectionMode = "automatic" | "manual";
+type TransactionStatus = "draft" | "ready" | "billed" | "paid" | "completed" | "canceled" | "past_due";
+type TransactionOrigin = "api" | "subscription_charge" | "subscription_payment_method_change" | "subscription_recurring" | "subscription_update" | "web";
+type SubscriptionStatus = "active" | "canceled" | "past_due" | "paused" | "trialing";
+type CustomData = Record<string, unknown> | null;
+type TimePeriod = {
+    interval: Interval;
+    frequency: number;
+};
+type TrialPeriod = TimePeriod & {
+    requires_payment_method?: boolean;
+};
+type Money = {
+    amount: string;
+    currency_code: string;
+};
+type Period = {
+    starts_at: string;
+    ends_at: string;
+};
+type BillingDetails = {
+    enable_checkout: boolean;
+    purchase_order_number: string | null;
+    additional_information: string | null;
+    payment_terms: TimePeriod;
+};
+type CustomerRecord = {
+    id: string;
+    name: string | null;
+    email: string;
+    marketing_consent: boolean;
+    status: Status;
+    custom_data: CustomData;
+    locale: string;
+    created_at: string;
+    updated_at: string;
+    import_meta: null;
+};
+type AddressRecord = {
+    id: string;
+    customer_id: string;
+    description: string | null;
+    first_line: string | null;
+    second_line: string | null;
+    city: string | null;
+    postal_code: string | null;
+    region: string | null;
+    country_code: string;
+    custom_data: CustomData;
+    status: Status;
+    created_at: string;
+    updated_at: string;
+    import_meta: null;
+};
+type BusinessRecord = {
+    id: string;
+    customer_id: string;
+    name: string;
+    company_number: string | null;
+    tax_identifier: string | null;
+    status: Status;
+    contacts: {
+        name: string | null;
+        email: string;
+    }[] | null;
+    created_at: string;
+    updated_at: string;
+    custom_data: CustomData;
+    import_meta: null;
+};
+type ProductRecord = {
+    id: string;
+    name: string;
+    type: CatalogType;
+    description: string | null;
+    tax_category: string;
+    image_url: string | null;
+    custom_data: CustomData;
+    status: Status;
+    created_at: string;
+    updated_at: string;
+    import_meta: null;
+};
+type PriceRecord = {
+    id: string;
+    product_id: string;
+    description: string;
+    type: CatalogType;
+    name: string | null;
+    billing_cycle: TimePeriod | null;
+    trial_period: TrialPeriod | null;
+    tax_mode: string;
+    unit_price: Money;
+    unit_price_overrides: {
+        country_codes: string[];
+        unit_price: Money;
+    }[];
+    quantity: {
+        minimum: number;
+        maximum: number;
+    };
+    status: Status;
+    created_at: string;
+    updated_at: string;
+    custom_data: CustomData;
+    import_meta: null;
+};
+type Totals = {
+    subtotal: string;
+    discount: string;
+    tax: string;
+    total: string;
+};
+type TransactionTotals = Totals & {
+    credit: string;
+    credit_to_balance: string;
+    balance: string;
+    grand_total: string;
+    grand_total_tax: string;
+    fee: string | null;
+    earnings: string | null;
+    currency_code: string;
+};
+type LineItem = {
+    id: string;
+    price_id: string;
+    quantity: number;
+    proration: null;
+    tax_rate: string;
+    unit_totals: Totals;
+    totals: Totals;
+    product: ProductRecord;
+};
+type TransactionDetails = {
+    tax_rates_used: {
+        tax_rate: string;
+        totals: Totals;
+    }[];
+    totals: TransactionTotals;
+    adjusted_totals: {
+        subtotal: string;
+        tax: string;
+        total: string;
+        grand_total: string;
+        grand_total_tax: string;
+        fee: string | null;
+        earnings: string | null;
+        currency_code: string;
+        retained_fee: string;
+    };
+    payout_totals: null;
+    adjusted_payout_totals: null;
+    line_items: LineItem[];
+};
+type PaymentAttempt = {
+    payment_attempt_id: string;
+    stored_payment_method_id: string;
+    payment_method_id: string | null;
+    amount: string;
+    status: "captured" | "error";
+    error_code: string | null;
+    method_details: {
+        type: "card";
+        card: {
+            type: string;
+            last4: string;
+            expiry_month: number;
+            expiry_year: number;
+            cardholder_name: string;
+        };
+        paypal: null;
+        south_korea_local_card: null;
+        underlying_details: null;
+    } | null;
+    created_at: string;
+    captured_at: string | null;
+};
+type TransactionItem = {
+    price_id: string;
+    /** The price as it was when the transaction was written, as Paddle embeds it. */
+    price: PriceRecord;
+    quantity: number;
+    proration: null;
+};
+type TransactionRecord = {
+    id: string;
+    status: TransactionStatus;
+    customer_id: string | null;
+    address_id: string | null;
+    business_id: string | null;
+    custom_data: CustomData;
+    currency_code: string;
+    origin: TransactionOrigin;
+    subscription_id: string | null;
+    invoice_id: string | null;
+    invoice_number: string | null;
+    collection_mode: CollectionMode;
+    discount_id: null;
+    billing_details: BillingDetails | null;
+    billing_period: Period | null;
+    items: TransactionItem[];
+    details: TransactionDetails;
+    payments: PaymentAttempt[];
+    checkout: {
+        url: string | null;
+    } | null;
+    created_at: string;
+    updated_at: string;
+    billed_at: string | null;
+    revised_at: null;
+};
+type SubscriptionItem = {
+    status: "active" | "inactive" | "trialing";
+    quantity: number;
+    recurring: boolean;
+    created_at: string;
+    updated_at: string;
+    previously_billed_at: string | null;
+    next_billed_at: string | null;
+    trial_dates: Period | null;
+    price: PriceRecord;
+    product: ProductRecord;
+};
+type ScheduledChange = {
+    action: "cancel" | "pause" | "resume";
+    effective_at: string;
+    resume_at: string | null;
+};
+type SubscriptionRecord = {
+    id: string;
+    status: SubscriptionStatus;
+    customer_id: string;
+    address_id: string;
+    business_id: string | null;
+    currency_code: string;
+    created_at: string;
+    updated_at: string;
+    started_at: string | null;
+    first_billed_at: string | null;
+    next_billed_at: string | null;
+    paused_at: string | null;
+    canceled_at: string | null;
+    discount: null;
+    collection_mode: CollectionMode;
+    billing_details: BillingDetails | null;
+    current_billing_period: Period | null;
+    billing_cycle: TimePeriod;
+    scheduled_change: ScheduledChange | null;
+    management_urls: {
+        update_payment_method: string | null;
+        cancel: string;
+    };
+    items: SubscriptionItem[];
+    custom_data: CustomData;
+    import_meta: null;
+};
+/** One-time charges queued with `effective_from: next_billing_period`, billed at the next renewal. */
+type PendingCharge = {
+    price_id: string;
+    quantity: number;
+};
+type EventRecord = {
+    event_id: string;
+    event_type: string;
+    occurred_at: string;
+    notification_id: null;
+    data: Record<string, unknown>;
+};
+
+/** Paddle id prefixes, per entity. */
+declare const ID_PREFIX: {
+    readonly customer: "ctm";
+    readonly address: "add";
+    readonly business: "biz";
+    readonly product: "pro";
+    readonly price: "pri";
+    readonly transaction: "txn";
+    readonly subscription: "sub";
+    readonly event: "evt";
+    readonly notification: "ntf";
+    readonly line_item: "txnitm";
+    readonly payment_attempt: "payatt";
+    readonly payment_method: "paymtd";
+    readonly invoice: "inv";
+};
+type IdKind = keyof typeof ID_PREFIX;
+declare class PaddleState {
+    readonly customers: Collection<CustomerRecord>;
+    readonly addresses: Collection<AddressRecord>;
+    readonly businesses: Collection<BusinessRecord>;
+    readonly products: Collection<ProductRecord>;
+    readonly prices: Collection<PriceRecord>;
+    readonly transactions: Collection<TransactionRecord>;
+    readonly subscriptions: Collection<SubscriptionRecord>;
+    /** Queued one-time charges per subscription id. */
+    readonly pendingCharges: Collection<PendingCharge[]>;
+    readonly events: Collection<EventRecord>;
+    private readonly ids;
+    constructor(sqlite: SqliteClient, namespace: string);
+    /**
+     * A Paddle-shaped id: `<prefix>_01` followed by 24 lower-case alphanumerics (Paddle ids are a
+     * prefix plus a 26-character ULID), deterministic for a given history.
+     */
+    nextId(kind: IdKind): string;
+    /** An opaque token (auth tokens, signing material), deterministic for a given history. */
+    nextToken(prefix: string, length: number): string;
+}
+
+type Json = Record<string, unknown>;
+/** What `POST /__admin/checkout` accepts: a hosted-checkout completion, in one call. */
+type CheckoutInput = {
+    /** An existing customer, or an email to find or create one by. */
+    customer_id?: string;
+    email?: string;
+    name?: string;
+    /** An existing address of the customer, or a country to create one for. Default `US`. */
+    address_id?: string;
+    country_code?: string;
+    postal_code?: string;
+    business_id?: string;
+    items: {
+        price_id: string;
+        quantity?: number;
+    }[];
+    custom_data?: CustomData;
+    currency_code?: string;
+};
+type CardInput = {
+    type?: string;
+    last4?: string;
+    expiry_month?: number;
+    expiry_year?: number;
+    cardholder_name?: string;
+};
+type PaddleAPIOptions = APIOptions & {
+    /** The public namespace name, for `/ns/<name>` in `meta.pagination.next` and management URLs. */
+    publicNamespace?: string;
+    /**
+     * The default payment link: a `ready` automatic-collection transaction gets
+     * `checkout.url = <paymentLink>?_ptxn=<id>`. Default none (`checkout.url` is `null`).
+     */
+    paymentLink?: string;
+    /** Called with every event the account produces (the body a webhook would carry). */
+    onEvent?: (event: EventRecord) => void;
+    /**
+     * Seed the fixture account (`seedFixtures`) on construction when the namespace is empty, and
+     * again after every `reset()`. Fixture events are recorded (`GET /events`) but not passed to
+     * `onEvent`: they are the account's pre-existing state, not new activity.
+     */
+    fixtures?: boolean;
+};
+/**
+ * Stateful mock of the Paddle Billing API. Catalog and customer records behave as Paddle's do;
+ * transactions carry computed totals (no tax, no discounts); subscriptions are created when a
+ * transaction with recurring prices is paid, which the admin routes simulate (`payTransaction`,
+ * `checkout`), and renewed or failed on demand (`renewSubscription`, `failPayment`).
+ */
+declare class PaddleAPI implements FetchAPI {
+    readonly app: Hono;
+    readonly sqlite: SqliteClient;
+    readonly state: PaddleState;
+    private readonly service;
+    private readonly now;
+    private readonly publicNamespace;
+    private readonly paymentLink;
+    private readonly onEvent;
+    private readonly fixtures;
+    private readonly requestIds;
+    private requestCounter;
+    /** While seeding fixtures: events are recorded but not published. */
+    private seeding;
+    constructor(options?: PaddleAPIOptions);
+    fetch(request: Request): Promise<Response>;
+    /** Empty the namespace; with `fixtures`, the fixture account is seeded again. */
+    reset(): Promise<void>;
+    /** Every event the account produced, oldest first. */
+    events(): EventRecord[];
+    private requestId;
+    private iso;
+    private prefix;
+    private emit;
+    /** The JSON body, validated against the contract; an absent body is `{}` when allowed. */
+    private body;
+    private includes;
+    private statusFilter;
+    private page;
+    private ok;
+    private mustCustomer;
+    createCustomer(input: {
+        email: string;
+        name?: string | null;
+        custom_data?: CustomData;
+        locale?: string;
+    }): CustomerRecord;
+    private listCustomers;
+    private createCustomerOp;
+    private getCustomer;
+    private updateCustomer;
+    private creditBalances;
+    private authToken;
+    createAddress(customerId: string, input: Partial<Omit<AddressRecord, "id" | "customer_id" | "status" | "created_at" | "updated_at" | "import_meta">> & {
+        country_code: string;
+    }): AddressRecord;
+    private mustAddress;
+    private listAddresses;
+    private createAddressOp;
+    private getAddress;
+    private updateAddress;
+    createBusiness(customerId: string, input: {
+        name: string;
+        company_number?: string | null;
+        tax_identifier?: string | null;
+        contacts?: {
+            name?: string | null;
+            email: string;
+        }[] | null;
+        custom_data?: CustomData;
+    }): BusinessRecord;
+    private mustBusiness;
+    private listBusinesses;
+    private contacts;
+    private createBusinessOp;
+    private getBusiness;
+    private updateBusiness;
+    /** The product record for an input, not yet stored (`commitProduct` stores and announces it). */
+    private buildProduct;
+    private commitProduct;
+    createProduct(input: Parameters<PaddleAPI["buildProduct"]>[0]): ProductRecord;
+    private mustProduct;
+    private renderProduct;
+    private listProducts;
+    private createProductOp;
+    private getProduct;
+    private updateProduct;
+    private timePeriod;
+    /**
+     * The validated price record for an input, not yet stored (`commitPrice` stores and announces
+     * it). `product` is a product that is itself not stored yet (a non-catalog item's product).
+     */
+    private buildPrice;
+    private commitPrice;
+    createPrice(input: Parameters<PaddleAPI["buildPrice"]>[0]): PriceRecord;
+    private mustPrice;
+    private renderPrice;
+    private listPrices;
+    private priceInput;
+    private createPriceOp;
+    private getPrice;
+    private updatePrice;
+    /**
+     * The priced items of a request: catalog prices by `price_id`, or non-catalog `price`
+     * objects, whose `type: custom` price (and product) are only stored once the whole request
+     * has validated: the caller runs `catalog` after its last check (a preview never does).
+     */
+    private resolveItems;
+    private resolveParties;
+    private billingDetails;
+    private period;
+    private countryOf;
+    private lineItems;
+    private checkoutFor;
+    /** Build (or rebuild) a transaction from request fields; shared by create and update. */
+    private transactionFrom;
+    /** Sequential and unique: one more than the invoices issued so far (`MOCK-01001` first). */
+    private nextInvoiceNumber;
+    private transactionEvents;
+    /** `POST /transactions` as a method: what the hosted checkout and the admin routes call. */
+    createTransaction(input: Json, origin?: TransactionOrigin): TransactionRecord;
+    private mustTransaction;
+    private renderTransaction;
+    private dateFilter;
+    private listTransactions;
+    private createTransactionOp;
+    private previewTransaction;
+    private getTransaction;
+    private updateTransaction;
+    private transactionInvoice;
+    private captured;
+    private subscriptionItems;
+    /**
+     * Complete a `ready`, `billed` or `past_due` transaction as if the customer paid: a captured
+     * card payment, `completed` status, an invoice, and, for recurring items, the subscription
+     * (`trialing` when a price has a trial, else `active`) or the recovery of a past-due one.
+     */
+    payTransaction(id: string, card?: CardInput): {
+        transaction: TransactionRecord;
+        subscription: SubscriptionRecord | null;
+    };
+    private mustSubscription;
+    private saveSubscription;
+    private recurringPriced;
+    private applyScheduledChange;
+    /** A completed transaction for a subscription's billing period (renewal, charge, update). */
+    private billSubscription;
+    /**
+     * Run the next billing date: a scheduled cancel or pause takes effect instead, a paused
+     * subscription with a scheduled resume resumes (billed from its `effective_at`); otherwise a
+     * `subscription_recurring` transaction is created (plus any queued one-time charges), the
+     * billing period advances, and a trial ends into `active`.
+     */
+    renewSubscription(id: string): {
+        subscription: SubscriptionRecord;
+        transaction: TransactionRecord | null;
+    };
+    /** The next renewal's payment is declined: a `past_due` transaction and subscription. */
+    failPayment(id: string): {
+        subscription: SubscriptionRecord;
+        transaction: TransactionRecord;
+    };
+    /** A hosted-checkout completion in one call: find or create the customer and address, then pay. */
+    checkout(input: CheckoutInput): {
+        transaction: TransactionRecord;
+        subscription: SubscriptionRecord | null;
+    };
+    private nextTransactionPreview;
+    private renderSubscription;
+    private listSubscriptions;
+    private subscriptionResponse;
+    private getSubscription;
+    private notCanceled;
+    private updateSubscription;
+    private activateSubscription;
+    private pauseSubscription;
+    private resumeSubscription;
+    /**
+     * A paused subscription becomes active for `period`; a period starting now (or one a
+     * scheduled resume set) is billed at once, a continued one is not.
+     */
+    private resumeInto;
+    private cancelSubscription;
+    private chargeSubscription;
+    private listEvents;
+    /**
+     * A small account to start from: a customer with an address and a business, a "Pro" product
+     * with monthly, yearly and one-time prices, a "Starter" price with a 14-day trial, an active
+     * monthly subscription, a trialing one, an unpaid `ready` transaction and a manual invoice.
+     * Deterministic: two instances seeded at the same clock hold identical ids.
+     */
+    seedFixtures(): {
+        customer: CustomerRecord;
+        address: AddressRecord;
+        business: BusinessRecord;
+        product: ProductRecord;
+        prices: {
+            monthly: PriceRecord;
+            yearly: PriceRecord;
+            setup: PriceRecord;
+            starter: PriceRecord;
+        };
+        subscriptions: {
+            active: SubscriptionRecord;
+            trialing: SubscriptionRecord;
+        };
+        transactions: {
+            ready: TransactionRecord;
+            invoice: TransactionRecord;
+        };
+    };
+    private seedAccount;
+}
+
+type PaddleRuntimeOptions = {
+    sqlite?: SqliteClient;
+    clock?: Clock;
+    seed?: number | string;
+    adminKey?: string;
+    onLog?: (entry: RequestLog) => void;
+    /**
+     * Where notifications go, signed with the endpoint's `pdl_ntfset_…` secret in
+     * `Paddle-Signature`. `events` limits the event types (default all).
+     */
+    webhooks?: Omit<WebhookEndpoint, "id"> & {
+        retryDelaysMs?: readonly number[];
+        fetch?: (request: Request) => Promise<Response>;
+    };
+    /** The default payment link `checkout.url` is built from (`<link>?_ptxn=<id>`). */
+    paymentLink?: string;
+    /** Seed every namespace with the fixture account on first use (`seedFixtures`). */
+    fixtures?: boolean;
+};
+type PaddleRuntime = ServiceRuntime<PaddleAPI> & {
+    readonly webhooks: WebhookHub;
+};
+
+/** Port `mockingbird-paddle serve` listens on when none is given. */
+declare const DEFAULT_PORT = 8795;
+type PaddleServerOptions = PaddleRuntimeOptions & {
+    /** Default `0`: the OS picks a free port. */
+    port?: number;
+    /** Default `127.0.0.1`. */
+    host?: string;
+};
+type PaddleServer = Listening & {
+    runtime: PaddleRuntime;
+};
+/**
+ * Serve the Paddle mock over `node:http`. Point the SDK at `url`:
+ * `new Paddle(key, { environment: url as Environment })`.
+ */
+declare const createServer: (options?: PaddleServerOptions) => Promise<PaddleServer>;
+/** How `serve` (and `serve --config`) builds the Paddle mock from flags. */
+declare const serveTarget: ServeTarget;
+
+export { DEFAULT_PORT, createServer, serveTarget };
+export type { PaddleServer, PaddleServerOptions };