palbase 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,70 @@
+import { HttpError, type FieldError } from 'palgres';
+import type { StandardSchemaV1 } from './decorators.js';
+export { BadRequest, Conflict, DeadlockDetected, HttpError, NotFound, SerializationFailure, TooManyRequests, UniqueViolation } from 'palgres';
+export type FieldIssue = FieldError;
+export declare function isHttpError(e: unknown): e is HttpError;
+/** Any refusal: its status, code and description of the caller's choosing. */
+export declare class PalError extends HttpError {
+    constructor(status: number, code: string, description: string, data?: unknown);
+}
+export declare class Unauthorized extends HttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+export declare class Forbidden extends HttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+export interface Envelope {
+    error: string;
+    error_description: string;
+    status: number;
+    request_id: string;
+    data?: unknown;
+}
+export declare function envelope(e: HttpError, requestId: string): Envelope;
+/** One error a release can throw by its wire code: what the contract types it as. */
+export interface RegisteredError {
+    code: string;
+    status: number;
+    /** The class name the analysis reads at a throw site. */
+    className: string;
+    data?: StandardSchemaV1;
+    builtin: boolean;
+}
+/** The errors of a release that defined none of its own: the named refusals, by code. */
+export declare function createErrorRegistry(): Map<string, RegisteredError>;
+/** The registry defineError writes to, by wire code. */
+export declare function errorRegistry(): Map<string, RegisteredError>;
+/** What a schema takes. */
+type InputOf<S> = S extends {
+    readonly '~standard': {
+        readonly types?: {
+            readonly input: infer I;
+        };
+    };
+} ? I : unknown;
+/** A defined error that carries data: `new RoomLocked({ retryAfter: 30 })`. */
+export interface DefinedErrorWithData<S extends StandardSchemaV1> {
+    new (data: InputOf<S>, message?: string): HttpError;
+    readonly code: string;
+    readonly status: number;
+}
+/** A defined error without data: `new RoomGone()`. */
+export interface DefinedError {
+    new (message?: string): HttpError;
+    readonly code: string;
+    readonly status: number;
+}
+/**
+ * A project's own error, as v2 defined one: its wire code, its status and,
+ * when it carries data, the data's schema — what every generated client
+ * types it as (`catch .roomLocked(let data)`). Called at a module's top level
+ * with literals: the build reads them where it is thrown.
+ *
+ *   export const RoomLocked = defineError("room_locked", 409, z.object({ retryAfter: z.number() }));
+ *   throw new RoomLocked({ retryAfter: 30 });
+ *
+ * A code is the project's once: defined again with another status or data, it
+ * is refused (a client matches an error by its code).
+ */
+export declare function defineError<S extends StandardSchemaV1>(code: string, status: number, data: S): DefinedErrorWithData<S>;
+export declare function defineError(code: string, status: number): DefinedError;

package/types/backend/src/i18n.d.ts

@@ -0,0 +1,21 @@
+/** The app's strings: its source language, its languages, and each key's cell per language. */
+export interface StringsTable {
+    version: 1;
+    source: string;
+    locales: string[];
+    strings: Record<string, Record<string, {
+        value: string;
+        state: 'translated' | 'needs_review' | 'missing';
+    }>>;
+}
+/** The languages a request asks for, best first — each tag and then its base language — and the source last. */
+export declare function chainFromAcceptLanguage(header: string | null, source: string | undefined): string[];
+/** The key's text in the first language of the chain that has it — the key itself in the source language. */
+export declare function lookup(table: StringsTable, key: string, chain: readonly string[]): {
+    text: string;
+    locale: string;
+};
+/** {{name}} filled from vars ({{{name}}} left as it is); a value not given is empty. */
+export declare function interpolate(text: string, vars?: Record<string, unknown>): string;
+/** The sentence `key` (written in the source language) in the caller's language, {{name}} filled. */
+export declare function t(key: string, vars?: Record<string, string | number | boolean | null | undefined>): string;

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

