palbase 0.26.0 → 0.28.0

package/types/web/src/calls-ui/index.d.ts

@@ -0,0 +1,71 @@
+import type { Call, CallSession, Calls } from '../calls.js';
+/** Every word the screens show. */
+export interface CallUITexts {
+    incomingVoice: string;
+    incomingVideo: string;
+    accept: string;
+    acceptVoiceOnly: string;
+    decline: string;
+    calling: string;
+    connecting: string;
+    reconnecting: string;
+    /** How the call ended for this device, by its endReason; `ended` for any other. */
+    declined: string;
+    missed: string;
+    busy: string;
+    hungUp: string;
+    canceled: string;
+    failed: string;
+    answeredElsewhere: string;
+    left: string;
+    ended: string;
+}
+/** What a screen reader says of what shows no words of its own. */
+export interface CallUILabels {
+    /** The ringing sheet. */
+    incoming: string;
+    /** The call's view. */
+    call: string;
+    mute: string;
+    unmute: string;
+    cameraOn: string;
+    cameraOff: string;
+    switchCamera: string;
+    hangUp: string;
+    /** This device's camera. */
+    self: string;
+}
+/** The screens' colors, corners and font: CSS values, set as --pb-call-<name> on the root element. */
+export interface CallUITheme {
+    accent?: string;
+    background?: string;
+    foreground?: string;
+    danger?: string;
+    /** A length; a number is pixels. */
+    radius?: string | number;
+    font?: string;
+}
+export interface CallUIOptions {
+    /** The element the screens are drawn in (positioned): over the whole page (the body) unless given. */
+    container?: HTMLElement;
+    texts?: Partial<CallUITexts>;
+    labels?: Partial<CallUILabels>;
+    /** The light and dark colors the system asks for, unless given. */
+    theme?: CallUITheme;
+    /** Added to the root element's classes. */
+    className?: string;
+    /** A soft ring while a sheet shows (true by default); silent where the page may not play sound yet. */
+    ringtone?: boolean;
+    /** Asked once for each call that rings: false leaves it to the app's own screen. */
+    incoming?(call: Call, session: CallSession): boolean;
+    /** An answer, a microphone or a camera that failed (the person refused the camera, the network). */
+    onError?(error: unknown, session: CallSession): void;
+}
+export interface CallUI {
+    /** Takes the screens away and stops listening; a call goes on. */
+    unmount(): void;
+}
+export declare const CALL_UI_TEXTS: Readonly<CallUITexts>;
+export declare const CALL_UI_LABELS: Readonly<CallUILabels>;
+/** Shows pb.calls' ringing calls and the call this page is in, until unmount. */
+export declare function mountCallUI(calls: Calls, options?: CallUIOptions): CallUI;

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

