palbase 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,148 @@
+import { type AppDatabase, type Binding, type Embed, type Plan, type Pool, type Schema, type SearchWorker, type SqlDriver } from 'palgres';
+import { type SchemaDef } from 'palgres/dsl';
+import type { Schemas, Tables } from './db-env.js';
+/** A connection pool: Bun's SQL and postgres.js both are one. */
+export interface SqlPool extends Pool {
+    unsafe(sql: string, params?: unknown[]): PromiseLike<unknown>;
+    begin<T>(fn: (tx: {
+        unsafe(sql: string, params?: unknown[]): PromiseLike<unknown>;
+    }) => Promise<T>): Promise<T>;
+}
+/**
+ * A database the app reaches: its pool (migrations), the engine's driver over
+ * it — what everything the serving app sends goes through: the version's
+ * lookup, requests, forgetting a user, cancels — and how it closes.
+ */
+export interface DatabaseDriver {
+    pool: SqlPool;
+    engine: SqlDriver;
+    /** The connections the engine's pool holds: what the requests' share and their further transactions' share are cut from. */
+    poolSize: number;
+    close(): Promise<void>;
+}
+export interface DatabaseConfig {
+    /** The app's schemas: each db/*.ts file's defineSchema(…). */
+    schemas: SchemaDef | SchemaDef[];
+    /** The app's database address (default PALBASE_DB_URL). */
+    url?: string;
+    /**
+     * Who a request is to the database: its caller (default) — authenticated
+     * with the token's claims, anon without one — or always the service role,
+     * for an operator's app whose tables are all service_role's (Studio).
+     */
+    requests?: 'caller' | 'service';
+    /**
+     * How a database is opened (default Bun's SQL; on Node give one: postgres.js
+     * with { types: POSTGRES_JS_TYPES }, its engine postgresJsDriver(pool,
+     * control)), saying its pool's size (poolSize):
+     * a third of it is the requests', two thirds their further transactions'.
+     * The default, Bun's, holds what the app may hold (connectionsOf) but the
+     * one it cancels with; one given here holds no more either.
+     */
+    driver?: (url: string) => DatabaseDriver;
+    /**
+     * What embeds for the tables that declare search — a search's query, and
+     * each row's text in the background: texts in, their vectors out, by the
+     * model and in the dimensions the table says. Default: the project's ai
+     * module (a table's model is "default", or a catalogue embedding model as
+     * provider:model), with nothing for the app to write.
+     */
+    embed?: Embed;
+}
+/**
+ * The deploy's steps (start, complete, rollback), and two that change
+ * nothing — `palbase db:plan` and `db:status` ask the app's own Palgres what a
+ * start would do and what the database's ledger says.
+ */
+export type MigrateMode = 'start' | 'complete' | 'rollback' | 'plan' | 'status';
+/** What the deploy asked of this run: a migration step, or nothing (serve). */
+export declare function migrateModeOf(env: Record<string, string | undefined>): MigrateMode | undefined;
+/**
+ * The schemas the app's database holds: the app's, and the framework's own
+ * (its writes' Idempotency-Keys) — migrated with them, in one version.
+ */
+export declare function schemasOf(config: DatabaseConfig): SchemaDef[];
+export declare function modelOf(config: DatabaseConfig): Schema;
+/** Whether a table of the schema declares search: such an app embeds its rows in the background. */
+export declare function searches(model: Schema): boolean;
+/** Whether the schema keeps a user's id anywhere: such an app must hear when a user is deleted. */
+export declare function keepsUsers(model: Schema): boolean;
+/**
+ * How many connections the app may hold to its database. On the platform it
+ * is told (PALBASE_DB_CONNECTIONS) its share of the database's: the copies of
+ * every machine given the database — a new version's beside the one that
+ * serves — hold no more than the database has between them, and one that
+ * held more left the next version's requests waiting for the connections of
+ * the one before (measured 2026-10-07: 31 a copy, 38 in all, 12 s). Told
+ * nothing (a laptop, a server of one's own), 31: ten requests' transactions
+ * at once and the two further ones each may hold ($asService, $atomic —
+ * palgres' admission), and one to cancel with.
+ */
+export declare function connectionsOf(env: Record<string, string | undefined>): number;
+/**
+ * The admission cut from a pool: a third to requests, two thirds to their
+ * further transactions. Cut from the pool's own size — a share larger than
+ * the pool would make a request in its first transaction wait in the driver,
+ * with no deadline, for a connection only a finished request frees.
+ */
+export declare function admissionFor(poolSize: number): {
+    concurrency: number;
+    nestedConcurrency: number;
+};
+/**
+ * How a migration's run ends, which is all the platform reads of it:
+ * 0 — done, or nothing to do; 1 — the migration's own verdict: it is refused,
+ * or what the tables hold does not fit it, and running it again changes
+ * nothing (the deploy stops, and what start began is taken back); 75 — it was
+ * cut off: the database unreachable or restarting, a lock not had in time.
+ * Run again — the platform does — it picks up where it stopped.
+ */
+export type MigrationExit = 0 | 1 | 75;
+/**
+ * The deploy's migration step on an app that declares no database: it has
+ * nothing to migrate, and began nothing a rollback could take back. A start
+ * — or anything else asked of it — is its verdict, said on its last line; a
+ * rollback, of what a start of this app began, has nothing to do. A database
+ * given to such a machine with its migrations on is refused as its release
+ * starts, and the release's rollback then ends — the machine is not held by it.
+ */
+export declare function migrateWithoutDatabase(mode: MigrateMode): MigrationExit;
+/** The deploy's migration step. */
+export declare function runMigration(config: DatabaseConfig, env: Record<string, string | undefined>, mode: MigrateMode): Promise<MigrationExit>;
+export interface OpenDatabase {
+    model: Schema;
+    binding: Binding;
+    /** The engine: one transaction per request, as its caller (or the service role). */
+    app: AppDatabase<Tables, Schemas>;
+    requests: 'caller' | 'service';
+    /** The platform's user.deleted: what the app kept of the user goes. */
+    forget(userId: string): Promise<{
+        deleted: number;
+        detached: number;
+    }>;
+    /** What embeds the rows of the tables that declare search, when the schema has one; not started. */
+    search?: SearchWorker;
+    close(): Promise<void>;
+}
+/**
+ * The app's schema has no version in the database, and the app runs off the
+ * platform — on a developer's computer, where no release is coming to
+ * migrate it: said at once, with what a push would do.
+ */
+export declare class SchemaNotPushed extends Error {
+    readonly digest: string;
+    readonly plan: Plan | undefined;
+    constructor(digest: string, plan: Plan | undefined);
+}
+/** A plan as palbase db:plan says it: from what version to what, each change, each refusal. */
+export declare function planLines(p: Plan): string[];
+/**
+ * The app's connection, bound to its version. On the platform a start may
+ * still be finishing when the first instance boots: the version is waited
+ * for up to a minute. Off it none is coming, and a schema with no version is
+ * the developer's to push (SchemaNotPushed).
+ */
+export declare function openDatabase(config: DatabaseConfig, env: Record<string, string | undefined>, secretKey: string, where: {
+    onPlatform: boolean; /** What embeds when the app names no embedder: the project's ai module. */
+    embed: Embed;
+}): Promise<OpenDatabase>;

