palbase 0.6.2 → 0.8.0

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

@@ -0,0 +1,329 @@
+import { type AgentEvent, type ChatEvent, type GoalEvent, type ToolEvent, type TurnEnd, type TurnEvent, type VoiceEvent } from '../../internal/src/chat.js';
+import { type Transport } from '../../internal/src/transport.js';
+export type { AgentEvent, ChatEvent, GoalEvent, HistoryEvent, HistoryItem, Publication, ThinkingEvent, ToolEvent, TranscriptEvent, TurnEnd, TurnEvent, VoiceEvent } from '../../internal/src/chat.js';
+/** A picture or a file a message carries: an image the model was shown, or a file put in the chat's workspace. */
+export interface ChatAttachment {
+    kind: 'image' | 'file' | (string & {});
+    /** What the message calls it: a file's name in the workspace. */
+    name: string;
+    contentType: string;
+    size: number;
+    /** Its bytes' sha256, hex. */
+    sha256: string;
+    /** Its place among the message's attachments (its images, then its files): what its bytes are read by. */
+    position: number;
+    /** Where it was copied from in the project's storage. */
+    bucket: string;
+    path: string;
+    /** A file's place in the chat's workspace (.palbase/attachments/<message id>/<name>); null for a picture. */
+    workspacePath: string | null;
+}
+/** A member's (or the server's) message, as the agent got it. */
+export interface ChatMessageView {
+    /** The writer's id for it: the same id is the same message. */
+    clientId: string;
+    id: string | null;
+    text: string;
+    /** The member who wrote it; null: the project's server. */
+    author: string | null;
+    authorName: string;
+    delivery: string;
+    /** pending until the agent has it, delivered once it does, failed when it could not be given. */
+    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;
+    /** The signed-in user wrote it. */
+    mine: boolean;
+    /** Its writer's labels for it ({} for none): what an app draws it by. */
+    metadata: Record<string, string>;
+    /** It is of what a fork began with: the chat it was forked from had it. */
+    history: boolean;
+    /** Its text is the first of a longer one (a fork's history part carries no more): the fork's model read it whole. */
+    truncated: boolean;
+    /** text: written to the chat; voice: a line said out loud in its voice — the person's (author, the member) or the voice's (author null). */
+    kind: 'text' | 'voice' | (string & {});
+    /** A line of kind voice: the voice it was said in, and by whom (user: the person; assistant: the voice). */
+    voice: {
+        id: string;
+        role: 'user' | 'assistant' | (string & {});
+    } | null;
+    /** Its pictures and files, its images first ([] for none). */
+    attachments: ChatAttachment[];
+}
+/** One model step's reasoning, as the agent showed it (thinking: visible): its windows as they came, together. */
+export interface ChatThinking {
+    /** The model step it is of; null when the part named none. */
+    stepId: string | null;
+    runId: string;
+    text: string;
+    /**
+     * The agent shows its reasoning and the turn's provider would not give it: why there is none (text ''), said
+     * once, where it would have been — the model, and the provider's word (null otherwise).
+     */
+    unavailable: boolean;
+    model: string | null;
+    reason: string | null;
+}
+/** A piece of an answer, in order: its text, split where a tool was called, a subagent handed work, or a step's reasoning began. */
+export type ChatPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool';
+    tool: ToolEvent;
+} | {
+    type: 'agent';
+    agent: AgentEvent;
+} | {
+    type: 'thinking';
+    thinking: ChatThinking;
+};
+/** One answer of the agent's (or of one of its subagents). */
+export interface ChatResponse {
+    id: string;
+    status: TurnEvent['status'] | null;
+    waiting: TurnEvent['waiting'];
+    /** How its turn ended, in the chat's words — completed, failed, stopped, budget_exceeded; null while it has not (or a subagent's). */
+    end: TurnEnd | (string & {}) | null;
+    /** Why, when it did not complete and was not stopped: its code, its words, whether asking again may go otherwise. */
+    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. */
+    mine: boolean;
+    /** The model's reasoning, step by step, when the agent shows it — also in parts, where each step's began. */
+    thinking: ChatThinking[];
+    /** A turn the chat's goal opened (a subagent's: its turn's): the goal, the turn's role and its number. */
+    goal: {
+        goalId: string;
+        role: string;
+        seq: number;
+    } | null;
+    /** It is of what a fork began with: the agent's answer in the chat it was forked from. */
+    history: boolean;
+    /** Its text is the first of a longer one (a fork's history part carries no more). */
+    truncated: boolean;
+}
+/** One tool call of the chat, its whole answer — the stream shows its end (its last 16 KiB) — its secret shapes masked. */
+export interface ChatToolCall {
+    callId: string;
+    name: string;
+    status: string;
+    runId: string;
+    responseId: string;
+    /** What the agent called it with; null when its arguments, masked, are no JSON. */
+    input: unknown;
+    /** Its answer's text, whole; null: none yet. */
+    output: string | null;
+    outputBytes: number;
+    imageCount: number;
+    isError: boolean;
+}
+/** One part of a chat's stream as a page of its past holds it (palbase/ai's chats.parts, or the module's own page). */
+export interface ChatStreamPart {
+    type: string;
+    id?: number;
+    data: Record<string, unknown>;
+}
+/** A page of a chat's past, the oldest it holds first; nextCursor reads the page before it (none: the chat's start is in this one). */
+export interface ChatPartsPage {
+    parts: ChatStreamPart[];
+    nextCursor?: string;
+}
+/**
+ * Which page of a chat's past is read: before a part (before: its journal's sequence — the oldest the channel gave),
+ * where a page's nextCursor left off (cursor), or from the chat's newest end (neither).
+ */
+export interface ChatPartsQuery {
+    before?: number;
+    cursor?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+/** How a chat reads its past past the day its channel keeps: the module, with the member's own session — or the app's own way. */
+export interface ChatHistoryReader {
+    parts(chatId: string, query: ChatPartsQuery): Promise<ChatPartsPage>;
+}
+/** The chat's goal as its words told it: set, changed, its status, and each word in order. */
+export interface ChatGoal {
+    id: string;
+    objective: string;
+    rubric: string;
+    /** active, paused, blocked, budget_limited, achieved — or cleared. */
+    status: string;
+    /** Why it last left active, as a stable code (empty while active). */
+    stopCode: string;
+    stopReason: string;
+    /** What its next turn is, as it was last said: work, or verify. */
+    phase: string;
+    maxTurns: number | null;
+    maxCostUsd: number | null;
+    /** Its words as they came: set, changed, each turn begun, judged and checked, its status, cleared. */
+    events: GoalEvent[];
+}
+/** The chat's voice as its parts told it: whose it is, what becomes of what is asked of it, live or ended — and why. */
+export interface ChatVoice {
+    id: string;
+    /** Its member; null: the server's own. */
+    userId: string | null;
+    /** The signed-in user's own. */
+    mine: boolean;
+    delegation: VoiceEvent['delegation'];
+    status: 'started' | 'closed' | (string & {});
+    /** On closed: how long it lasted, and why it ended ('' while live). */
+    seconds: number | null;
+    closeReason: string;
+}
+/**
+ * One thing of the conversation, in order: a message (a line said in the chat's voice too: kind voice), an answer, a
+ * word of the chat's goal, or the chat's voice beginning or ending.
+ */
+export type ChatItem = {
+    type: 'message';
+    message: ChatMessageView;
+} | {
+    type: 'response';
+    response: ChatResponse;
+} | {
+    type: 'goal';
+    goal: GoalEvent;
+} | {
+    type: 'voice';
+    voice: VoiceEvent;
+};
+export interface ChatState {
+    /** 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 the signed-in user: the tool calls of their own turns
+     * waiting for their yes, and the client tool calls of their own turns
+     * waiting for their app's answer — each said back through the gateway's
+     * own messages, its backend deciding. Another member's turn is theirs.
+     */
+    waiting: {
+        approvals: ToolEvent[];
+        outputs: ToolEvent[];
+    };
+    /** The chat's goal, once one was set in it; null: none. */
+    goal: ChatGoal | null;
+    /** A fork's: the chat it was forked from, and the message it was cut before; null for a chat of its own. */
+    forkedFrom: {
+        chatId: string;
+        beforeMessage: string;
+    } | null;
+    /** The chat's voice — the last that began in it, live or ended; null: none yet. */
+    voice: ChatVoice | null;
+}
+/** A gateway's chat: its state now, and told each time it changes. */
+export interface GatewayChat extends AsyncIterable<ChatState> {
+    /** The chat as the channel holds it now: the same object until it changes. */
+    readonly state: ChatState;
+    /** Told each time the state changes (at most once a microtask); returns the unsubscribe. */
+    subscribe(listener: (state: ChatState) => void): () => void;
+    /** More of the chat's past is there to read with loadOlder (true until a page reaches the chat's start). */
+    readonly hasOlder: boolean;
+    /**
+     * Reads the page of the chat's past before what it holds — the channel keeps a day — and folds it in: the first
+     * page is the one before the oldest part the channel gave (before: its sequence; none: the chat's newest end),
+     * each after it the page its last named. With the member's own session (the project lets its app's users reach
+     * their chats: ai.settings clients) unless load gives the page another way — the app's backend asking palbase/ai's
+     * chats.parts. Resolves with hasOlder. The chat's id is the join's chatId, or its messages' (chatId gives it).
+     */
+    loadOlder(options?: {
+        limit?: number;
+        chatId?: string;
+        load?: (query: ChatPartsQuery) => Promise<ChatPartsPage>;
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+}
+/**
+ * A chat folded from its channel's parts. It holds no connection: a part is
+ * handed to take() as the channel gives it — once, in order — and the state
+ * is built from them; me is the signed-in user, read as the state is built.
+ */
+export declare class ChatLog implements GatewayChat {
+    private readonly me;
+    private readonly reader;
+    private readonly messages;
+    private readonly responses;
+    private readonly order;
+    private turn;
+    private goal;
+    /** The goal's words taken, by their sequence. */
+    private readonly goalWords;
+    /** The voices' starts and ends taken, each once by its voice: an end is told under no sequence (vclosed:<voice>). */
+    private readonly voiceWords;
+    /** The chat's voice: the last that began in it, live or ended. */
+    private voice;
+    /** A fork's history, by its part's place: whenever a part comes, what it holds goes before the rest of the chat. */
+    private readonly history;
+    private forkedFrom;
+    private readonly calls;
+    /**
+     * Every part the channel gave, in order, and the pages of the past read before them (loadOlder), the oldest first:
+     * a page read is folded by folding them all again, the past first — a part both told (the channel's day and the
+     * page's newest end meet) is then the channel's, as it came after.
+     */
+    private readonly taken;
+    private older;
+    /** The oldest part the channel gave, by its journal's sequence: the first page of the past is read before it. */
+    private oldestLive;
+    private olderCursor;
+    private olderLeft;
+    private loading;
+    private chatId;
+    private readonly listeners;
+    /** The iterations waiting for a change: woken when the gateway is left. */
+    private readonly enders;
+    private snapshot;
+    private told;
+    private ended;
+    constructor(me?: () => string | undefined, reader?: ChatHistoryReader, chatId?: string);
+    get hasOlder(): boolean;
+    loadOlder(options?: Parameters<GatewayChat['loadOlder']>[0]): Promise<boolean>;
+    private readOlder;
+    private idFor;
+    private refold;
+    get state(): ChatState;
+    subscribe(listener: (state: ChatState) => void): () => void;
+    /** The state now, then each time it changes, until the gateway is left. */
+    [Symbol.asyncIterator](): AsyncGenerator<ChatState, void, undefined>;
+    /** The gateway was left: an iteration ends, and no part is taken any more. */
+    end(): void;
+    /** One payload of the channel's "chat" event; one that is no part this runtime reads is let be. */
+    takePayload(payload: unknown): void;
+    take(e: ChatEvent): void;
+    private fold;
+    private goalSaid;
+    private heard;
+    private said;
+    private place;
+    private response;
+    private changed;
+    private build;
+}
+/**
+ * A chat's member's reads of it beyond its channel, with their own session — the ai module's calls written here, so
+ * a browser's bundle carries nothing more of the module. The project lets its app's users reach their chats
+ * (ai.settings clients), or the module refuses them (403 clients_disabled).
+ */
+export interface ChatReads extends ChatHistoryReader {
+    toolCall(chatId: string, callId: string, signal?: AbortSignal): Promise<ChatToolCall>;
+    workspaceFile(chatId: string, path: string, manifest?: string, signal?: AbortSignal): Promise<Blob>;
+}
+export declare function chatReader(transport: Transport): ChatReads;

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

@@ -5,7 +5,7 @@ import { type RefreshMode, type SessionStore } from './session.js';
 import { RealtimeSocket } from './socket.js';
 import { Analytics, type AnalyticsOptions } from './analytics.js';
 import { Purchases } from './purchases.js';
-import { AI } from './ai.js';
+import { type ChatToolCall } from './chat.js';
 export interface ClientOptions {
     /** The project's address: https://<ref>.<domain> */
     url: string;
@@ -46,6 +46,14 @@ export interface ClientOptions {
      * which app asks, it does not prove it. Its id, not its slug: a UUID.
      */
     appId?: string;
+    /**
+     * The language the app shows itself in, said with every request as
+     * Accept-Language — a tag ("tr", "pt-BR"), or tags in order of preference
+     * — what auth's emails and pages, a flag's and a paywall's rules and a
+     * backend's translations read. Without it the browser says its own.
+     * pb.setLanguage changes it.
+     */
+    language?: string | readonly string[];
 }
 /**
  * The app's client. A backend's generated Palbe module (palbase apps:sync)
@@ -63,7 +71,24 @@ export interface PalbaseClient {
     analytics: Analytics;
     /** What the signed-in customer has (live, onCustomerInfo), the paywall's catalog, and buying on the web. */
     purchases: Purchases;
-    /** The project's agents, for the signed-in user (when the project lets its users talk to them): their chats, followed as typed parts. */
-    ai: AI;
+    /** The language every request says from now on (ClientOptions.language); null for the browser's own. */
+    setLanguage(language: string | readonly string[] | null): void;
+    /**
+     * One tool call of a chat the signed-in user is a member of, its whole answer — the one a tool part names
+     * (call_id): the chat's channel shows a call's answer by its end (omittedBytes what it left out). Read with their
+     * own session (the project lets its app's users reach their chats: ai.settings clients); another chat's call is
+     * not found.
+     */
+    chatToolCall(chatId: string, callId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ChatToolCall>;
+    /**
+     * A file of a chat's workspace, its bytes: from the tree the workspace is at now, or from the one a publish named
+     * (manifest: an ai.workspace.published event's manifest_id) — a build's product as that publish left it. Up to
+     * 64 MiB (file_too_large past it); a path its tree does not name is file_not_found.
+     */
+    chatWorkspaceFile(chatId: string, path: string, manifest?: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Blob>;
 }
 export declare function createClient(opts: ClientOptions): PalbaseClient;

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

@@ -0,0 +1,90 @@
+import { type ChatHistoryReader, type GatewayChat } from './chat.js';
+import type { RealtimeSocket } from './socket.js';
+/** One event of a gateway, as a generated module's union has it. */
+export type GatewayEvent = {
+    event: string;
+    payload: unknown;
+};
+/**
+ * A gateway, as the generator writes one. `send`, `reply` and `event` carry
+ * types alone — their values are never read: `gateway.send('say', { … })` is
+ * checked against the message's shape and resolves with its ack's, and a
+ * handler's event against the gateway's events.
+ */
+export interface GatewayDescriptor<E extends GatewayEvent, S, R = Record<keyof S, unknown>, P extends readonly string[] = readonly string[], C extends boolean = false> {
+    /** The backend's class: `ChatGateway`. */
+    name?: string;
+    /** The channel pattern the backend declared: `chat:{chatId}`. */
+    pattern: string;
+    /** It keeps what it sends: a join is sent what it keeps, and a dropped socket misses nothing. */
+    durable?: boolean;
+    /** Its server pipes a chat into it: the handle holds the chat's state (`handle.chat`). */
+    chat?: C;
+    /** 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;
+    reply?: R;
+    event: E;
+}
+/** How a gateway is joined. */
+export interface JoinOptions {
+    /** A durable gateway's: sent what it keeps first (true, the default), or only what comes after the join (false). */
+    history?: boolean;
+}
+/** What `on` returns: called, it stops that callback (`off` does the same). */
+export type GatewaySubscription = () => void;
+/** A live gateway. Hold it for as long as the view is on screen, and `leave` it when the view goes: an occupied gateway is one its backend is still running for. */
+export interface GatewayHandle<E extends GatewayEvent, S, R = Record<keyof S, unknown>> {
+    /** The channel this handle is on: `chat:42`. */
+    readonly topic: string;
+    /** A durable gateway's number of the last event the handle was sent: what a dropped socket joins again after. */
+    readonly seq: number | undefined;
+    /** Every event the gateway declares, as a union to switch over. */
+    on(handler: (event: E) => void): GatewaySubscription;
+    /** One event by its name, its payload typed. */
+    on<K extends E['event']>(event: K, handler: (payload: Extract<E, {
+        event: K;
+    }>['payload']) => void): GatewaySubscription;
+    /** Stops one callback. */
+    off(subscription: GatewaySubscription): void;
+    /**
+     * Sends one declared message and waits for the gateway's backend to take
+     * it: resolves with its ack (what its @Subscribe returned), rejects with a
+     * GatewayError — its reason — when it did not.
+     */
+    send<K extends keyof S & string>(message: K, payload: S[K]): Promise<K extends keyof R ? R[K] : unknown>;
+    /** Drops every callback of this handle and lets go of the gateway; the channel is left with its last handle. */
+    leave(): void;
+}
+/** A chat gateway's handle: the chat its server piped into the channel, as its state. */
+export interface ChatGatewayHandle<E extends GatewayEvent, S, R = Record<keyof S, unknown>> extends GatewayHandle<E, S, R> {
+    /** The chat from its start (the channel keeps it), and each change as the platform writes it. */
+    readonly chat: GatewayChat;
+}
+/** What a join resolves with: a chat gateway's handle holds its chat. */
+export type JoinedGateway<E extends GatewayEvent, S, R, C> = [C] extends [true] ? ChatGatewayHandle<E, S, R> : GatewayHandle<E, S, R>;
+/**
+ * Why a gateway 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 GatewayError extends Error {
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}
+/**
+ * Joins `gateway` on `socket`: resolves once the backend let the user in,
+ * rejects with a GatewayError when it did not. me is the signed-in user: a
+ * chat's turns and messages that are theirs; reader is how a chat gateway's
+ * chat reads its past and its calls with the user's session.
+ */
+export declare function joinGateway<E extends GatewayEvent, S, R, P extends readonly string[], C extends boolean = false>(socket: RealtimeSocket, gateway: GatewayDescriptor<E, S, R, P, C>, params: Record<P[number], string>, options?: JoinOptions, me?: () => string | undefined, reader?: ChatHistoryReader): Promise<JoinedGateway<E, S, R, C>>;

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

@@ -1,9 +1,10 @@
 export { createClient, type ClientOptions, type PalbaseClient } from './client.js';
 export type { Auth, CredentialsLike, SignInResult, User } from './auth.js';
-export { localStore, memoryStore, SessionChangedError, type AuthEvent, type RefreshMode, type Session, type SessionStore } from './session.js';
-export { Channel, RealtimeSocket, type PushReply } from './socket.js';
+export { localStore, memoryStore, SessionChangedError, type AuthEvent, type RefreshMode, type Session, type SessionEndReason, type SessionStore } from './session.js';
+export { Channel, RealtimeSocket, type ChannelOptions, type PushReply } from './socket.js';
 export { Analytics, type AnalyticsOptions } from './analytics.js';
-export { AI, ChatSession, type AgentEvent, type Chat, type ChatEvent, type ChatItem, type ChatMessageView, type ChatOptions, type ChatPart, type ChatResponse, type ChatState, type ChatVoice, type ClientToolHandlers, type ToolEvent, type ToolResult, type TurnEvent, type VoiceEvent, } from './ai.js';
+export type { AgentEvent, ChatAttachment, ChatEvent, ChatGoal, ChatItem, ChatMessageView, ChatPart, ChatPartsPage, ChatPartsQuery, ChatResponse, ChatState, ChatStreamPart, ChatThinking, ChatToolCall, ChatVoice, GatewayChat, GoalEvent, HistoryEvent, HistoryItem, Publication, ThinkingEvent, ToolEvent, TranscriptEvent, TurnEnd, TurnEvent, VoiceEvent, } from './chat.js';
+export { connectVoice, type StartedVoice, type VoiceConnection, type VoiceOptions } from './voice.js';
 export { Purchases, type CustomerInfo, type CustomerInfoListener, type MergeGrant, type Offerings } from './purchases.js';
 export type { Paywall, PaywallRenderOptions } from './paywall/placement.js';
 export type { PaywallAttribute } from './paywall/attributes.js';
@@ -11,5 +12,5 @@ export type { PaywallPackage, PaywallView } from './paywall/render.js';
 export { PalbaseError } from '../../internal/src/transport.js';
 export { BackendError, isBackendError, type BackendErrorKind, type FieldError } from './backend-error.js';
 export type { BackendBase, CallOptions, UploadOptions, UploadProgress } from './backends.js';
-export { RoomError, type RoomDescriptor, type RoomEvent, type RoomHandle, type RoomSubscription } from './rooms.js';
+export { GatewayError, type ChatGatewayHandle, type GatewayDescriptor, type GatewayEvent, type GatewayHandle, type GatewaySubscription, type JoinedGateway, type JoinOptions } from './gateways.js';
 export type { RetryPolicy } from '../../internal/src/retry.js';

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

@@ -17,6 +17,14 @@ export interface SessionStore {
     watch?(onChange: () => void): () => void;
 }
 export type AuthEvent = 'SIGNED_IN' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'SIGNED_OUT' | 'SESSION_EXPIRED';
+/**
+ * Why a session ended without the app signing out (SESSION_EXPIRED): it ran out (past its lifetime, or idle too
+ * long), it was revoked (signed out everywhere, revoked by the project, its token refused), the account was deleted
+ * (by the project, or by the user on another device), or the account was suspended.
+ */
+export type SessionEndReason = 'expired' | 'revoked' | 'userDeleted' | 'userBanned';
+/** What a refused refresh says: auth's reason when it gives one, else what its code means. */
+export declare function sessionEndReasonOf(refusal: unknown): SessionEndReason;
 export interface TokenPair {
     access_token: string;
     refresh_token: string;
@@ -57,6 +65,8 @@ export declare class SessionManager {
     private current;
     private loaded;
     private inflight;
+    /** Why the last session ended, set before SESSION_EXPIRED is told; null once someone signs in or out. */
+    endReason: SessionEndReason | null;
     private listeners;
     private store;
     private refresher;
@@ -82,7 +92,7 @@ export declare class SessionManager {
      * tab: a sign-out signs the user out of every tab. It is left alone only
      * when it holds another user's (someone else signed in since).
      */
-    clear(event: 'SIGNED_OUT' | 'SESSION_EXPIRED'): Promise<void>;
+    clear(event: 'SIGNED_OUT' | 'SESSION_EXPIRED', reason?: SessionEndReason): Promise<void>;
     /** The access token to send now; undefined when no one is signed in. */
     accessToken(): Promise<string | undefined>;
     /** One refresh at a time — in this tab, and across tabs when the store is shared. */

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

@@ -12,6 +12,14 @@ export interface SocketOptions {
     replyTimeoutMs?: number;
 }
 export type ChannelState = 'closed' | 'joining' | 'joined' | 'refused';
+export interface ChannelOptions {
+    /**
+     * On a durable channel, the number to be sent its log after: what was missed
+     * since (0: all it keeps). Left out, the channel is heard from its join on.
+     * Either way it is joined again after the last number it was sent.
+     */
+    after?: number;
+}
 /**
  * What became of a push: the server's answer — `ok` with its response, or
  * `error` with `{ reason }` — or, when none came, `timeout` (`no reply`: the
@@ -26,13 +34,20 @@ export declare class Channel {
     state: ChannelState;
     /** Why the server refused the last join, when it did. */
     refusal?: Record<string, unknown>;
+    /**
+     * A durable channel's number: of the last broadcast it was sent (each carries
+     * its `seq`), or of the one its join started after. A socket that drops joins
+     * it again after it, and is sent what it missed in order, once. Undefined on
+     * a channel that keeps no log.
+     */
+    logSeq?: number;
     joinRef: string | null;
     private listeners;
     private closers;
     private joinWaiters;
     readonly name: string;
     private socket;
-    constructor(name: string, socket: RealtimeSocket);
+    constructor(name: string, socket: RealtimeSocket, opts?: ChannelOptions);
     get topic(): string;
     /** Resolves once joined; rejects with the server's reason when refused. */
     join(): Promise<void>;
@@ -69,7 +84,8 @@ export declare class RealtimeSocket {
     reconnects: number;
     private opts;
     constructor(opts: SocketOptions);
-    channel(name: string): Channel;
+    /** The channel by its name; opts are the first caller's (a channel already made keeps its own). */
+    channel(name: string, opts?: ChannelOptions): Channel;
     /** Closes the socket; every channel is closed (the app joins again — as the next user, if one signs in). */
     disconnect(): void;
     /** A new token for every joined channel (the session was refreshed). */

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

@@ -0,0 +1,36 @@
+/** What the app's backend answers the offer with: the voice it started, and the provider's answer (chats.voice.start). */
+export interface StartedVoice {
+    id: string;
+    sdp: string;
+}
+export interface VoiceOptions {
+    /** The round trip to the app's own backend: the offer (an SDP) in, the voice and its answer out. */
+    start(sdp: string): Promise<StartedVoice>;
+    /** Where the voice plays; left out, an audio element of its own (autoplay), not in the page. */
+    audio?: HTMLAudioElement;
+    /** A microphone the app opened already — left open on close; left out, one is asked for (getUserMedia) and closed with the voice. */
+    microphone?: MediaStream;
+    /** How long the offer's network candidates are gathered at most before it is sent (default 10 s). */
+    iceTimeoutMs?: number;
+    /** Ends the connecting: whatever was opened is closed. */
+    signal?: AbortSignal;
+    /** The provider's word that something went wrong in the voice (its events channel carries errors alone). */
+    onError?(message: string): void;
+    /** The connection's state each time it changes: connected, disconnected, failed, closed. */
+    onState?(state: RTCPeerConnectionState): void;
+}
+/** A voice connected: the peer connection, where it plays, and its microphone — muted, or closed. */
+export interface VoiceConnection {
+    /** The voice the backend started: what it reads, tells and closes it by. */
+    readonly id: string;
+    readonly peer: RTCPeerConnection;
+    readonly audio: HTMLAudioElement;
+    readonly microphone: MediaStream;
+    /** The microphone is heard (false) or not (true). */
+    readonly muted: boolean;
+    mute(on: boolean): void;
+    /** Ends it here: the connection, and the microphone it opened. The backend closes the voice itself (chats.voice.close). */
+    close(): void;
+}
+/** Connects the browser to a chat's voice: the microphone in, the voice out, the offer through the app's own backend. */
+export declare function connectVoice(options: VoiceOptions): Promise<VoiceConnection>;

package/dist/chunks/2RG3I7LX.js

@@ -1,6 +0,0 @@
-/*! palbase 0.6.2 — Palbase SDK License (see LICENSE) */
-import{a as C,b as E}from"./IYCW6PWG.js";async function*S(e,t={}){let n=e.getReader(),o=new TextDecoder,r="",a="",i=[],g,w=()=>{n.cancel().catch(()=>{})};t.signal?.addEventListener("abort",w,{once:!0});try{if(t.signal?.aborted)return;for(;;){let{done:v,value:A}=await n.read();if(v||t.signal?.aborted)return;t.onBytes?.(),r+=o.decode(A,{stream:!0});for(let y=r.indexOf(`
-`);y>=0;y=r.indexOf(`
-`)){let s=r.slice(0,r[y-1]==="\r"?y-1:y);r=r.slice(y+1),s===""?(a!==""&&(yield g===void 0?{event:a,data:i.join(`
-`)}:{event:a,data:i.join(`
-`),id:g}),a="",i=[],g=void 0):s.startsWith("event:")?a=k(s,6):s.startsWith("data:")?i.push(k(s,5)):s.startsWith("id:")&&(g=k(s,3))}}}finally{t.signal?.removeEventListener("abort",w);try{await n.cancel()}catch{}}}function k(e,t){let n=e.slice(t);return n.startsWith(" ")?n.slice(1):n}function P(e){let t=0;for(let n=0;n<e.length;n++){let o=e.charCodeAt(n);o<128?t+=1:o<2048?t+=2:o>=55296&&o<=56319&&n+1<e.length&&(e.charCodeAt(n+1)&64512)===56320?(t+=4,n++):t+=3}return t}function $(e,t){if(t<=0)return 0;let n=0;for(let o=0;o<e.length;o++){let r=e.charCodeAt(o),a=3,i=1;if(r<128?a=1:r<2048?a=2:r>=55296&&r<=56319&&o+1<e.length&&(e.charCodeAt(o+1)&64512)===56320&&(a=4,i=2),n+=a,n>=t)return o+i;o+=i-1}return e.length}function j(e,t){return e.slice($(e,t))}var M={too_many_streams:()=>"too many chat streams are open at once (4 a user, 32 a project): close one \u2014 chat.close(), or leave a stream's loop \u2014 then follow again",too_many_chats:()=>"this user is in as many chats as they may be (100): delete or leave one before starting another",too_many_endpoints:()=>"the project holds as many tool endpoints as it may (32): delete one (ai.endpoints.delete) before putting another",too_many_messages:e=>`this user has sent as many messages this minute as the project allows${e.retryAfter!==void 0?`: write again in ${e.retryAfter} s`:""}`,history_full:()=>"the project keeps as much chat history as it may: delete chats to write again",not_your_turn:()=>"this turn is another member's: only the member who started it (or the project's server) answers its tools and decides its approvals",image_not_found:()=>"a picture given is not a file of the project's storage: upload it first (storage.from(bucket).upload(path, file)) and give that bucket and path",storage_unavailable:e=>`the project's storage did not answer when the model was to read a picture${e.retryAfter!==void 0?`: try again in ${e.retryAfter} s`:"; try again shortly"}`},O=new WeakSet;function R(e){if(!(e instanceof E)||O.has(e))return e;let t=M[e.code];if(!t)return e;let n=new E({op:e.op,status:e.status,code:e.code,message:`${t(e)} (${e.op}: ${e.status} ${e.code})`,requestId:e.requestId,retryAfter:e.retryAfter,body:e.body,cause:e});return O.add(n),n}function V(e){return e.catch(t=>{throw R(t)})}var m=class extends Error{constructor(t){super(t),this.name="StreamCut"}};function Y(e,t={}){let n=t.resumeFor??12e4,o=t.idleFor??45e3,r=t.signal,a=t.after,i=t.response,g=new Map;i!==void 0&&g.set(i,t.offset??0);let w=!1,v=()=>{let s={};return a!==void 0&&(s.after=a),i!==void 0&&(s.response=i,s.offset=g.get(i)??0),s};function A(s,_,h){let f=h!==void 0&&/^\d+$/.test(h)?Number(h):void 0;if(f!==void 0&&a!==void 0&&f<=a)return;let c;try{c=C(JSON.parse(_))}catch{throw new m(`a ${s} frame is not JSON`)}if(typeof c!="object"||c===null)throw new m(`a ${s} frame is not an object`);let p;switch(s){case"message":p={type:"message",seq:f??0,message:c};break;case"turn":{let d={...c,type:"turn",seq:f??0};d.waiting??=null,d.error??=null,(d.status==="running"||d.status==="waiting")&&(i=d.response_id),p=d;break}case"text":{let d=String(c.response_id),l=Number(c.offset),u=String(c.text??"");if(!Number.isInteger(l)||l<0)throw new m("a text frame names no offset");i=d;let b=g.get(d)??0,x=l+P(u);if(x<=b)return;let T=l>=b?u:j(u,b-l);g.set(d,x),p={type:"text",response_id:d,offset:Math.max(l,b),text:T};break}case"reset":{let d=String(c.response_id),l=Number(c.offset),u=g.get(d)??0;if(!Number.isInteger(l)||l<0||l>=u)return;g.set(d,l),p={type:"reset",response_id:d,offset:l};break}case"tool":case"agent":case"voice":p={...c,type:s,seq:f??0};break;default:break}return f!==void 0&&(a=f),p}async function*y(){let s=Date.now()+n,_;for(let h=0;;h++){if(r?.aborted)throw r.reason;let f=new AbortController,c=()=>f.abort(r?.reason);r?.addEventListener("abort",c,{once:!0});let p,d=()=>{clearTimeout(p),p=setTimeout(()=>f.abort(new m(`no byte for ${o} ms`)),o)},l;try{let u=await e(v(),f.signal);if(!u.body)throw new m("the stream has no body");d();let b=S(u.body,{signal:f.signal,onBytes:()=>{d(),s=Date.now()+n,h=0}});for await(let x of b){let T=A(x.event,x.data,x.id);T&&(yield T)}_=new m("the stream ended")}catch(u){if(r?.aborted)throw r.reason;if(u instanceof E){if(u.status>0&&u.status<500&&u.status!==429||u.code==="too_many_streams")throw R(u);u.retryAfter!==void 0&&(l=u.retryAfter*1e3)}_=f.signal.aborted&&f.signal.reason instanceof m?f.signal.reason:u}finally{clearTimeout(p),r?.removeEventListener("abort",c),f.abort()}if(Date.now()+(l??0)>s)throw _;await L(l??Math.min(250*2**Math.min(h,4),4e3),r)}}return{get position(){return v()},[Symbol.asyncIterator](){if(w)throw new TypeError("a chat stream is read once: follow the chat again from its position for another reader");return w=!0,y()}}}function L(e,t){return new Promise((n,o)=>{if(t?.aborted)return o(t.reason);let a=setTimeout(()=>{t?.removeEventListener("abort",i),n()},e),i=()=>{clearTimeout(a),o(t?.reason)};t?.addEventListener("abort",i,{once:!0})})}var N=new Set(["image/png","image/jpeg","image/webp","image/gif"]);function H(e){return Array.isArray(e)&&e.length>0&&e.every(q)?e.map(F):q(e)?[F(e)]:e==null?[{type:"text",text:""}]:typeof e=="string"?[{type:"text",text:e}]:[{type:"text",text:JSON.stringify(e)??String(e)}]}function q(e){if(typeof e!="object"||e===null)return!1;let t=e;return t.type==="text"?typeof t.text=="string":t.type==="image"?(typeof t.mediaType=="string"||typeof t.media_type=="string")&&(typeof t.data=="string"||t.data instanceof Uint8Array):t.type===void 0&&typeof t.mediaType=="string"&&t.bytes instanceof Uint8Array}function F(e){if("type"in e&&e.type==="text")return{type:"text",text:e.text};let t="bytes"in e||"mediaType"in e?e.mediaType:e.media_type;if(!N.has(t))throw new TypeError(`a tool's picture is image/png, image/jpeg, image/webp or image/gif (got ${JSON.stringify(t)})`);let n="bytes"in e?e.bytes:e.data;return{type:"image",media_type:t,data:typeof n=="string"?n:B(n)}}function B(e){let t="";for(let n=0;n<e.length;n+=32768)t+=String.fromCharCode(...e.subarray(n,n+32768));return btoa(t)}export{S as a,P as b,$ as c,j as d,R as e,V as f,Y as g,H as h};