@@ -0,0 +1,274 @@
+import { calls as api } from '../../internal/src/modules/index.js';
+/** A call as the module keeps it: its people, its state, how it ended. */
+export type Call = api.Call;
+/** A person (or the project's agent) in a call, as the call lists them. */
+export type CallParticipant = api.Participant;
+/** A page of calls, newest first. */
+export type CallPage = api.CallPage;
+type Listener = () => void;
+/**
+ * Where a call is, as this device has it:
+ * - `calling` — the person called is being rung;
+ * - `incoming` — this person is rung; `invited` — asked into a call that does not ring (a huddle: join it);
+ * - `connecting` — answered, the media on its way; `connected`; `reconnecting` — the network dropped for a moment;
+ * - `elsewhere` — answered on another device or in another tab;
+ * - `ended` — over for this device (endReason says why).
+ */
+export type CallPhase = 'calling' | 'incoming' | 'invited' | 'connecting' | 'connected' | 'reconnecting' | 'elsewhere' | 'ended';
+/** Someone else in the call, and what is heard and seen of them. */
+export interface RemoteParticipant {
+    /** Their user id — or, for the project's agent, bot:<identity>. */
+    userId: string;
+    name: string | null;
+    imageUrl: string | null;
+    bot: boolean;
+    /** Their audio and video: one stream for the whole call, whichever way the media flows. */
+    stream: MediaStream;
+    /** Their microphone is heard. */
+    audio: boolean;
+    /** Their camera is seen. */
+    video: boolean;
+}
+export interface CallState {
+    /** The call as the module last said it (the highest version heard). */
+    call: Call;
+    /** This person, as the call lists them. */
+    me: CallParticipant | null;
+    phase: CallPhase;
+    /** This person rang (or started the group). */
+    outgoing: boolean;
+    /** Between the two devices, or through the media server. */
+    mode: 'p2p' | 'sfu';
+    /** This device's microphone and camera, while it is in the call. */
+    local: MediaStream | null;
+    microphone: boolean;
+    camera: boolean;
+    /** The others in the call. */
+    remote: RemoteParticipant[];
+    /** Why it ended for this device: the call's end_reason, `left` (this person left a group that goes on), `declined`, `missed`, `answered_elsewhere`. */
+    endReason: string | null;
+    /** The last thing that went wrong with this device's media (a camera refused, the media server not reached). */
+    error: Error | null;
+}
+export interface StartCallOptions {
+    /** A video call; a voice call unless true (pb.calls.video and pb.calls.voice say it). */
+    video?: boolean;
+    /** Ring the people asked (true by default); false: a group call they join (a huddle). */
+    ring?: boolean;
+    /** A group call even with one person asked: others may be asked later. */
+    group?: boolean;
+    /** The conversation it is made from: its members alone may be called, and it keeps the call as a message. */
+    conversationId?: string;
+    /** The app's own words about the call, shown to those rung (32 strings, 2 KiB at most). */
+    metadata?: Record<string, string>;
+    /** The name and picture shown to those rung; else the caller's messaging profile's. */
+    callerName?: string;
+    callerImageUrl?: string;
+    /** This call's media through the relay alone (CallsOptions.forceRelay, for one call). */
+    forceRelay?: boolean;
+    /** A microphone (and camera) stream the app opened already; left open when the call ends. */
+    media?: MediaStream;
+}
+export interface AnswerOptions {
+    /** Send video (the call's own kind unless said): a video call answered by voice, or a voice call with the camera on. */
+    video?: boolean;
+    forceRelay?: boolean;
+    media?: MediaStream;
+}
+export interface HistoryOptions {
+    /** 1 to 100; 20 when absent. */
+    limit?: number;
+    /** The page after the one that handed out this cursor (next_cursor). */
+    cursor?: string;
+    /** Only the calls the person missed (or was busy for). */
+    missed?: boolean;
+    state?: 'ringing' | 'active' | 'ended';
+}
+/** The browser's media, as calls uses it: a test's or a runtime's own. */
+export interface CallsRTC {
+    RTCPeerConnection: typeof RTCPeerConnection;
+    MediaStream: typeof MediaStream;
+    getUserMedia(constraints: MediaStreamConstraints): Promise<MediaStream>;
+}
+export interface CallsOptions {
+    /**
+     * Every call's media through the relay (iceTransportPolicy relay), never straight between the devices: neither
+     * learns the other's address, at the price of a hop. The project's relay_all setting says it for every app.
+     */
+    forceRelay?: boolean;
+    /** The others' voices play by themselves (true by default): false leaves each RemoteParticipant's stream to the app. */
+    playAudio?: boolean;
+}
+/**
+ * One call as this device has it: its state to draw (subscribe), and what the person does in it. Made by
+ * pb.calls.start/voice/video/join, or heard (pb.calls.onIncoming).
+ */
+export declare class CallSession {
+    readonly id: string;
+    private c;
+    private call;
+    private snapshot;
+    private readonly listeners;
+    /** This tab acts in the call: it made, answered or joined it here. */
+    private owned;
+    /** This tab is answering or joining it: what the module says meanwhile does not end it. */
+    private entering;
+    private phase;
+    private endReason;
+    private error;
+    private relay;
+    private local;
+    private tracks;
+    /** The tracks this device opened, stopped when the call is done with them; an app's own stream is left open. */
+    private readonly opened;
+    private mic;
+    private facing;
+    private link;
+    private linking;
+    private linkState;
+    private sdpSent;
+    private answered;
+    private answer;
+    private inbox;
+    private lastSeq;
+    private readonly seen;
+    private readonly sentSeqs;
+    private room;
+    private joiningRoom;
+    private roomState;
+    private readonly streams;
+    private readonly via;
+    private readonly mutedInRoom;
+    private readonly players;
+    private sink;
+    private quieted;
+    private heartbeat;
+    private poll;
+    private done;
+    get state(): CallState;
+    /** Listens to every change of state; returns the unsubscribe. */
+    subscribe(listener: Listener): () => void;
+    /** Answers the call on this device (the first of the person's devices to answer has it). */
+    accept(o?: AnswerOptions): Promise<void>;
+    /** Comes into a group call this person was asked to (or was in before). */
+    join(o?: AnswerOptions): Promise<void>;
+    /** Turns the call down on every device of this person's: a direct call ends; a group goes on, and may still be joined. */
+    decline(): Promise<void>;
+    /** Hangs up (or, while it rings, cancels): a direct call ends for both; a group goes on for the others. */
+    leave(): Promise<void>;
+    /** Asks more people in (ringing them unless ring is false): a direct call becomes a group, going on. */
+    invite(userIds: string | string[], o?: {
+        ring?: boolean;
+    }): Promise<void>;
+    /** The microphone heard (true) or muted. */
+    setMicrophone(on: boolean): Promise<void>;
+    /** The camera on or off: off, it is closed (its light goes out); on, opened again — a voice call's too. */
+    setCamera(on: boolean): Promise<void>;
+    /** Another camera: the one named (a videoinput's deviceId), or the other facing one (front, back). */
+    switchCamera(deviceId?: string): Promise<void>;
+    /** Where the others' voices play: an audiooutput's deviceId (a browser that can choose one: setSinkId). */
+    setAudioOutput(deviceId: string): Promise<void>;
+    /** Reads the call as it is now. */
+    refresh(): Promise<void>;
+    private me;
+    /** What the call now means for this device, and the media that follows. */
+    private derive;
+    private mediaPhase;
+    private enter;
+    /** This device's microphone (and camera): the app's stream, or opened here. */
+    private open;
+    private camera;
+    /** The camera's track now (null: off), wherever the media flows. */
+    private putVideo;
+    private toPeer;
+    /** Sends a signal once the call is answered (nothing leaves before): an offer or answer in order, candidates after it. */
+    private signal;
+    private take;
+    /** A signal between the last one handled and this one that is neither handled nor this device's own: missed. */
+    private gapBefore;
+    private fetchSignals;
+    private handle;
+    /** The connection between the devices is gone: what came through it goes too. */
+    private unlink;
+    private toRoom;
+    private streamOf;
+    private heard;
+    private gone;
+    private play;
+    private beat;
+    private stillHere;
+    private end;
+    /** The tracks this device opened are closed: the camera's light goes out. */
+    private release;
+    private stopIfOpened;
+    /** Its notification goes, once: the call no longer rings here. */
+    private quiet;
+    private failed;
+    private refusal;
+    private refused;
+    private changed;
+    private remoteOf;
+}
+/** pb.calls: the signed-in person's calls. */
+export declare class Calls {
+    /** This install's device id: the one its pushes are registered with (web-<installation id>). */
+    readonly deviceId: string;
+    private readonly transportFor;
+    private readonly session;
+    private readonly socket;
+    private readonly ref;
+    private readonly opts;
+    private readonly beacon;
+    private user;
+    private api;
+    private channel;
+    private off;
+    private readonly sessions;
+    private readonly incoming;
+    private readonly entered;
+    private workerHeard;
+    /** The call this page is in (made, answered or joined here), or null. */
+    get current(): CallSession | null;
+    /**
+     * Calls one person (a direct call: their devices ring) or several (a group call), from this device — its
+     * microphone (and camera) asked for first: a refusal rings no one. A call to someone calling this person this moment
+     * is that call, answered. Refused with a PalbaseError: `not_allowed` (403), `in_another_call` (409),
+     * `too_many_calls` or `quota_exceeded` (429), `invalid_user_ids` or `call_full` (400).
+     */
+    start(userIds: string | string[], o?: StartCallOptions): Promise<CallSession>;
+    /** A voice call. */
+    voice(userIds: string | string[], o?: Omit<StartCallOptions, 'video'>): Promise<CallSession>;
+    /** A video call. */
+    video(userIds: string | string[], o?: Omit<StartCallOptions, 'video'>): Promise<CallSession>;
+    /** Comes into a group call this person was asked to — a huddle, one they declined or left — on this device. */
+    join(callId: string, o?: AnswerOptions): Promise<CallSession>;
+    /**
+     * Listens for calls that ring this person (and group calls they are asked to: phase `invited`), while the page is
+     * open — and those ringing as it opens (a tap on the call's notification). Returns the unsubscribe.
+     */
+    onIncoming(listener: (call: CallSession) => void): () => void;
+    /** Listens for each call this page comes into — made, answered or joined here (a call UI follows them). Returns the unsubscribe. */
+    onCall(listener: (call: CallSession) => void): () => void;
+    /** This person's calls, newest first, with how each went for them (their participant's state: `missed` among them). */
+    history(o?: HistoryOptions): Promise<CallPage>;
+    /** A call of this person's, as it is now. */
+    get(callId: string): Promise<Call>;
+    /**
+     * Follows the signed-in person's calls (start, join and onIncoming do it themselves): their channel, and the calls
+     * ringing them now. Rejects when no one is signed in.
+     */
+    ready(): Promise<void>;
+    private stop;
+    private unfollow;
+    private follow;
+    /** The calls ringing this person now: a page opened by the call's notification, or a channel that was down. */
+    private ringing;
+    /** A tap on a call's notification, told by the service worker (palbase/web/push-sw.js). */
+    private listenToWorker;
+    private heardCall;
+    private tell;
+    /** The session of a call: the one kept, or a new one (entering: this device is about to answer or join it). */
+    private sessionOf;
+    private rtc;
+}
+export {};

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

