palbase 0.6.2 → 0.7.0

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

@@ -1,178 +0,0 @@
-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;
-}
-/** 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
- * @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/web/src/ai.d.ts

@@ -1,224 +0,0 @@
-import { type AgentEvent, type ToolEvent, type TurnEvent, type VoiceEvent } from '../../internal/src/chat.js';
-import { ai as aiModule } from '../../internal/src/modules/index.js';
-import { type ToolResult } from '../../internal/src/tool-output.js';
-import { type Transport } from '../../internal/src/transport.js';
-import type { SessionManager } from './session.js';
-export type Chat = aiModule.Chat;
-export type { AgentEvent, ChatEvent, ToolEvent, TurnEvent, VoiceEvent } from '../../internal/src/chat.js';
-export type { ToolResult } from '../../internal/src/tool-output.js';
-/** A member's message as this client holds it: one it sent is here at once, pending until the agent has it. */
-export interface ChatMessageView {
-    /** The writer's id for it: the same id is the same message. */
-    clientId: string;
-    /** The module's id; null until it answered. */
-    id: string | null;
-    text: string;
-    /** The member who wrote it; null: the project's server (or, for one this client sent, not yet answered — mine says it is the user's). */
-    author: string | null;
-    authorName: string;
-    delivery: string;
-    /** pending until the agent has it, delivered once it does, failed when it could not be given (or sent). */
-    status: 'pending' | 'delivered' | 'failed';
-    /** Why it failed: the module's code. */
-    error: string | null;
-    /** The turn it started or reached. */
-    responseId: string | null;
-    createdAt: string;
-    /** Sent from this client. */
-    mine: boolean;
-}
-/** A piece of an answer, in order: its text, split where a tool was called or a subagent handed work. */
-export type ChatPart = {
-    type: 'text';
-    text: string;
-} | {
-    type: 'tool';
-    tool: ToolEvent;
-} | {
-    type: 'agent';
-    agent: AgentEvent;
-};
-/** One answer of the agent's (or of one of its subagents). */
-export interface ChatResponse {
-    id: string;
-    status: TurnEvent['status'] | null;
-    waiting: TurnEvent['waiting'];
-    error: TurnEvent['error'];
-    /** The whole answer so far. */
-    text: string;
-    parts: ChatPart[];
-    /** A subagent's: its run, its name, and the response that handed it the work. */
-    runId: string | null;
-    agent: string | null;
-    parentId: string | null;
-    /** The member whose turn it is (a subagent's: its turn's); null: the project's server's, or the engine's. */
-    startedBy: string | null;
-    /** The signed-in user's own turn: theirs alone to answer its client tools and decide its approvals. */
-    mine: boolean;
-    /** The chat has had one member all its life, as its turn last said (null until it did): only then does this app answer its client tools by itself. */
-    solo: boolean | null;
-}
-export type ChatItem = {
-    type: 'message';
-    message: ChatMessageView;
-} | {
-    type: 'response';
-    response: ChatResponse;
-};
-export interface ChatState {
-    /** idle until the chat is first used; live while its stream is open; failed when the stream was refused (error says why). */
-    status: 'idle' | 'connecting' | 'live' | 'failed' | 'closed';
-    error: unknown;
-    /** The conversation in order: the members' messages and the agent's answers (a subagent's is in its parent's parts). */
-    items: ChatItem[];
-    messages: ChatMessageView[];
-    /** Every answer, the subagents' too, as they began. */
-    responses: ChatResponse[];
-    /** The last turn's state. */
-    turn: TurnEvent | null;
-    /**
-     * What waits for this user: tool calls of their own turns waiting for
-     * their yes (approve/deny), and client tool calls of their own turns
-     * waiting for their app's answer. Another member's turn is theirs to
-     * decide — its calls are in its parts, not here.
-     */
-    waiting: {
-        approvals: ToolEvent[];
-        outputs: ToolEvent[];
-    };
-    /** The chat's live voice as it went: what was said either way, in order, and when it began, ended or handed a task over. */
-    voice: VoiceEvent[];
-}
-/**
- * A chat's live voice this app started (startVoice): its id, its peer connection, and stop. What the voice is
- * told besides what it hears is the app's server's to say (the server SDK), never a member's.
- */
-export interface ChatVoice {
-    readonly id: string;
-    readonly peer: RTCPeerConnection;
-    /** Ends the voice; how long it lasted, in seconds. */
-    stop(): Promise<number>;
-}
-export interface ChatOptions {
-    /** The journal id to follow from (default 0: the chat from its start). */
-    after?: number;
-    /** How long a stream that keeps being cut is followed again before the chat fails (default 2 minutes). */
-    resumeFor?: number;
-}
-/** A client tool's answer, by the tool's name: what it returns is shown to the agent; a throw is the tool's failure. */
-export type ClientToolHandlers = Record<string, (input: unknown, call: ToolEvent) => ToolResult | Promise<ToolResult>>;
-/** One chat, followed: its state, its changes, and what the user does in it. */
-export declare class ChatSession implements AsyncIterable<ChatState> {
-    readonly id: string;
-    private readonly api;
-    private readonly session;
-    private readonly options;
-    private status;
-    private error;
-    private readonly messages;
-    private readonly responses;
-    private readonly order;
-    private turn;
-    private readonly calls;
-    private readonly voiceParts;
-    private readonly handlers;
-    private readonly answering;
-    private readonly listeners;
-    private following;
-    /** Where the stream is: a chat followed again (after a failure) goes on from there, not from its start. */
-    private position;
-    private snapshot;
-    private told;
-    constructor(api: ReturnType<typeof aiModule.client>, id: string, options?: ChatOptions, session?: SessionManager);
-    /** The chat as this client holds it now: the same object until it changes. */
-    get state(): ChatState;
-    /** Told the state each time it changes (at most once a microtask); returns the unsubscribe. The chat is followed from now on. */
-    subscribe(listener: (state: ChatState) => void): () => void;
-    /** The state now, then each time it changes; a break leaves the chat followed (close() ends it). */
-    [Symbol.asyncIterator](): AsyncGenerator<ChatState, void, undefined>;
-    /**
-     * Writes to the chat: the message is in the state at once, pending, and
-     * delivered when the agent has it (the stream says so); failed when it
-     * could not be sent — the promise rejects with why (429
-     * too_many_messages, 409 history_full). The same clientId again (a
-     * failed message sent again) is the same message.
-     */
-    send(text: string, options?: {
-        delivery?: 'next' | 'now';
-        clientId?: string;
-    }): Promise<ChatMessageView>;
-    /**
-     * The client tools this app answers by itself, by name: a call of one of
-     * them that waits for its output (a tool part, awaiting_output) is
-     * answered with what the function returns — in a turn the signed-in user
-     * started, of a chat that is theirs alone (solo). In a chat with other
-     * members a message of theirs may have asked for it (a location, a
-     * photo), and they see the answer: the call stays in waiting.outputs for
-     * the app to ask its user and answer (answer()). A call in another
-     * member's turn is theirs: it never runs on this device (the module
-     * refuses another's answer, 403 not_your_turn). Returns the function that
-     * takes them back.
-     */
-    tools(handlers: ClientToolHandlers): () => void;
-    /**
-     * Answers a client tool's call of the user's own turn (a tool part's
-     * call_id, awaiting_output) — what tools() does by itself in a chat that is
-     * theirs alone, and the app does here when it is not, once its user said
-     * yes. True when this answer is the one; false when the call was answered
-     * already or waits no more.
-     */
-    answer(callId: string, output: ToolResult, options?: {
-        isError?: boolean;
-    }): Promise<boolean>;
-    /** A call that waits for a person's yes (a tool part's approval_id): made. */
-    approve(approvalId: string, reason?: string): Promise<void>;
-    /** Not made: the agent is told, with the reason, and goes on. */
-    deny(approvalId: string, reason?: string): Promise<void>;
-    /** Stops the turn the agent is working on: what it wrote stays. Its response's id, or null when none ran. */
-    stop(): Promise<string | null>;
-    /**
-     * Starts the chat's live voice from the microphone's stream: the voice's
-     * audio plays in audio (a new element unless given), and what is said
-     * either way comes into the state's voice parts. One voice a chat at a time.
-     */
-    startVoice(options: {
-        stream: MediaStream;
-        voice?: string;
-        audio?: HTMLAudioElement;
-    }): Promise<ChatVoice>;
-    /** A message for one of the agent's subagents at work (an agent part's run_id), at its next step. */
-    sendToSubagent(runId: string, text: string): Promise<void>;
-    /** Stops following the chat. */
-    close(): void;
-    private follow;
-    private take;
-    private heard;
-    private response;
-    private autoAnswer;
-    /** The signed-in user started this response's turn (its turn event said so). */
-    private mine;
-    private changed;
-    private build;
-}
-/** The project's agents for the signed-in user. */
-export declare class AI {
-    /** Every client operation of the ai contract, through the session's transport. */
-    readonly api: ReturnType<typeof aiModule.client>;
-    private readonly session;
-    /** The chats the user is in: started with a named agent the project opened to its users (as its owner), listed, read, deleted (an owner's). */
-    readonly chats: {
-        /** A chat with a named agent (clients: true), the user its owner under `name`. A user's chat carries no metadata: that is the server's to write. */
-        create(chat: {
-            agent: string;
-            name?: string;
-            title?: string;
-        }): Promise<Chat>;
-        /** The chats the user is in, the newest first (100 at most). */
-        list(): Promise<Chat[]>;
-        get(id: string): Promise<Chat>;
-        delete(id: string): Promise<void>;
-    };
-    constructor(transport: Transport, session?: SessionManager);
-    /** A chat the user is in, to follow and write to. */
-    chat(chatId: string, options?: ChatOptions): ChatSession;
-}

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