package/types/backend/src/db-env.d.ts

@@ -0,0 +1,4 @@
+export interface Tables {
+}
+export interface Schemas {
+}

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

@@ -0,0 +1,293 @@
+import 'reflect-metadata';
+import type { EventType, PalbaseEvent } from '../../server/src/index.js';
+import type { UserT } from './engine.js';
+import type { UploadConfig } from './upload.js';
+/** A validator the framework runs: any Standard Schema (zod, valibot, arktype, …). */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+export type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | {
+            readonly key: PropertyKey;
+        }>;
+    }>;
+};
+export interface AuthConfig {
+    required: boolean;
+    verifiedEmail?: boolean;
+    /** v2 read these from its database; v3 has none yet: refused at boot. */
+    role?: string;
+    permission?: string;
+}
+export type AuthSpec = boolean | Partial<AuthConfig>;
+export interface RateLimitConfig {
+    max: number;
+    /** Seconds. */
+    window: number;
+}
+export interface ControllerOptions {
+    auth?: AuthSpec;
+}
+export interface RouteOptions {
+    auth?: AuthSpec;
+    /** A limit for this route; false for none. */
+    rateLimit?: RateLimitConfig | false;
+}
+export type ParamKind = 'body' | 'query' | 'param' | 'user' | 'optionalUser' | 'headers' | 'req' | 'requestId' | 'client' | 'resolve' | 'uploadedObject';
+export interface ParamMeta {
+    index: number;
+    kind: ParamKind;
+    schema?: StandardSchemaV1;
+    name?: string;
+    /** @Resolve's: the provider that makes the value, and what the decorator passed it. */
+    resolver?: abstract new (...args: never[]) => ParamResolver<unknown, unknown>;
+    options?: unknown;
+}
+export interface RouteMeta {
+    method: string;
+    subpath: string;
+    fn: string;
+    options: RouteOptions;
+    /** @Upload's: the route takes a file, through storage, into this bucket and path. */
+    upload?: UploadConfig;
+}
+export interface ControllerMeta {
+    basePath: string;
+    options: ControllerOptions;
+}
+/** A class as the container knows it, as v2 named the type: `providers: [BillingService as Token]`. */
+export type Token<T = unknown> = abstract new (...args: never[]) => T;
+export interface ModuleDef {
+    imports?: Function[];
+    controllers?: Function[];
+    providers?: Function[];
+    exports?: Function[];
+}
+export declare const CONTROLLER: unique symbol;
+export declare const ROUTES: unique symbol;
+export declare const PARAMS: unique symbol;
+export declare const INJECTABLE: unique symbol;
+export declare const MODULE: unique symbol;
+export declare const EVENTS: unique symbol;
+export declare const WEBHOOK: unique symbol;
+export declare const JOBS: unique symbol;
+export declare function declared(): Set<Function>;
+export declare const RESERVED: Set<string>;
+export declare function Controller(basePath: string, options?: ControllerOptions): ClassDecorator;
+export declare const Get: (subpath: string, options?: RouteOptions) => MethodDecorator;
+export declare const Post: (subpath: string, options?: RouteOptions) => MethodDecorator;
+export declare const Put: (subpath: string, options?: RouteOptions) => MethodDecorator;
+export declare const Patch: (subpath: string, options?: RouteOptions) => MethodDecorator;
+export declare const Delete: (subpath: string, options?: RouteOptions) => MethodDecorator;
+/** The HTTP QUERY method (its input is read with @Body). */
+export declare const Query: (subpath: string, options?: RouteOptions) => MethodDecorator;
+export declare const Body: (schema: StandardSchemaV1) => ParameterDecorator;
+export declare const QueryParams: (schema: StandardSchemaV1) => ParameterDecorator;
+export declare const Headers: (schema?: StandardSchemaV1) => ParameterDecorator;
+export declare const Param: (name: string) => ParameterDecorator;
+export declare const User: () => ParameterDecorator;
+export declare const OptionalUser: () => ParameterDecorator;
+export declare const Req: () => ParameterDecorator;
+export declare const RequestId: () => ParameterDecorator;
+export declare const TraceId: () => ParameterDecorator;
+export declare const Client: () => ParameterDecorator;
+/** What a resolver is given of the request: what the route's own decorators read, before its body is. */
+export interface ResolveContext {
+    /** The path's parameters, decoded: {ref} of /environments/{ref}. */
+    readonly params: Readonly<Record<string, string>>;
+    /** The signed-in user; null on a route that does not need one and was called by nobody. */
+    readonly user: UserT | null;
+    readonly headers: globalThis.Headers;
+    readonly requestId: string;
+}
+/**
+ * A provider that makes a route's parameter from its request — the team, the
+ * environment, the account the path names, with the caller's right to it
+ * checked — for every route that asks with @Resolve. Its refusal (a NotFound,
+ * a Forbidden) is the request's answer, given before the body is read
+ * against its schema.
+ */
+export interface ParamResolver<T = unknown, O = undefined> {
+    resolve(context: ResolveContext, options: O): T | Promise<T>;
+}
+/**
+ * A parameter the app makes: `resolver` (an @Injectable its module lists, and
+ * the controller's module reaches as it would a constructor's dependency)
+ * resolves it, with `options`, in the request's transaction — what it reads
+ * and what the handler then does are one transaction. An app names its own:
+ *
+ *   export const CurrentTeam = (role?: TeamRole) => Resolve(TeamOfRequest, role);
+ *   remove(@CurrentTeam("owner") team: Team, @Param("id") id: string) { … }
+ */
+export declare function Resolve<T, O>(resolver: abstract new (...args: never[]) => ParamResolver<T, O>, ...options: undefined extends O ? [options?: O] : [options: O]): ParameterDecorator;
+export declare function Injectable(): ClassDecorator;
+export declare function Module(def: ModuleDef): ClassDecorator;
+export declare const PLATFORM_EVENT: RegExp;
+/**
+ * What a method under @On(event) may be. For a type the modules' contracts
+ * declare (x-palbase-events: purchases.entitlement.changed, …) it takes
+ * PalbaseEvent's member of that type — its data as the contract says — and
+ * the delivery's meta: a handler that reads another payload is a compile
+ * error. For any other type (user.deleted, a third party's in a @Webhook
+ * class) any method, as before.
+ */
+export type EventHandler<E extends string> = E extends EventType ? (event: Extract<PalbaseEvent, {
+    type: E;
+}>, meta: {
+    requestId: string;
+}) => unknown : (...args: never[]) => unknown;
+export interface OnOptions {
+    /**
+     * A storage event's (file.uploaded, file.deleted, file.moved): the bucket
+     * whose objects it takes — the others' events are not run here, nor sent to
+     * the machine when no handler of their type takes every bucket. Left out,
+     * every bucket's.
+     */
+    bucket?: string;
+}
+/** One @On: the event it takes, its method, and the bucket a storage event's is kept to. */
+export interface EventDeclaration {
+    event: string;
+    fn: string;
+    bucket?: string;
+}
+/** A storage event: of an object, in a bucket — what @On's bucket keeps a handler to. */
+export declare const isFileEvent: (event: string) => boolean;
+/**
+ * A handler of an event. In a @Webhook class it takes one of that sender's
+ * events, by any name the sender gives it (invoice.paid,
+ * pull_request.opened, PING) — "" included, as in v2: the deliveries that
+ * name no type, Twilio's plain incoming message or call, Slack's slash
+ * command. On any other class it takes one of the platform's (user.deleted,
+ * …), and the class is a provider its module lists. A method's decorator
+ * runs before its class's, so which of the two it is — and so whether a
+ * platform event's name is one — is told at boot. Any name is taken; the
+ * types the modules' contracts declare (EventType) are the ones an editor
+ * offers, and each types its handler (EventHandler).
+ */
+export declare function On<E extends EventType | (string & {})>(event: E, options?: OnOptions): <F extends EventHandler<E>>(target: object, key: string | symbol, descriptor: TypedPropertyDescriptor<F>) => void;
+export interface JobOptions {
+    /**
+     * What its runs are kept under (Studio, the CLI) and the platform calls it
+     * by: letters, digits, '.', '_' and '-', at most 64. Renaming it starts a
+     * new job.
+     */
+    name: string;
+    /** Five fields of cron's — minute hour day-of-month month day-of-week — in UTC, like "0 3 * * *". */
+    schedule: string;
+    /** Seconds one run may take before it is a failed attempt: 1–300 (30). */
+    timeout?: number;
+    /** Attempts after a failed one, 10 s, 20 s, … five minutes apart: 0–10 (5). */
+    retry?: number;
+}
+export interface JobDeclaration {
+    name: string;
+    schedule: string;
+    timeout: number;
+    retries: number;
+}
+/** One run of a job, as the platform calls it: what its run(meta) is given. */
+export interface JobMeta {
+    /** The app's environment variables, as it started (its keys left out). */
+    env: Record<string, string>;
+    /** The project the app belongs to (its id). */
+    environmentId: string;
+    job: string;
+    /** The run's id: the same for each attempt of one run — what a job keys its work on to do it once. */
+    runId: string;
+    /** The minute it was due. */
+    scheduledAt: Date;
+    /** 1 for the first, then one more each time a failed attempt is made again. */
+    attempt: number;
+}
+/**
+ * A provider the platform runs on `schedule` — five fields of cron's, in UTC
+ * — by calling its run(meta), on the machine: woken for it if asleep, one of
+ * its copies called, one run of a job at a time. A throw is a failed attempt,
+ * made again; a return is done. It runs in a transaction of its own, as the
+ * service role: no one called it but the app. Off the platform nothing calls
+ * it. Its module lists it in its providers, as any other.
+ */
+export declare function Job(options: JobOptions): ClassDecorator;
+/** The senders whose signing scheme is known by name. */
+export type WebhookProvider = 'stripe' | 'github' | 'twilio' | 'sendgrid' | 'slack' | 'discord' | 'livekit';
+/** A signature scheme spelled out, for a sender with no preset: an HMAC of `signs`, in `header`. */
+export interface SignatureSpec {
+    /** The header carrying the signature. */
+    header: string;
+    /** Stripped before comparison (e.g. `sha256=`); a header without it is refused. */
+    prefix?: string;
+    algo: 'hmac-sha256' | 'hmac-sha1';
+    encoding: 'hex' | 'base64';
+    /** What the HMAC covers: `{body}` (the bytes as they arrived), `{ts}`, and literal text. `{ts}` needs `timestampHeader`, and brings the five-minute replay window — without it a captured delivery verifies whenever it is sent again. */
+    signs: string;
+    timestampHeader?: string;
+}
+export interface WebhookOptions {
+    /** The last segment of its URL, /webhooks/<name>: what the sender is configured with. */
+    name: string;
+    provider?: WebhookProvider;
+    signature?: SignatureSpec;
+    /** The env var holding the signing secret (for Discord and SendGrid, their public key): its name, never its value. */
+    secret: {
+        env: string;
+    };
+}
+export interface WebhookDeclaration extends WebhookOptions {
+    /** Each @On of the class: the event it takes, and its method. */
+    events: {
+        event: string;
+        fn: string;
+    }[];
+}
+/**
+ * A class whose @On methods take a third party's deliveries, POSTed to
+ * /webhooks/<name>: each one verified — with the provider's scheme, or the
+ * signature spelled out — under the secret its env var holds, then handed to
+ * the @On of its event. The class is a provider its module lists, its
+ * constructor injected as a controller's. Every misuse is refused here: a
+ * webhook that verifies nothing, or answers 200 and runs nothing, is not one.
+ *
+ * A handler is idempotent. Senders deliver at least once, and a delivery the
+ * app has run is not run again by its sender's id — but that memory is this
+ * copy's alone and lives in its memory: another copy of the app, or this one
+ * started again, runs it again. And not every delivery can be told from one
+ * sent again by someone else. Stripe, Slack, Discord, LiveKit and SendGrid
+ * sign a time and an id: a captured delivery is refused once five minutes
+ * have passed, and not run twice before. GitHub and Twilio sign neither —
+ * whoever holds one of their deliveries, from a log or a proxy, can send it
+ * again at any time, under a fresh delivery id, and it is run again; what is
+ * told apart is their own retry. A handler of theirs keys its work on the
+ * event's own ids (a MessageSid, a payload's ids), and checks what it decides
+ * on: GitHub's event name is an unsigned header, and Twilio's signature
+ * does not delimit its parameters (webhooks.ts). A signature spelled out
+ * without {ts} is replayed as theirs, and names no id.
+ */
+export declare function Webhook(options: WebhookOptions): ClassDecorator;
+export declare function metaOf<T>(target: Function, key: symbol): T | undefined;
+/** The controller classes this process declared, in the order they were declared — v2's getRegisteredControllers(). */
+export declare function getRegisteredControllers(): readonly Function[];
+/** A route as v2 described one: its method, its path under the controller's, its method's name, its options and an upload's config. */
+export interface RouteInfo {
+    method: string;
+    path: string;
+    fnName: string;
+    options: RouteOptions & {
+        uploadConfig?: UploadConfig;
+    };
+}
+/** A controller's routes, as v2's getRoutes(ctor) listed them. */
+export declare function getRoutes(ctor: Function): RouteInfo[];