@@ -0,0 +1,23 @@
+import 'reflect-metadata';
+export { Body, Client, Controller, Delete, Get, getRegisteredControllers, getRoutes, Headers, Injectable, Job, Module, On, OptionalUser, Param, Patch, Post, Put, Query, QueryParams, Req, RequestId, Resolve, TraceId, User, Webhook, type AuthConfig, type AuthSpec, type ControllerOptions, type EventHandler, type JobMeta, type JobOptions, type ModuleDef, type OnOptions, type ParamResolver, type RateLimitConfig, type ResolveContext, type RouteInfo, type RouteOptions, type SignatureSpec, type StandardSchemaV1, type Token, type WebhookOptions, type WebhookProvider, } from './decorators.js';
+export { Upload, UploadedObject, type UploadConfig } from './upload.js';
+export { OnAuthorize, OnEmpty, OnFirst, OnJoin, OnLeave, OnMessage, Room, type RoomAuthorizeContext, type RoomContext, type RoomGrant, type RoomMessageContext, type RoomOptions, type RoomUser, } from './rooms.js';
+export { getWebhookManifest, type WebhookEventHandler, type WebhookMeta } from './webhooks.js';
+export { DiError, type DiErrorKind } from './container.js';
+export { BadRequest, Conflict, DeadlockDetected, Forbidden, HttpError, NotFound, PalError, SerializationFailure, TooManyRequests, Unauthorized, UniqueViolation, defineError, type DefinedError, type DefinedErrorWithData, type Envelope, type FieldIssue, } from './errors.js';
+export { createApp, MAX_BODY_BYTES, type App, type AppOptions, type AppTokens, type ClientInfo, type CorsOptions, type UserT } from './engine.js';
+export { ContractRunEnded, MigrationRunEnded, PalbaseFactory, type AppConfig, type PalbaseApplication } from './bootstrap.js';
+export { SchemaNotPushed } from './database.js';
+export type { DatabaseConfig } from './database.js';
+export { bigint, boolean, check, date, defineSchema, defineTable, enumType, foreignKey, index, integer, jsonb, numeric, ownedByUser, policy, raw, sqlType, text, timestamp, userRef, uuid, type AnyColumn, type ColumnMap, type PolicyExprCtx, type SchemaDef, type TableDef, type TableHandle, type TableRef, } from 'palgres/dsl';
+export type { Embed, TablesOf } from 'palgres';
+export { increment, now } from 'palgres';
+export type { WhereFilter } from 'palgres';
+export type { PalbaseConnection } from './env.js';
+export { Database, Log, Palbase, type AtomicDatabase, type Logger } from './runtime.js';
+export { Flags, Notifications, Realtime, Secrets, Storage, type EnvBuckets, type PalbaseBatchOverrideOperation, type PalbaseBatchSetOverridesResult, type PalbaseBucketClient, type StorageService, type PalbaseClearAllOverridesResult, type PalbaseClearOverrideResult, type PalbaseEmailSendParams, type PalbaseEmailSendResponse, type PalbaseFileObject, type PalbaseFlag, type PalbaseFlagContext, type PalbaseFlagSource, type PalbaseFlagValue, type PalbaseFlagVariant, type PalbaseFlagsServiceClient, type PalbaseListOptions, type PalbaseLocalizedText, type PalbasePushRecipient, type PalbasePushSendParams, type PalbasePushSendResponse, type PalbaseResult, type PalbaseSetOverrideResult, type PalbaseSetOverridesResult, type PalbaseSignedUrlResponse, type PalbaseUploadOptions, type TypedBucketClient, } from './services.js';
+export { Cache, CACHE_MAX_TTL, type CacheClient } from './cache.js';
+export { t, type StringsTable } from './i18n.js';
+export { AuthUnavailable, TokenError, TokenVerifier, type SessionStanding, type TokenRefusal, type TokenUser } from '../../server/src/index.js';
+export { EVENT_TYPES, PalbaseError, type EventType, type PalbaseEvent, type PlatformEvent, type PlatformEvents, type WebhookEvent } from '../../server/src/index.js';
+export { z } from 'zod';