@@ -11,6 +11,7 @@ import { Purchases } from './purchases.js';
 import { type ChatToolCall } from './chat.js';
 import { Flags } from './flags.js';
 import { Messaging, type MessagingOptions } from './messaging.js';
+import { Calls, type CallsOptions } from './calls.js';
 export interface ClientOptions {
     /** The project's address: https://<ref>.<domain> */
     url: string;
@@ -71,6 +72,8 @@ export interface ClientOptions {
     language?: string | readonly string[];
     /** What the device keeps of the signed-in person's conversations (pb.messaging): dropped on sign-out unless keepOnSignOut. */
     messaging?: MessagingOptions;
+    /** How the signed-in person's calls go (pb.calls): every call through the relay (forceRelay), voices played by themselves (playAudio). */
+    calls?: CallsOptions;
 }
 /**
  * The app's client. A backend's generated Palbe module (palbase apps:sync)
@@ -98,6 +101,8 @@ export interface PalbaseClient {
     flags: Flags;
     /** The signed-in person's conversations — direct ones and groups — kept up to date, on the device and live. */
     messaging: Messaging;
+    /** The signed-in person's voice and video calls: made, rung, answered — one to one or in a group. */
+    calls: Calls;
     /** The language every request says from now on (ClientOptions.language); null for the browser's own. */
     setLanguage(language: string | readonly string[] | null): void;
     /**

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

@@ -11,6 +11,7 @@ export { Purchases, redemptionToken, type CheckoutSource, type CustomerInfo, typ
 export { Notify, WebPush, type PushPermission, type PushSubscribeOptions } from './notify.js';
 export { Flags, type FlagSource, type FlagsListener } from './flags.js';
 export { ConversationList, ConversationView, DeletedGroupList, indexedDBKeyValue, Messaging, ScheduledList, ThreadView, type Conversation, type ConversationMatch, type ConversationViewState, type ConversationListState, type DeletedGroup, type DeletedGroupListState, type Entry, type Hit, type Member, type Message, type MessagingOptions, type MyProfile, type Observed, type OpenedFile, type OutboxItem, type OutgoingFile, type Profile, type ScheduledMessage, type SearchHit, type SearchMatch, type SearchOptions, type SearchResults, type SendOptions, type ThreadState, type ThreadViewState, } from './messaging.js';
+export { Calls, CallSession, type AnswerOptions, type Call, type CallPage, type CallParticipant, type CallPhase, type CallsOptions, type CallState, type HistoryOptions, type RemoteParticipant, type StartCallOptions, } from './calls.js';
 export { Inbox, type InboxItem, type InboxListOptions, type InboxPage, type InboxView, type InboxViewOptions } from './inbox.js';
 export { InApp, SESSION_START, type InAppOptions } from './inapp.js';
 export type { Paywall, PaywallRenderOptions } from './paywall/placement.js';

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

@@ -11,6 +11,7 @@ export type Profile = api.Profile;
 export type ScheduledMessage = api.ScheduledMessage;
 export type ThreadState = api.ThreadState;
 export type SearchMatch = api.SearchMatch;
+export type OpenGroup = api.OpenGroup;
 export type { DeletedGroup, Entry, Hit, OutboxItem } from '../../internal/src/messaging/index.js';
 export interface MessagingOptions {
     /**
@@ -117,6 +118,8 @@ export interface SearchOptions {
     by?: 'words' | 'meaning';
     /** Search one conversation of the person's only. */
     conversationId?: string;
+    /** Search the conversations of one space only (org:<id>): a place of the app's they belong to. */
+    space?: string;
     /** How many messages a page holds (1 to 50; 20 when absent). */
     limit?: number;
     /** The page after the one that handed out this cursor (nextCursor): a search by words alone. */
@@ -256,8 +259,13 @@ export declare class Messaging {
     private seat;
     private typed;
     private tell;
-    /** The person's conversations, the latest first, kept up to date. */
-    conversations(): ConversationList;
+    /**
+     * The person's conversations, the latest first, kept up to date — those of some spaces only (spaces: the places of
+     * the app's they belong to, as org:<id>), when it names any.
+     */
+    conversations(opts?: {
+        spaces?: string[];
+    }): ConversationList;
     /**
      * The groups the person was in that someone deleted, kept up to date while the person may still report them
      * (reportableUntil, 14 days after), the latest to stop first: report() names one by its id, no message needed. A
@@ -273,15 +281,27 @@ export declare class Messaging {
     conversation(conversationId: string, opts?: {
         at?: string;
     }): ConversationView;
-    /** The direct conversation with someone — the one there is, or a new one. */
-    direct(userId: string): Promise<ConversationView>;
-    /** A new group, the person its owner. */
+    /**
+     * The direct conversation with someone — the one there is, or a new one — in a space (org:<id>): the two have one in
+     * each space, and one with none. The project's hook is asked, the space named.
+     */
+    direct(userId: string, opts?: {
+        space?: string;
+    }): Promise<ConversationView>;
+    /**
+     * A new group, the person its owner — in a space (org:<id>), and open (found in the space's open groups and joined
+     * by whom the project's hook lets: openGroups, join) or closed (the default: joined when someone adds you). An open
+     * group names its space ('space_required'), and the project's hook is asked whether the person may make one there
+     * ('open_group'; refused: 'not_allowed').
+     */
     group(input: {
         title: string;
         memberIds?: string[];
         description?: string;
         photo?: string;
         settings?: api.GroupSettings;
+        space?: string;
+        visibility?: 'open' | 'closed';
     }): Promise<{
         conversation: ConversationView;
         notAdded: api.NotAdded[];
@@ -301,8 +321,26 @@ export declare class Messaging {
      * means instead, the nearest first, each with its score: one page, no conversations by name. Opened as any find is.
      */
     search(query: string, opts?: SearchOptions): Promise<SearchResults>;
-    /** The person's conversations whose name says every word asked: a group's title, the other person's name. */
+    /** The person's conversations (of a space, when one is named) whose name says every word asked: a group's title, the other person's name. */
     private named;
+    /**
+     * A space's open groups (org:<id>), the oldest first, a page at a time — each with whether the person is in it
+     * (joined) — when the project's hook lets them find them; refused otherwise (a PalbaseError, code 'not_allowed').
+     */
+    openGroups(space: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: OpenGroup[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * Joins an open group by themselves — when the project's hook lets them and it has room — and answers it, the person
+     * in it. Joining one they are in answers it as it is. Refused (a PalbaseError) when the hook does not let them
+     * ('not_allowed'), an admin removed them ('removed'), it is read-only ('read_only') or full ('group_full'); a closed
+     * group is not found.
+     */
+    join(conversationId: string): Promise<ConversationView>;
     /** The person's messages scheduled for later, kept up to date. */
     scheduled(): ScheduledList;
     /** The threads the person follows, the latest answered first. */
@@ -373,6 +411,9 @@ declare abstract class View<S> implements Observed<S> {
     protected abstract read(): S;
 }
 export declare class ConversationList extends View<ConversationListState> {
+    /** The spaces it is narrowed to (none: every conversation). */
+    readonly spaces: readonly string[];
+    constructor(m: Messaging, spaces?: readonly string[]);
     protected touches(t: Touched): boolean;
     protected read(): ConversationListState;
 }