palbase 0.34.0 → 0.36.0

package/types/internal/src/modules/calls.d.ts

@@ -53,6 +53,10 @@ export type Call = {
      * Its people and bots
      */
     participants: Participant[];
+    /**
+     * The place it is held at, as the project names it (a channel of its app, a conversation: channel:42, conversation:<id>): the place's people — whom the project's rule lets in — find it going on and join it unasked. Null for a call of no place
+     */
+    place: string | null;
     /**
      * Whether it rings the people asked (false: a huddle they join)
      */
@@ -102,6 +106,10 @@ export type CallEvent = {
      * user or bot
      */
     participant_kind?: string;
+    /**
+     * The place it is held at (null for a call of no place)
+     */
+    place: string | null;
     /**
      * The call's room on the media server: what an agent's ticket is for
      */
@@ -240,6 +248,10 @@ export type HookSettings = {
      * A hook that does not answer: refuse the call, or let it
      */
     on_error?: "deny" | "allow";
+    /**
+     * The hook answers places too (action place: may this person see and join the calls held at a place). Off, it is never asked of a place, and a place's call is seen only by the people asked into it (a conversation:<id> place's members aside)
+     */
+    places?: boolean;
     /**
      * How long it is waited for (100 to 5,000; 2,000)
      */
@@ -262,6 +274,23 @@ export type InviteRequest = {
      */
     user_ids: string[];
 };
+/**
+ * Comes into a group call on a device
+ */
+export type JoinRequest = {
+    /**
+     * The device it is joined on
+     */
+    device_id: string;
+    /**
+     * Their picture, an https URL, likewise
+     */
+    image_url?: string | null;
+    /**
+     * What the others see of one who comes in unasked (a place's), where nothing else names them
+     */
+    name?: string | null;
+};
 /**
  * A device's way into the call's room on the media server, where every call's media flows — one to one or in a group: its url and the ticket its client connects with
  */
@@ -332,6 +361,20 @@ export type Participant = {
      */
     user_id: string;
 };
+/**
+ * A place and its call: going on, or — told to a watcher as it ends — its last, ended (with its version: a snapshot that comes late is known for older); no call when none goes on there. Participants carry no device_id
+ */
+export type PlaceView = {
+    call?: Call;
+    /**
+     * The place
+     */
+    place: string;
+    /**
+     * How long the reader is told of the place's call (the place event on their calls channel) before the watch is asked again — a watch's answer alone
+     */
+    watch_seconds?: number;
+};
 /**
  * A call to make
  */
@@ -362,12 +405,16 @@ export type StartCallRequest = {
     metadata?: {
         [key: string]: string;
     };
+    /**
+     * Holds the call at a place (a group call): letters, digits and . _ : -, 1 to 128 (channel:42; conversation:<id> for a conversation of Palbase's messaging, whose members it lets in). One call goes on at a place at a time. Who it lets in is the project's rule: a conversation's members, else the project's hook (calls.can_call, action place); with no hook, no one but those asked
+     */
+    place?: string | null;
     /**
      * Ring them (true, by default); false: a group call they join (a huddle)
      */
     ring?: boolean;
     /**
-     * Who to call: one person (a direct call), or several (a group)
+     * Who to call: one person (a direct call), or several (a group); none for a call at a place, which its people join
      */
     user_ids: string[];
     /**
@@ -375,6 +422,25 @@ export type StartCallRequest = {
      */
     video?: boolean;
 };
+/**
+ * A call not started: why, and — when a call goes on at its place (place_busy) — that call, to join
+ */
+export type StartRefused = {
+    call?: Call;
+    /**
+     * The refusal's name
+     */
+    error: string;
+    /**
+     * What it means
+     */
+    error_description: string;
+    /**
+     * The request's id
+     */
+    request_id?: string;
+    [key: string]: unknown;
+};
 /**
  * A way in for an agent
  */
@@ -517,6 +583,39 @@ export declare function client(t: Transport): {
         body: TicketRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<201, Ticket>>;
+    /**
+     * A place's call
+     *
+     * The call going on at the place, if one is, for a reader the place lets in: one of those in it or asked, or whom the project's rule lets in (a conversation's members for a conversation:<id> place, else the project's hook; with no hook, no one else).
+     */
+    getCallPlace(input: {
+        path: {
+            place: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, PlaceView>>;
+    /**
+     * Watch a place
+     *
+     * The reader is told of the place's call — started, changed, ended (no call) — as the place event on their calls channel, for watch_seconds; an app showing the place asks again before it runs out. Answered with the place's call as it is.
+     */
+    watchCallPlace(input: {
+        path: {
+            place: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, PlaceView>>;
+    /**
+     * Stop watching a place
+     *
+     * The reader is told no more of the place's call.
+     */
+    unwatchCallPlace(input: {
+        path: {
+            place: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
     /**
      * Call settings
      *
@@ -591,13 +690,13 @@ export declare function client(t: Transport): {
     /**
      * Join a group call
      *
-     * Comes into a group call the reader was asked to — rung, missed, declined, or in before — on the device.
+     * Comes into a group call the reader was asked to — rung, missed, declined, or in before — on the device; or, unasked, a call held at a place whose rule lets the reader in.
      */
     joinCall(input: {
         path: {
             call_id: string;
         };
-        body: DeviceRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        body: JoinRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, Call>>;
     /**

package/types/internal/src/modules/machines.d.ts

@@ -210,7 +210,7 @@ export type Machine = {
      */
     replicas: number;
     /**
-     * Kept awake: a machine of a size that sleeps is never put to sleep when idle, and is started again at once when it is asleep — while its environment has paid rights (Pay as you go with a balance), which pays its every hour. Without them it sleeps as any; a dedicated size never sleeps.
+     * Kept awake: a machine of a size that sleeps is never put to sleep when idle, and is started again at once when it is asleep — while its environment has paid rights (Pay as you go), which pays its every hour. Without them it sleeps as any; a dedicated size never sleeps.
      */
     always_on: boolean;
     /**
@@ -303,7 +303,7 @@ export type MachineCreate = {
      */
     replicas?: number;
     /**
-     * Keeps it awake (Machine.always_on): open to an environment on Pay as you go with a balance, refused `always_on_not_available` otherwise.
+     * Keeps it awake (Machine.always_on): open to an environment on Pay as you go, refused `always_on_not_available` otherwise.
      */
     always_on?: boolean;
     /**
@@ -396,7 +396,7 @@ export type MachineUpdate = {
      */
     replicas?: number;
     /**
-     * Whether it is kept awake from now on (Machine.always_on): no version changes. Turning it on is open to an environment on Pay as you go with a balance, refused `always_on_not_available` otherwise.
+     * Whether it is kept awake from now on (Machine.always_on): no version changes. Turning it on is open to an environment on Pay as you go, refused `always_on_not_available` otherwise.
      */
     always_on?: boolean;
     /**
@@ -538,9 +538,13 @@ export type Database = {
      */
     awake_hours?: number;
     /**
-     * How long its size lets it run in a month, in hours: past it, it sleeps until the month ends, and a client is told so. Absent for a size with no such limit.
+     * How long a Free environment's free and preview databases may run in a month between them, in hours (environment_awake_hours): past it, they sleep until the month ends, and a client is told so. Absent for a size with no such limit.
      */
     awake_hours_limit?: number;
+    /**
+     * How long the environment's free and preview databases have run this month between them, deleted ones too, in hours: what awake_hours_limit holds — a database deleted and opened again gets no new hours. Present with awake_hours_limit.
+     */
+    environment_awake_hours?: number;
     /**
      * How much it held when last measured — every database in it summed, the ones its owner made too — measured while it is awake. Absent before its first measure.
      */
@@ -973,9 +977,13 @@ export type DatabaseCreated = {
      */
     awake_hours?: number;
     /**
-     * How long its size lets it run in a month, in hours: past it, it sleeps until the month ends, and a client is told so. Absent for a size with no such limit.
+     * How long a Free environment's free and preview databases may run in a month between them, in hours (environment_awake_hours): past it, they sleep until the month ends, and a client is told so. Absent for a size with no such limit.
      */
     awake_hours_limit?: number;
+    /**
+     * How long the environment's free and preview databases have run this month between them, deleted ones too, in hours: what awake_hours_limit holds — a database deleted and opened again gets no new hours. Present with awake_hours_limit.
+     */
+    environment_awake_hours?: number;
     /**
      * How much it held when last measured — every database in it summed, the ones its owner made too — measured while it is awake. Absent before its first measure.
      */

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

@@ -1,4 +1,5 @@
 import { calls as api } from '../../internal/src/modules/index.js';
+import { PalbaseError } from '../../internal/src/transport.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. */
@@ -22,12 +23,16 @@ export interface RemoteParticipant {
     name: string | null;
     imageUrl: string | null;
     bot: boolean;
-    /** Their audio and video: one stream for the whole call, the same object while they are in it. */
+    /** Their microphone and camera: one stream for the whole call, the same object while they are in it. */
     stream: MediaStream;
     /** Their microphone is heard. */
     audio: boolean;
     /** Their camera is seen. */
     video: boolean;
+    /** The screen they share — its picture, and its sound if they share that — apart from their camera; null while they share none. */
+    screen: MediaStream | null;
+    /** They are heard speaking now (as the media server tells it, a moment behind). */
+    speaking: boolean;
 }
 export interface CallState {
     /** The call as the module last said it (the highest version heard). */
@@ -41,6 +46,12 @@ export interface CallState {
     local: MediaStream | null;
     microphone: boolean;
     camera: boolean;
+    /** This device shares a screen (setScreenShare). */
+    screenSharing: boolean;
+    /** The screen this device shares, for the app's own preview of it; null while it shares none. */
+    screen: MediaStream | null;
+    /** This person is heard speaking now. */
+    speaking: 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`. */
@@ -57,6 +68,12 @@ export interface StartCallOptions {
     group?: boolean;
     /** The conversation it is made from: its members alone may be called, and it keeps the call as a message. */
     conversationId?: string;
+    /**
+     * Holds it at a place (channel:42, conversation:<id>): a group call, whom the project's rule lets into the place
+     * joins unasked; no one need be asked. One call goes on at a place at a time: another is refused with a
+     * PlaceBusyError carrying it, to join. pb.calls.place(name).start says it too.
+     */
+    place?: 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. */
@@ -71,6 +88,20 @@ export interface AnswerOptions {
     /** A microphone (and camera) stream the app opened already; left open when the call ends. */
     media?: MediaStream;
 }
+export interface CallJoinOptions extends AnswerOptions {
+    /** What the others see of this person coming into a place's call unasked, where messaging names them not. */
+    name?: string;
+    /** Their picture there, an https URL. */
+    imageUrl?: string;
+}
+export interface ScreenShareOptions {
+    /** Share the sound of what is shared too (a tab's, where the browser offers it). */
+    audio?: boolean;
+}
+/** A call started at a place: the people asked into it besides (none need be), and the rest as pb.calls.start's. */
+export interface PlaceCallOptions extends Omit<StartCallOptions, 'place' | 'group'> {
+    userIds?: string[];
+}
 export interface HistoryOptions {
     /** 1 to 100; 20 when absent. */
     limit?: number;
@@ -84,11 +115,20 @@ export interface HistoryOptions {
 export interface CallsRTC {
     MediaStream: typeof MediaStream;
     getUserMedia(constraints: MediaStreamConstraints): Promise<MediaStream>;
+    /** A screen, window or tab the person picks: absent where the browser shares none. */
+    getDisplayMedia?(constraints: DisplayMediaStreamOptions): Promise<MediaStream>;
 }
 export interface CallsOptions {
     /** The others' voices play by themselves (true by default): false leaves each RemoteParticipant's stream to the app. */
     playAudio?: boolean;
 }
+/**
+ * A call refused because one goes on at its place already (409 `place_busy`): that call, to join —
+ * pb.calls.join(e.call), or the place's join().
+ */
+export declare class PlaceBusyError extends PalbaseError {
+    readonly call: Call;
+}
 /**
  * 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).
@@ -112,11 +152,16 @@ export declare class CallSession {
     private readonly opened;
     private mic;
     private facing;
+    private shared;
+    private sharing;
     private room;
     private joiningRoom;
     private roomState;
     private readonly streams;
+    private readonly screens;
     private readonly owners;
+    /** Who the media server hears speaking now, by identity. */
+    private speakers;
     private readonly mutedInRoom;
     private readonly players;
     private sink;
@@ -129,8 +174,8 @@ export declare class CallSession {
     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>;
+    /** Comes into a group call this person was asked to (or was in before), or one at a place that lets them in. */
+    join(o?: CallJoinOptions): 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. */
@@ -145,6 +190,12 @@ export declare class CallSession {
     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>;
+    /**
+     * Shares a screen, a window or a tab — the browser asks the person which — or stops sharing it. The others see it
+     * apart from the camera (their RemoteParticipant's screen); the browser's own "stop sharing" stops it here too.
+     * A person who picks none rejects it (NotAllowedError), and nothing is shared.
+     */
+    setScreenShare(on: boolean, o?: ScreenShareOptions): 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. */
@@ -159,6 +210,10 @@ export declare class CallSession {
     private camera;
     /** The camera's track now (null: off): sent to the room in place of the one before. */
     private putVideo;
+    /** The screen shared now (null: none), sent to the room in place of the one before. */
+    private putScreen;
+    /** What this device sends to the room, and what each is. */
+    private sent;
     /** Into the call's room with a ticket of this device's: its microphone (and camera) sent there, the others' heard. */
     private toRoom;
     private streamOf;
@@ -196,22 +251,35 @@ export declare class Calls {
     private readonly sessions;
     private readonly incoming;
     private readonly entered;
+    private readonly places;
     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).
+     * Calls one person (a direct call: their devices ring) or several (a group call), or holds a group call at a place
+     * (o.place), 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:
+     * the project lets this person call them, or hold a call at the place, not), `in_another_call` (409),
+     * `too_many_calls` or `quota_exceeded` (429), `invalid_user_ids`, `invalid_place` or `call_full` (400) — and a
+     * PlaceBusyError (409 `place_busy`) with the call going on at the place.
      */
     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>;
+    /**
+     * Comes into a group call on this device: one this person was asked to — a huddle, one they declined or left — or,
+     * unasked, one held at a place whose rule lets them in (its id, or the call as a place or a PlaceBusyError has it).
+     * Refused with a PalbaseError: `not_allowed` (403: the place lets them not), `call_not_found` (404), `not_joinable`,
+     * `call_ended`, `call_full` or `answered_elsewhere` (409).
+     */
+    join(call: string | Call, o?: CallJoinOptions): Promise<CallSession>;
+    /**
+     * A place calls are held at, as the project names it (channel:42, conversation:<id>): the call going on there, told
+     * as it starts, changes and ends while the place is watched; one handle for each place.
+     */
+    place(name: string): CallPlace;
     /**
      * 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.
@@ -231,6 +299,8 @@ export declare class Calls {
     private stop;
     private unfollow;
     private follow;
+    /** A call to join by its id: as the module has it for this person — or, one they are not in yet, as its place told it. */
+    private toJoin;
     /** 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). */
@@ -241,4 +311,67 @@ export declare class Calls {
     private sessionOf;
     private rtc;
 }
+export interface CallPlaceState {
+    /** The place's name. */
+    place: string;
+    /** The call going on there, as last heard (its people, not their devices); null: none, or not read yet. */
+    call: Call | null;
+    /** This page is told of the place's call as it starts, changes and ends (watch). */
+    watching: boolean;
+    /** The last refusal of reading or watching it: a PalbaseError — `not_allowed` (403) where the project's rule lets this person into the place's calls not. */
+    error: Error | null;
+}
+/**
+ * A place calls are held at (pb.calls.place(name)): the call going on there to draw (subscribe), watched while the
+ * page shows the place — the module tells the person's calls channel of it as it starts, changes and ends — and the
+ * call started or joined there.
+ */
+export declare class CallPlace {
+    readonly place: string;
+    private readonly c;
+    private snapshot;
+    private readonly listeners;
+    private call;
+    private error;
+    /** How many watch it now: the watch is the person's, one for all of this page's. */
+    private watchers;
+    private renewing;
+    private timer;
+    private poll;
+    /** Counts what the channel told: a read that answers "none" after a word heard meanwhile is older than that word. */
+    private words;
+    private readonly ended;
+    get state(): CallPlaceState;
+    /** Listens to every change of state; returns the unsubscribe. */
+    subscribe(listener: Listener): () => void;
+    /** Reads the place's call as it is now (null: none goes on). Refused with a PalbaseError `not_allowed` (403). */
+    refresh(): Promise<Call | null>;
+    /**
+     * Watches the place: told of its call as it starts, changes and ends, renewed while it is watched — until as many
+     * unwatch() as watch() were made. Answers with the call going on there (null: none). Refused with a PalbaseError
+     * `not_allowed` (403).
+     */
+    watch(): Promise<Call | null>;
+    /** Stops watching it (the last of the page's watchers): told no more. */
+    unwatch(): Promise<void>;
+    /**
+     * Starts a group call at the place (no one need be asked), from this device. One goes on there already: a
+     * PlaceBusyError with it — the place's call is it now, to join.
+     */
+    start(o?: PlaceCallOptions): Promise<CallSession>;
+    /** Comes into the call going on at the place, read first when none is known; none there: a PalbaseError `call_not_found` (404). */
+    join(o?: CallJoinOptions): Promise<CallSession>;
+    /** The watch asked again — the place's call read with it — and the next one set before it runs out. */
+    private renew;
+    private later;
+    /** Without the person's channel (realtime off, or not joined yet), a watched place is read. */
+    private polling;
+    private idle;
+    /** A read's answer: its call; or none — unless the channel told of the place meanwhile, which is newer. */
+    private take;
+    private set;
+    private fail;
+    private make;
+    private changed;
+}
 export {};

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

@@ -11,7 +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 { CallPlace, Calls, CallSession, PlaceBusyError, type AnswerOptions, type Call, type CallPage, type CallParticipant, type CallPhase, type CallPlaceState, type CallsOptions, type CallState, type CallJoinOptions, type HistoryOptions, type PlaceCallOptions, type RemoteParticipant, type ScreenShareOptions, 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';