package/types/backend/src/openapi.d.ts

@@ -0,0 +1,73 @@
+import type { RateLimitConfig, StandardSchemaV1 } from './decorators.js';
+import type { RegisteredError } from './errors.js';
+import type { RoomDeclaration } from './rooms.js';
+import type { Route } from './router.js';
+/** Where the platform delivers the project's events to the app. */
+export declare const PLATFORM_EVENTS_PATH = "/webhooks/palbase";
+/** What the engine decided for a route: the document says what it enforces. */
+export interface RouteFacts {
+    auth: {
+        required: boolean;
+        verifiedEmail: boolean;
+    };
+    /** The limit the route spends, or false when it has none. */
+    limit: RateLimitConfig | false;
+}
+export interface ContractOptions {
+    /** The app's database runs each request as its caller's identity (or keeps its claims). */
+    databaseSeesCaller: boolean;
+    /** The app has a database: its writes take an Idempotency-Key. */
+    idempotency?: boolean;
+    /** The app's @Webhook classes, as the engine serves them. */
+    webhooks?: readonly WebhookFacts[];
+    /** The project's events the app takes at POST /webhooks/palbase: its @On types, and user.deleted when its tables keep users. */
+    platformEvents?: readonly string[];
+    /** The buckets whose storage events (file.*) those handlers take; undefined when one of them takes every bucket's. */
+    platformEventBuckets?: readonly string[];
+    /**
+     * What the app's source says a route answers and throws — read from its
+     * types when its contract is written (contract/analyze.ts) — or undefined
+     * for a route it says nothing of: that route answers JSON of no schema.
+     */
+    routes?: (route: Route) => RouteContract | undefined;
+    /** The release's errors by wire code (defineError's registry): what a thrown code is typed as. */
+    errors?: ReadonlyMap<string, RegisteredError>;
+    /** The app's @Room classes, as their decorators declare them. */
+    rooms?: readonly RoomDeclaration[];
+}
+/** What a route answers and throws, as its source declares. */
+export interface RouteContract {
+    /** void: it answers nothing (204); raw: the Response its handler built; otherwise the schema of its JSON answer, or of each item of it. */
+    returns: {
+        kind: 'void';
+    } | {
+        kind: 'raw';
+    } | {
+        kind: 'json';
+        schema: StandardSchemaV1;
+        array: boolean;
+    };
+    /** Every error the route can throw, in the order it is first thrown. */
+    throws: readonly ThrownError[];
+}
+/** One error a route throws: the name every client gives its case, its wire code and status. */
+export interface ThrownError {
+    name: string;
+    code: string;
+    status: number;
+}
+/** A @Webhook as the engine serves it: POST /webhooks/<name>. */
+export interface WebhookFacts {
+    name: string;
+    /** The class declaring it. */
+    cls: string;
+    provider?: string;
+    /** The header a signature spelled out arrives in. */
+    signatureHeader?: string;
+    /** The env var its secret is read from. */
+    secretEnv: string;
+    events: string[];
+}
+type Json = Record<string, unknown>;
+export declare function openapiDocument(table: readonly Route[], factsOf: (route: Route) => RouteFacts, opts: ContractOptions): Json;
+export {};

package/types/backend/src/platform-calls.d.ts

