palbase 0.4.0 → 0.5.1

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

@@ -83,7 +83,8 @@ 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 const CRONS: unique symbol;
+export declare const TASKS: unique symbol;
 export declare function declared(): Set<Function>;
 export declare const RESERVED: Set<string>;
 export declare function Controller(basePath: string, options?: ControllerOptions): ClassDecorator;
@@ -179,49 +180,63 @@ export declare const isFileEvent: (event: string) => boolean;
  * 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 {
+export interface CronOptions {
     /**
      * 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.
+     * new cron.
      */
     name: string;
-    /** Five fields of cron's — minute hour day-of-month month day-of-week — in UTC, like "0 3 * * *". */
+    /** Five fields of cron's — minute hour day-of-month month day-of-week — like "0 3 * * *", on the clocks of timeZone. */
     schedule: string;
-    /** Seconds one run may take before it is a failed attempt: 1–300 (30). */
+    /**
+     * The time zone whose clocks the schedule is on, by its IANA name
+     * ("Europe/Istanbul", "America/New_York"): UTC when none. Where its clocks
+     * change, a time they skip is not run, and a time they show twice is run
+     * the first time only.
+     */
+    timeZone?: string;
+    /** Seconds one run may take before it is a failed attempt: 1–900 (30). */
     timeout?: number;
     /** Attempts after a failed one, 10 s, 20 s, … five minutes apart: 0–10 (5). */
     retry?: number;
 }
-export interface JobDeclaration {
+export interface CronDeclaration {
     name: string;
     schedule: string;
+    timeZone: string;
     timeout: number;
     retries: number;
 }
-/** One run of a job, as the platform calls it: what its run(meta) is given. */
-export interface JobMeta {
+/** One run of a cron, as the platform calls it: what its run(meta) is given. */
+export interface CronMeta {
     /** 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. */
+    /** The cron's name. */
+    cron: string;
+    /** The run's id: the same for each attempt of one run — what a cron keys its work on to do it once. */
     runId: string;
-    /** The minute it was due. */
+    /** The minute it was due (or was asked to run now). */
     scheduledAt: Date;
     /** 1 for the first, then one more each time a failed attempt is made again. */
     attempt: number;
 }
+export declare const PLATFORM_NAME: RegExp;
+/** Why a time zone is not one the platform reads its clocks of, or undefined when it is. */
+export declare function zoneProblem(zone: string): string | undefined;
 /**
- * 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
+ * A provider the platform runs on `schedule` — five fields of cron's, on the
+ * clocks of its time zone (UTC unless it names one) — by calling its
+ * run(meta), on the machine: woken for it if asleep, one of its copies
+ * called, one run of a cron 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.
+ * it. Its module lists it in its providers, as any other. Studio and the CLI
+ * pause it, resume it and run it now.
  */
-export declare function Job(options: JobOptions): ClassDecorator;
+export declare function Cron(options: CronOptions): 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`. */

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

@@ -1,6 +1,7 @@
 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 ChannelsDef } from './channels.js';
 import { type StringsTable } from './i18n.js';
 import type { RequestTelemetry } from './requests.js';
 /** The signed-in user, as @User() gives it. */
@@ -62,6 +63,8 @@ export interface AppOptions {
     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 channels; the ones defineChannels declared in this process unless given (a test's own). */
+    channels?: ChannelsDef;
     /** The app's database: each request (and each delivery) one transaction, as its caller or as the service role. */
     database?: {
         app: RequestDatabases;
@@ -91,10 +94,15 @@ export interface AppOptions {
      * 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;
+     * - the app's @Cron classes: GET /_palbase/crons lists them (the platform
+     *   asks once a version is up), POST /_palbase/crons/<name> runs one — its
+     *   body {cron, run_id, scheduled_at, attempt} is what the signature covers
+     *   — and answers 204, or the failure the platform tries again;
+     * - its @Task classes: GET /_palbase/tasks lists them (asked with the
+     *   crons), POST /_palbase/tasks/<name> runs one attempt of a task — {task,
+     *   id, attempt, payload, created_at} — and answers 204, 422 for a task
+     *   never to be done (TaskFailure, or a payload its schema refuses), 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;

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

@@ -11,7 +11,7 @@ export interface PalbaseConnection {
      * 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.
+     * app's crons and tasks, /_palbase/crons and /_palbase/tasks) is not served.
      */
     platformSecret?: string;
 }

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

@@ -1,5 +1,7 @@
 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 { Body, Client, Controller, Delete, Get, getRegisteredControllers, getRoutes, Headers, Cron, Injectable, Module, On, OptionalUser, Param, Patch, Post, Put, Query, QueryParams, Req, RequestId, Resolve, TraceId, User, Webhook, type AuthConfig, type AuthSpec, type ControllerOptions, type EventHandler, type CronMeta, type CronOptions, 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 { Task, TaskFailure, Tasks, type EnqueueOptions, type PayloadOf, type QueuedTask, type TaskClass, type TaskMeta, type TaskOptions, type TasksService } from './tasks.js';
+export { defineChannels, ownerOnly, publicChannel, type ChannelAuthorizeCtx, type ChannelEntry, type ChannelGrant, type ChannelsDef, type ChannelsInput } from './channels.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';
@@ -9,7 +11,7 @@ export { createApp, MAX_BODY_BYTES, type App, type AppOptions, type AppTokens, t
 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 { bigint, boolean, check, date, defineSchema, defineTable, enumType, foreignKey, index, integer, jsonb, numeric, ownedByUser, policy, raw, sqlType, text, timestamp, userRef, uuid, type AnyColumn, type ColumnKey, type ColumnMap, type PolicyExprCtx, type SchemaDef, type TableDef, type TableHandle, type TableKeys, type TableRef, } from 'palgres/dsl';
 export type { Embed, TablesOf } from 'palgres';
 export { increment, now } from 'palgres';
 export type { WhereFilter } from 'palgres';

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

@@ -1,5 +1,6 @@
 import type { RateLimitConfig, StandardSchemaV1 } from './decorators.js';
 import type { RegisteredError } from './errors.js';
+import type { ChannelRow } from './channels.js';
 import type { RoomDeclaration } from './rooms.js';
 import type { Route } from './router.js';
 /** Where the platform delivers the project's events to the app. */
@@ -34,6 +35,8 @@ export interface ContractOptions {
     errors?: ReadonlyMap<string, RegisteredError>;
     /** The app's @Room classes, as their decorators declare them. */
     rooms?: readonly RoomDeclaration[];
+    /** The owner and public channels defineChannels declares, in its order: x-palbase-channels, decided by realtime itself. */
+    channels?: readonly ChannelRow[];
 }
 /** What a route answers and throws, as its source declares. */
 export interface RouteContract {

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

@@ -89,6 +89,16 @@ export interface RoomContext {
 export interface RoomMessageContext<P = unknown> extends RoomContext {
     payload: P;
 }
+/** v2 held a room a minute after its last member: twice the slowest client's heartbeat, and margin. */
+export declare const DEFAULT_GRACE_MS = 60000;
+/**
+ * Why `pattern` is no room's, or undefined. A pattern is a channel's: ':'
+ * segments, a "{name}" segment taking exactly one — and realtime takes a
+ * pattern it cannot decide for no room at all, silently: the room would
+ * compile, ship and never be joined. So everything it would not take is
+ * refused here, by name, while someone is looking.
+ */
+export declare function patternProblem(pattern: string): string | undefined;
 /**
  * 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

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

@@ -0,0 +1,168 @@
+import { type StandardSchemaV1 } from './decorators.js';
+export interface TaskOptions {
+    /**
+     * The task's type: what its tasks are put on the queue under, kept under
+     * (Studio, the CLI) and called by — letters, digits, '.', '_' and '-', at
+     * most 64.
+     */
+    name: string;
+    /** Seconds one attempt may take before it is a failed one: 1–900 (60). */
+    timeout?: number;
+    /** Attempts after a failed one, 10 s, 20 s, … an hour apart at most: 0–20 (5). */
+    retry?: number;
+    /** How many of its tasks the machine runs at once, however many copies it has: 1–50 (5). */
+    concurrency?: number;
+    /**
+     * What a task carries, checked before run() is called: a task that does
+     * not hold to it can never be done, and fails at once — it is not tried
+     * again. run() is given what the schema gives.
+     */
+    payload?: StandardSchemaV1;
+}
+export interface TaskDeclaration {
+    name: string;
+    timeout: number;
+    retries: number;
+    concurrency: number;
+    payload?: StandardSchemaV1;
+}
+/** One attempt of a task, as the platform calls it: what its run(payload, meta) is given beside what it carries. */
+export interface TaskMeta {
+    /** 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;
+    /** The task's type. */
+    task: string;
+    /** The task's id: the same for each of its attempts — what it keys its work on to do it once. */
+    id: string;
+    /** 1 for the first, then one more each time a failed attempt is made again. */
+    attempt: number;
+    /** When it was put on the queue. */
+    createdAt: Date;
+}
+/**
+ * Thrown by a task's run(): the task can never be done — what it carries is
+ * not what it needs, the thing it works on is gone — and fails now, not to
+ * be tried again. Any other throw is an attempt that failed, made again.
+ */
+export declare class TaskFailure extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A provider whose run(payload, meta) does tasks of its type: put on the
+ * queue with Tasks.enqueue(TheClass, payload), each run once its time
+ * comes — on the platform, which wakes the machine for it; off it, in this
+ * process. A return is done; a throw an attempt that failed, made again
+ * later (a TaskFailure: failed for good). It runs in a transaction of its
+ * own, as the service role: no one called it but the app. Its module lists
+ * it in its providers, as any other.
+ */
+export declare function Task(options: TaskOptions): ClassDecorator;
+/** A @Task class: its constructor takes what it was written to take, its run() a payload and the meta. */
+export type TaskClass = abstract new (...args: never[]) => {
+    run(payload: never, meta: TaskMeta): unknown;
+};
+/** What a @Task class's run() takes as its payload. */
+export type PayloadOf<C> = C extends abstract new (...args: never[]) => {
+    run(payload: infer P, ...rest: never[]): unknown;
+} ? P : never;
+export interface EnqueueOptions {
+    /** Due this many seconds from now (30 days at most). */
+    delay?: number;
+    /** Due at this time (30 days from now at most; a time past is now). */
+    runAt?: Date;
+    /**
+     * Put once under this key: another task of its type under the same key,
+     * while the first is held — until a day after it is over — is not put,
+     * and the first is answered (duplicate: true).
+     */
+    key?: string;
+}
+/** A task on the queue, as it was put. */
+export interface QueuedTask {
+    id: string;
+    task: string;
+    state: 'waiting' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+    attempt: number;
+    /** When it is due (RFC 3339): JSON as it is, so a handler can answer with the task. */
+    runAt: string;
+    key?: string;
+    reason?: string;
+    /** Put already under its key: this is that task, and nothing new was put. */
+    duplicate: boolean;
+}
+/** The queue the app puts its tasks on: the platform's, or its own off the platform. */
+export interface TaskQueue {
+    enqueue(task: string, payload: unknown, options: EnqueueOptions & {
+        machine?: string;
+    }): Promise<QueuedTask>;
+    cancel(id: string, machine?: string): Promise<QueuedTask>;
+    get(id: string, machine?: string): Promise<QueuedTask>;
+}
+export interface TasksService {
+    /**
+     * Put a task of this @Task class on the machine's queue, carrying payload
+     * — what its run() takes, checked as it is written.
+     */
+    enqueue<C extends TaskClass>(task: C, payload: PayloadOf<C>, options?: EnqueueOptions): Promise<QueuedTask>;
+    /** Put a task of a type by its name — of another of the project's machines, with machine. */
+    enqueue(task: string, payload?: unknown, options?: EnqueueOptions & {
+        machine?: string;
+    }): Promise<QueuedTask>;
+    /** Take a task that is waiting off the queue: it is not run. */
+    cancel(id: string, options?: {
+        machine?: string;
+    }): Promise<QueuedTask>;
+    /** A task on the queue, as it is now. */
+    get(id: string, options?: {
+        machine?: string;
+    }): Promise<QueuedTask>;
+}
+/** The machine's task queue. */
+export declare const Tasks: TasksService;
+/** The platform's queue of the machine this app runs on (PALBASE_MACHINE), or of another of the project's. */
+export declare function platformQueue(machine: string | undefined): TaskQueue;
+/** How the app does one attempt of a task: what the platform's call would answer. */
+export type RunTask = (call: {
+    task: string;
+    id: string;
+    attempt: number;
+    payload: unknown;
+    createdAt: Date;
+}, signal: AbortSignal) => Promise<{
+    status: number;
+    message?: string;
+}>;
+/**
+ * The app's own queue, off the platform: its tasks run in this process, as
+ * the platform would run them — when due, each type no more at once than its
+ * concurrency, an attempt that failed made again later, a key held a day
+ * after its task is over. Nothing of it outlives the process.
+ */
+export declare class LocalQueue implements TaskQueue {
+    private readonly types;
+    private readonly run;
+    private readonly now;
+    private readonly tasks;
+    private readonly running;
+    private readonly idle;
+    constructor(types: ReadonlyMap<string, TaskDeclaration>, run: RunTask, now?: () => number);
+    enqueue(task: string, payload: unknown, o: EnqueueOptions & {
+        machine?: string;
+    }): Promise<QueuedTask>;
+    cancel(id: string): Promise<QueuedTask>;
+    get(id: string): Promise<QueuedTask>;
+    /** Resolves once no task is waiting to run now, nor running: what a test waits for after putting one. */
+    settled(): Promise<void>;
+    private quiet;
+    private known;
+    private view;
+    private schedule;
+    private pump;
+    private attempt;
+    private finish;
+    private wake;
+}

package/types/internal/src/chat.d.ts

@@ -88,7 +88,23 @@ export interface AgentEvent {
     reason?: string;
     [field: string]: unknown;
 }
-export type ChatEvent = MessageEvent | TurnEvent | TextEvent | ResetEvent | ToolEvent | AgentEvent;
+/** The chat's live voice: what was said either way (transcript), when it began and ended, and a task it handed over. */
+export interface VoiceEvent {
+    type: 'voice';
+    seq: number;
+    voice_session_id: string;
+    kind: 'transcript' | 'started' | 'closed' | 'delegated';
+    /** A transcript's: the member speaking (user) or the voice answering (assistant). */
+    role?: 'user' | 'assistant';
+    text?: string;
+    /** A delegated task's: answer it with the voice's speak and this id. */
+    delegation_id?: string;
+    task?: string;
+    reason?: string;
+    seconds?: number;
+    [field: string]: unknown;
+}
+export type ChatEvent = MessageEvent | TurnEvent | TextEvent | ResetEvent | ToolEvent | AgentEvent | VoiceEvent;
 /** Where a reader is: what it hands the stream to go on from there. */
 export interface ChatPosition {
     /** The id of the last journal event held. */