package/types/backend/src/engine-db.d.ts

@@ -0,0 +1,24 @@
+import { type DatabaseDiagnosticsOptions, type DBClient, type SqlDriver } from 'palgres';
+import type { SchemaDef } from 'palgres/dsl';
+export type { SqlDriver };
+export interface RequestDatabaseIdentity {
+    /** The database role the caller's work runs as. */
+    role: string;
+    /** The role $asService() runs as. */
+    serviceRole: string;
+    /** The caller's claims, as JSON: what auth.uid() and policies read. */
+    claimsJson: string;
+}
+export interface RequestDatabaseOptions {
+    /** The app's schema files' default exports: what each call is compiled against. */
+    schemas: readonly SchemaDef[];
+    diagnostics?: DatabaseDiagnosticsOptions;
+    signal?: AbortSignal;
+}
+export interface RequestDatabaseHandle {
+    /** The string-keyed client: what withServices({ Database }) takes. */
+    client: DBClient;
+    commit(): Promise<void>;
+    rollback(reason: unknown): Promise<void>;
+}
+export declare function createRequestDatabase(sql: SqlDriver, identity: RequestDatabaseIdentity, options?: RequestDatabaseOptions): RequestDatabaseHandle;

package/types/backend/src/engine-exports.d.ts

@@ -0,0 +1,3 @@
+export { makeMemoryCache, type MemoryCacheOptions } from './cache.js';
+export { createApp, type App, type AppOptions } from './engine.js';
+export { createRequestDatabase, type RequestDatabaseHandle, type RequestDatabaseIdentity, type RequestDatabaseOptions, type SqlDriver } from './engine-db.js';

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