@@ -1,61 +0,0 @@
-import type { RealtimeSocket } from './socket.js';
-/** One event of a room, as a generated module's union has it. */
-export type RoomEvent = {
-    event: string;
-    payload: unknown;
-};
-/**
- * A room, as the generator writes one. `send` and `event` carry types alone —
- * their values are never read: `room.send('say', { … })` is checked against
- * the message's shape, and a handler's event against the room's events.
- */
-export interface RoomDescriptor<E extends RoomEvent, S, P extends readonly string[] = readonly string[]> {
-    /** The channel pattern the backend declared: `ai:{sessionId}`. */
-    pattern: string;
-    /** The `{param}` names, in the pattern's order: a join takes exactly these. */
-    params: P;
-    /** The declared event names: what a handle listens to. */
-    events: readonly string[];
-    /** The declared message names: what a handle sends. */
-    messages: readonly string[];
-    send: S;
-    event: E;
-}
-/** What `on` returns: called, it stops that callback (`off` does the same). */
-export type RoomSubscription = () => void;
-/** A live room. Hold it for as long as the view is on screen, and `leave` it when the view goes: an occupied room is one its backend is still running for. */
-export interface RoomHandle<E extends RoomEvent, S> {
-    /** The channel this handle is on: `ai:42`. */
-    readonly topic: string;
-    /** Every event the room declares, as a union to switch over. */
-    on(handler: (event: E) => void): RoomSubscription;
-    /** One event by its name, its payload typed. */
-    on<K extends E['event']>(event: K, handler: (payload: Extract<E, {
-        event: K;
-    }>['payload']) => void): RoomSubscription;
-    /** Stops one callback. */
-    off(subscription: RoomSubscription): void;
-    /**
-     * Sends one declared message and waits for the room's backend to take it;
-     * rejects with a RoomError — its reason — when it did not.
-     */
-    send<K extends keyof S & string>(message: K, payload: S[K]): Promise<void>;
-    /** Drops every callback of this handle and lets go of the room; the channel is left with its last handle. */
-    leave(): void;
-}
-/**
- * Why a room did not do what was asked. `reason` is the server's: for a join,
- * `unauthorized` (the backend did not let the user in) or `unavailable` (it
- * could not be asked: try again); for a message, the reason the backend gave,
- * `forbidden` when it gave none or the user may only listen, `rate_limited`,
- * `unavailable`. When no answer came it is `no reply` or `socket closed` —
- * the message may have been taken — and `not joined` when nothing was sent:
- * the handle left, its socket closed (a sign-out, another user's sign-in), or
- * the socket dropped and is being opened again.
- */
-export declare class RoomError extends Error {
-    readonly reason: string;
-    constructor(message: string, reason: string);
-}
-/** Joins `room` on `socket`: resolves once the backend let the user in, rejects with a RoomError when it did not. */
-export declare function joinRoom<E extends RoomEvent, S, P extends readonly string[]>(socket: RealtimeSocket, room: RoomDescriptor<E, S, P>, params: Record<P[number], string>): Promise<RoomHandle<E, S>>;