@@ -0,0 +1,41 @@
+export declare const UPLOAD_AUTHORIZE_PATH = "/_palbase/storage/upload/authorize";
+export declare const UPLOAD_COMPLETE_PATH = "/_palbase/storage/upload/complete";
+export declare const ROOMS_PATH = "/_palbase/realtime/rooms";
+/**
+ * The most a platform's call carries: the machines module refuses to send
+ * more (an upload's completion — its client's body and the object — is the
+ * largest).
+ */
+export declare const PLATFORM_CALL_MAX: number;
+/** The caller, as the module that checked its token names it. */
+export interface SignedUser {
+    /** The user's id; absent when nobody is signed in. */
+    id?: string;
+    session?: string;
+    /** anon, authenticated, or service_role for a call made with the project's secret key. */
+    role: string;
+    /** The user's email and whether it is verified, as auth said when it checked the token; absent when it said none. */
+    email?: string;
+    emailVerified?: boolean;
+}
+/** The `user` of a call, or undefined when it is not one. */
+export declare function signedUserOf(v: unknown): SignedUser | undefined;
+/** The caller's address as the edge saw it, which the module names beside the user ("client"), or undefined. */
+export declare function clientOf(v: unknown): string | undefined;
+/**
+ * Who a platform's call is counted against, for a route's limit: the caller
+ * the module names in the signed call — the user, the session of one signed
+ * in to no one, or else the address the edge saw it come from (client) — as a
+ * request's own is counted by its user or its address. Never the
+ * connection's address, which is the platform's and every caller's alike,
+ * nor a header, which is anyone's to send. Named by none of them, the callers
+ * of one role share the route's limit: a limit each could step around by
+ * saying something of itself is none.
+ */
+export declare function limitKeyOf(user: SignedUser, client?: string): string;
+/**
+ * The claims the request's database is told for a signed-in caller — what
+ * auth.uid() reads (sub), its role and session — or null for nobody: what a
+ * token's claims would say of the same user, of what the call names.
+ */
+export declare function claimsOf(user: SignedUser | undefined): Record<string, unknown> | null;

package/types/backend/src/requests.d.ts