@@ -0,0 +1,124 @@
+import { type PalbaseServer, type TokenUser, type TokenVerifier, type WebhookEvent } from '../../server/src/index.js';
+import { type AuthSpec, type RateLimitConfig } from './decorators.js';
+import { type ContractOptions } from './openapi.js';
+import type { RequestTelemetry } from './requests.js';
+/** The signed-in user, as @User() gives it. */
+export interface UserT {
+    id: string;
+    email: string | null;
+    role: string | null;
+    emailVerified: boolean;
+    metadata: Record<string, unknown>;
+    sessionId: string | null;
+    /** A test user of the project (made with its secret key; the token says test: true). */
+    test: boolean;
+}
+export interface ClientInfo {
+    sdkVersion: string | null;
+    appVersion: string | null;
+    platform: string | null;
+    osVersion: string | null;
+}
+/** Browsers on these origins may call the app (preflight answered, CORS headers sent). */
+export interface CorsOptions {
+    /** Exact origins (https://app.example.com), or "*" for any. */
+    origins: string[] | '*';
+    /** Seconds a browser keeps a preflight's answer (default 600). */
+    maxAge?: number;
+}
+/**
+ * An app's own API tokens (a CI's, an agent's). A bearer that is no JWT and
+ * that accepts takes — told without the database: its shape, and a check of
+ * its own the app can make (a tag only it can sign) — is one of them: resolve
+ * says who it stands for, in a transaction of its own as a delivery's is, or
+ * null. Any other bearer is a Palbase session's, and the app is never asked.
+ */
+export interface AppTokens {
+    accepts(token: string): boolean;
+    resolve(token: string): Promise<TokenUser | null>;
+}
+export interface AppOptions {
+    modules: Function[];
+    verifier: TokenVerifier;
+    server: PalbaseServer;
+    /** Required when a provider handles events (@On). */
+    webhookSecret?: string;
+    /** Where each @Webhook's secret is read (secret: { env }) — process.env unless given — and its handlers' meta.env. */
+    env?: Record<string, string | undefined>;
+    /** The project's id: a @Webhook handler's meta.environmentId. */
+    projectId?: string;
+    /** Each answered request's log line and analytics trace; none when not given. */
+    telemetry?: RequestTelemetry;
+    now?: () => number;
+    maxBodyBytes?: number;
+    /** Every route's auth unless it or its controller says otherwise (default: required). */
+    auth?: AuthSpec;
+    /** The app's own API tokens (a CI's, an agent's): AppTokens. */
+    tokens?: AppTokens;
+    /** Every route's limit unless it says otherwise (default 300 a minute per caller); false for none. */
+    rateLimit?: RateLimitConfig | false;
+    /** Off unless given: a backend called from browsers names their origins. */
+    cors?: CorsOptions;
+    /** The framework's own handlers of the platform's events (user.deleted → forget), run before the app's @On. */
+    events?: Record<string, ((event: WebhookEvent) => Promise<unknown>)[]>;
+    /** The app's database: each request (and each delivery) one transaction, as its caller or as the service role. */
+    database?: {
+        app: RequestDatabases;
+        requests: 'caller' | 'service';
+    };
+    /**
+     * Built to write its contract and nothing else (PALBASE_CONTRACT_OUT): its
+     * webhooks' secrets are not read, and whether it declares a database says
+     * what the contract says of its callers.
+     */
+    contractOnly?: {
+        database: boolean;
+        routes?: ContractOptions['routes'];
+        errors?: ContractOptions['errors'];
+    };
+    /**
+     * The platform's calls to the machine, for the platform alone: each
+     * carries Palbase-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret,
+     * "<t>." + body)>, t at most five minutes from now; every other call is
+     * 401 invalid_signature, its error_description saying which of
+     * missing_signature, malformed_signature, stale_timestamp or
+     * signature_mismatch. The factory gives it the machine's
+     * PALBASE_PLATFORM_SECRET; unset here, none is served (404). They are:
+     * - the app's @Job classes: GET /_palbase/jobs lists them (the platform asks
+     *   once a version is up), POST /_palbase/jobs/<name> runs one — its body
+     *   {job, run_id, scheduled_at, attempt} is what the signature covers —
+     *   and answers 204, or the failure the platform tries again;
+     * - its @Upload routes' two steps, from storage (upload.ts), and its
+     *   @Room classes' joins, messages and moments, from realtime (rooms.ts):
+     *   platform-calls.ts.
+     */
+    platform?: {
+        secret: string;
+    };
+}
+/** What the engine needs of Palgres' AppDatabase: a request's database, and its end. */
+export interface RequestDatabases {
+    request(identity: {
+        role: 'anon' | 'authenticated' | 'service';
+        claims: Record<string, unknown>;
+    }, options?: {
+        signal?: AbortSignal;
+        heldIdle?: (waitedMs: number) => void;
+    }): {
+        database: object;
+        commit(): Promise<void>;
+        rollback(reason: unknown): Promise<void>;
+    };
+}
+export interface App {
+    handle(request: Request, info?: {
+        remoteAddress?: string;
+    }): Promise<Response>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    readonly routes: readonly string[];
+    /** The app's contract (OpenAPI): what its routes answer and throw, as written for its build. */
+    contract(): unknown;
+}
+export declare const MAX_BODY_BYTES: number;
+export declare function createApp(opts: AppOptions): App;

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

@@ -0,0 +1,27 @@
+export interface PalbaseConnection {
+    /** https://<ref>.<domain> — PALBASE_URL. */
+    url?: string;
+    /** The project's id — PALBASE_PROJECT_ID. */
+    projectId?: string;
+    /** The project's secret key — PALBASE_SECRET_KEY, from the project's Secrets. */
+    secretKey?: string;
+    /** The webhook endpoint's secret — PALBASE_WEBHOOK_SECRET; needed on the platform when the app handles events (@On) or keeps users. */
+    webhookSecret?: string;
+    /**
+     * The key the platform signs its own calls to this machine with —
+     * PALBASE_PLATFORM_SECRET, which the platform starts every machine with.
+     * Off the platform there is none, and what only the platform calls (the
+     * app's jobs, /_palbase/jobs) is not served.
+     */
+    platformSecret?: string;
+}
+export interface Connection {
+    url: string;
+    projectId: string;
+    secretKey: string;
+    webhookSecret?: string;
+    platformSecret?: string;
+}
+export declare function connection(given: PalbaseConnection, env: Record<string, string | undefined>, opts: {
+    needsWebhookSecret: boolean;
+}): Connection;