@@ -0,0 +1,81 @@
+export interface AnsweredRequest {
+    requestId: string;
+    method: string;
+    /** The route's path as declared ("/orgs/{id}", without its method), or the path when no route took it. */
+    endpoint: string;
+    /** The path as asked. */
+    path: string;
+    status: number;
+    durationMs: number;
+    /** The signed-in caller, when there was one. */
+    userId?: string;
+}
+/** Where traces go: analytics' batch of request traces, as the project's server. */
+export interface TraceSink {
+    sendTraceBatch(input: {
+        body: {
+            traces: TraceBody[];
+        };
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+export interface TraceBody {
+    request_id: string;
+    source: 'backend';
+    endpoint: string;
+    method: string;
+    status: number;
+    duration_ms: number;
+    timestamp: number;
+    distinct_id?: string;
+}
+export interface RequestTelemetryOptions {
+    /** Lines a second the request log writes before it counts instead (the machine's log keeps 1200 a minute). */
+    linesPerSecond?: number;
+    /** Traces sent in one batch (analytics takes 100). */
+    batchSize?: number;
+    /** How long a trace waits for its batch to fill. */
+    flushMs?: number;
+    /** Traces held while analytics does not take them; past this the oldest go. */
+    maxPending?: number;
+    /** How long one batch's call may take, its retries included (default 10 000 ms); past it, the call is let go and its traces dropped. */
+    sendMs?: number;
+    /** How long a flush waits for analytics in all (default 2000 ms); past it, what is not sent is dropped, and said. */
+    shutdownMs?: number;
+    now?: () => number;
+}
+export declare class RequestTelemetry {
+    private readonly linesPerSecond;
+    private readonly batchSize;
+    private readonly flushMs;
+    private readonly maxPending;
+    private readonly sendMs;
+    private readonly shutdownMs;
+    private readonly now;
+    private tokens;
+    private refilled;
+    private unlogged;
+    private unloggedSince;
+    private pending;
+    private timer;
+    private sending;
+    private inFlight;
+    private pausedUntil;
+    private lastSendWarning;
+    private readonly sink;
+    constructor(sink: TraceSink | undefined, opts?: RequestTelemetryOptions);
+    record(r: AnsweredRequest): void;
+    /**
+     * Sends what is held, and waits for it — the app's shutdown, a test — for
+     * shutdownMs at most. When that is up, the call analytics has not answered
+     * is let go and what is still held is dropped, said once with how many: a
+     * connection hung on the way would otherwise hold the process until it is
+     * killed, and the database's close with it.
+     */
+    flush(): Promise<void>;
+    private letGo;
+    private log;
+    private trace;
+    private schedule;
+    private send;
+}

package/types/backend/src/rooms.d.ts

@@ -0,0 +1,168 @@
+import type { realtime } from '../../internal/src/modules/index.js';
+import { type StandardSchemaV1 } from './decorators.js';
+import { type SignedUser } from './platform-calls.js';
+export declare const ROOM: unique symbol;
+export declare const ROOM_HOOKS: unique symbol;
+/** The moments a room's methods are told of. */
+export type RoomHook = 'authorize' | 'first' | 'join' | 'leave' | 'empty';
+export interface RoomOptions {
+    /**
+     * What the room sends its members, by event name, each its payload's
+     * schema: the room's public surface, typed in every generated client. A
+     * room emits from anywhere in its class, so there is no return type to read
+     * them from — they are declared.
+     */
+    events: Record<string, StandardSchemaV1>;
+    /**
+     * How long the room is held after its last member left before it is empty
+     * (@OnEmpty), in milliseconds: 60000 unless said. Raise it for an upstream
+     * that is expensive to start again; one who comes back within it finds the
+     * room as it was.
+     */
+    graceMs?: number;
+}
+/** A room as its decorators declare it. */
+export interface RoomDeclaration {
+    pattern: string;
+    events: Record<string, StandardSchemaV1>;
+    graceMs: number;
+    /** Each moment, the method told of it. */
+    hooks: Partial<Record<RoomHook, string>>;
+    /** Each message a member may send: its method, and its payload's schema — an object of no prototype, whatever the names. */
+    messages: Record<string, {
+        fn: string;
+        schema: StandardSchemaV1;
+    }>;
+}
+/** Who a member is, to a room's methods. */
+export interface RoomUser {
+    /** The user's id; "" in @OnFirst and @OnEmpty, which no one in particular caused. */
+    id: string;
+}
+/** What @OnAuthorize is given: who asks to join, and the channel's parameters. */
+export interface RoomAuthorizeContext {
+    user: RoomUser;
+    params: Readonly<Record<string, string>>;
+}
+/**
+ * What @OnAuthorize answers: true lets the user in to hear and to send; an
+ * object says which — { read: false } is no way in (admitted to hear nothing
+ * is not admitted), { write: false } a listener who may not send; null,
+ * undefined or false keep the user out. A room with no @OnAuthorize lets
+ * nobody in, and one whose @OnAuthorize throws lets that user in nowhere.
+ * So does any other answer — a number, a string, an object that says
+ * neither read nor write ({} too): only a grant lets anyone in, and the
+ * app's log says what was answered instead.
+ */
+export type RoomGrant = boolean | null | undefined | {
+    read?: boolean;
+    write?: boolean;
+};
+/** What a room's moments are given (@OnFirst, @OnJoin, @OnLeave, @OnEmpty). */
+export interface RoomContext {
+    /** The channel: "ai:42". */
+    room: string;
+    /** The pattern's parameters: { sessionId: "42" }. */
+    params: Readonly<Record<string, string>>;
+    /**
+     * The room's own: aborted when it empties (before @OnEmpty runs), or when
+     * owner.release() gives it up — what @OnFirst started stops on it.
+     */
+    signal: AbortSignal;
+    /** Its members now, across realtime's replicas; 0 in @OnMessage. */
+    count: number;
+    user: RoomUser;
+    /**
+     * An event to the room's members — in @OnJoin, to the member who joined
+     * alone. Sent in the order emitted, and never thrown: realtime is lossy,
+     * and what could not be sent is in the app's log.
+     */
+    emit(event: string, payload?: unknown): void;
+    owner: {
+        /** Runs `work` past the method, until the room's signal aborts: an upstream's loop. Its failure is logged, never the app's crash. */
+        hold(work: (signal: AbortSignal) => unknown): void;
+        /** Gives the room up now: its signal aborts, and the next member to come finds it unheld (@OnFirst again). */
+        release(): void;
+    };
+}
+/** What @OnMessage is given: the room's context, the member, and the payload as its schema made it. */
+export interface RoomMessageContext<P = unknown> extends RoomContext {
+    payload: P;
+}
+/**
+ * A class whose methods manage the room `pattern` names. It is a provider a
+ * module lists (its constructor injected as any provider's), built once: what
+ * @OnFirst starts and @OnEmpty stops lives in it.
+ *
+ *   @Room('ai:{sessionId}', { events: { token: Token } })
+ *   class AiRoom {
+ *     @OnAuthorize() can({ user, params }: RoomAuthorizeContext): RoomGrant { … }
+ *     @OnFirst() open(ctx: RoomContext) { ctx.owner.hold((signal) => this.stream(ctx, signal)); }
+ *     @OnEmpty() close(ctx: RoomContext) { … }
+ *     @OnMessage('say', Say) say(ctx: RoomMessageContext<Say>) { … }
+ *   }
+ */
+export declare function Room(pattern: string, options: RoomOptions): ClassDecorator;
+/** Who may join: answers a RoomGrant (RoomAuthorizeContext). No @OnAuthorize, and nobody joins. */
+export declare const OnAuthorize: () => MethodDecorator;
+/**
+ * The room is occupied and held by no one: start what it needs. Told once
+ * across realtime's replicas when its first member comes — before that
+ * member is answered — and again only after it emptied.
+ */
+export declare const OnFirst: () => MethodDecorator;
+/** A member joined (after it was answered): what it emits goes to that member alone. */
+export declare const OnJoin: () => MethodDecorator;
+/** A member left. */
+export declare const OnLeave: () => MethodDecorator;
+/** Nobody has been in the room for its graceMs: stop what @OnFirst started. Its signal is aborted already. */
+export declare const OnEmpty: () => MethodDecorator;
+/**
+ * A message a member sends, `name`, its payload checked against `schema`
+ * before the method runs (RoomMessageContext): a payload that does not fit
+ * never reaches it, and the member hears why.
+ */
+export declare function OnMessage(name: string, schema: StandardSchemaV1): MethodDecorator;
+/** The room a class declares, or undefined: a room is one by its decorator, never its name. */
+export declare function roomOf(cls: Function): RoomDeclaration | undefined;
+/** A room's channel's parameters, or undefined when the channel is not one of its. */
+export declare function matchRoom(pattern: string, channel: string): Record<string, string> | undefined;
+/** One event to a room's members, as realtime's broadcast takes it: its channel (topic), and conn_id for one membership alone. */
+type RoomBroadcast = realtime.BroadcastMessage;
+export interface RoomDeps {
+    /**
+     * `work` as the platform's caller names it — in a transaction as `user`,
+     * or as the app itself when the moment is no one's (first, empty) —
+     * committed unless it throws, or the platform hung up before it ended.
+     */
+    run<T>(user: SignedUser | undefined, where: string, signal: AbortSignal | undefined, work: () => Promise<T>): Promise<T>;
+    /** realtime's POST /realtime/broadcast, as the app (its secret key). */
+    broadcast(messages: RoomBroadcast[]): Promise<unknown>;
+    /** The platform's infrastructure, not the method, failed: the call is answered 503, and realtime asks again. */
+    isOutage(e: unknown): boolean;
+}
+/** What a room's call is answered: JSON, nothing (204), or a refusal. */
+export type RoomAnswer = {
+    status: 200;
+    body: unknown;
+} | {
+    status: 204;
+} | {
+    status: number;
+    code: string;
+    message: string;
+    retryAfter?: number;
+};
+export interface Rooms {
+    readonly declarations: readonly RoomDeclaration[];
+    /** The platform's call about a room — authorize, message or lifecycle — its JSON body. */
+    serve(kind: string, body: unknown, signal?: AbortSignal): Promise<RoomAnswer>;
+    /** Every room let go: what was held is aborted (the app is stopping). */
+    close(): void;
+}
+/** The app's rooms, served: `classes` its providers that are rooms, each with its instance. */
+export declare function createRooms(classes: {
+    cls: Function;
+    instance: object;
+}[], deps: RoomDeps): Rooms;
+export {};

package/types/backend/src/router.d.ts

@@ -0,0 +1,22 @@
+import { type AuthSpec, type ParamMeta, type RouteMeta } from './decorators.js';
+export interface Route {
+    /** "<METHOD> <path as declared>": the rate limit's key and the logs' name. */
+    id: string;
+    method: string;
+    segments: ({
+        param: string;
+    } | string)[];
+    controller: Function;
+    fn: string;
+    params: ParamMeta[];
+    meta: RouteMeta;
+    controllerAuth: AuthSpec | undefined;
+}
+export declare function routeTable(controllers: Function[]): Route[];
+export type Match = {
+    route: Route;
+    params: Record<string, string>;
+} | {
+    malformed: true;
+} | null;
+export declare function match(table: Route[], method: string, pathname: string): Match;

package/types/backend/src/runtime.d.ts

@@ -0,0 +1,56 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { PalbaseServer } from '../../server/src/index.js';
+import type { AtomicDatabase as AtomicOf, EnvTypedDatabase } from 'palgres';
+import type { Schemas, Tables } from './db-env.js';
+export interface RequestScope {
+    requestId: string;
+    /** The request's database: its transaction, as its caller. Set when the app has one. */
+    database?: object;
+    /** The signed-in user it serves (a room's member), once known: Flags are read for them. */
+    userId?: string;
+    /** A test's stand-ins for the platform's services (withServices): each one read here first. */
+    services?: Readonly<Record<string, object | undefined>>;
+    /** The app's strings, and the languages this request is answered in, best first: what t() reads. */
+    strings?: import('./i18n.js').StringsTable;
+    locales?: readonly string[];
+    /** The languages t() answered in, for the response's Content-Language. */
+    usedLocales?: string[];
+}
+/**
+ * A service whose calls go to the stand-in a test gave for it (withServices),
+ * and to `impl` everywhere else.
+ */
+export declare function scoped<T extends object>(name: string, impl: T): T;
+/**
+ * The service a call goes to: a test's stand-in for it, or `impl`. In a
+ * test's scope a service it gave no stand-in for is refused by name, as
+ * v2's was — its real calls would reach a platform no test serves. Log is
+ * the exception: a line written is the test's to read or not.
+ */
+export declare function serviceOf<T extends object>(name: string, key: PropertyKey, impl: T): T;
+export declare const requestScope: AsyncLocalStorage<RequestScope>;
+/** The project's modules: auth, storage, notify, secrets, flags, analytics, realtime, machines. */
+export declare const Palbase: PalbaseServer;
+/**
+ * The request's database, as v2's: `Database.public.<table>`, `$query`,
+ * `$transaction`, `$atomic`, `$asService()`. It is the request's own
+ * transaction — committed when the handler returns, rolled back when it
+ * throws — so it is reached inside a request (a handler, a service it calls,
+ * an @On), never at import or from a timer.
+ */
+export declare const Database: EnvTypedDatabase<Tables, Schemas>;
+/** One `Database.$atomic()` transaction's handle over the app's tables: the type of its callback's `tx`, as v2 named it. */
+export type AtomicDatabase = AtomicOf<Tables, Schemas>;
+/** A logger's shape, as v2 named it: Log is one, and so is what a test hands in its place. */
+export interface Logger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+export declare const Log: {
+    debug: (message: string, fields?: Record<string, unknown>) => void;
+    info: (message: string, fields?: Record<string, unknown>) => void;
+    warn: (message: string, fields?: Record<string, unknown>) => void;
+    error: (message: string, fields?: Record<string, unknown>) => void;
+};