palbase 0.30.0 → 0.32.0

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

@@ -49,10 +49,6 @@ export type Call = {
     metadata: {
         [key: string]: string;
     };
-    /**
-     * Between two devices, or through the media server
-     */
-    mode: "p2p" | "sfu";
     /**
      * Its people and bots
      */
@@ -102,18 +98,14 @@ export type CallEvent = {
      * direct or group
      */
     kind: string;
-    /**
-     * p2p or sfu
-     */
-    mode: string;
     /**
      * user or bot
      */
     participant_kind?: string;
     /**
-     * The call's room on the media server
+     * The call's room on the media server: what an agent's ticket is for
      */
-    room?: string | null;
+    room: string;
     /**
      * The call's state
      */
@@ -174,10 +166,6 @@ export type CallSettings = {
      * How many people (and bots) a call holds
      */
     max_participants: number;
-    /**
-     * Every direct call's media goes through the relay
-     */
-    relay_all: boolean;
 };
 /**
  * What to change (null hook: none)
@@ -195,10 +183,6 @@ export type CallSettingsRequest = {
      * 2 to 100
      */
     max_participants?: number;
-    /**
-     * Relay every direct call
-     */
-    relay_all?: boolean;
 };
 /**
  * The device
@@ -265,40 +249,6 @@ export type HookSettings = {
      */
     url: string;
 };
-/**
- * An ICE candidate
- */
-export type IceCandidate = {
-    /**
-     * The candidate line
-     */
-    candidate: string;
-    /**
-     * Its media section's index
-     */
-    sdp_m_line_index?: number | null;
-    /**
-     * Its media section's id
-     */
-    sdp_mid?: string | null;
-};
-/**
- * A STUN or TURN server
- */
-export type IceServer = {
-    /**
-     * The relay credential
-     */
-    credential?: string;
-    /**
-     * The server's URLs (stun:, turn:, turns:)
-     */
-    urls: string[];
-    /**
-     * The relay credential's name
-     */
-    username?: string;
-};
 /**
  * People to ask in
  */
@@ -313,50 +263,30 @@ export type InviteRequest = {
     user_ids: string[];
 };
 /**
- * How a device's media flows
+ * 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
  */
 export type Media = {
-    /**
-     * A direct call's ICE servers
-     */
-    ice_servers: IceServer[];
-    /**
-     * relay: every packet through the relay
-     */
-    ice_transport_policy: "all" | "relay";
-    /**
-     * Between the two devices, or through the media server
-     */
-    mode: "p2p" | "sfu";
-    /**
-     * This device makes the offer (the caller's); the other answers it
-     */
-    offerer: boolean;
-    /**
-     * Their device
-     */
-    peer_device_id: string | null;
-    /**
-     * The other person of a direct call
-     */
-    peer_user_id: string | null;
     /**
      * The call's room
      */
-    room: string | null;
+    room: string;
     /**
      * The ticket into the call's room
      */
-    token: string | null;
+    token: string;
     /**
      * The media server's url (wss://)
      */
-    url: string | null;
+    url: string;
 };
 /**
  * A person, or a bot, in a call
  */
 export type Participant = {
+    /**
+     * What the media server sent them in the call (bytes): what the call is billed by, as its meter told it (up to a minute behind)
+     */
+    bytes: number;
     /**
      * The device they are in it on (answered on)
      */
@@ -402,80 +332,6 @@ export type Participant = {
      */
     user_id: string;
 };
-/**
- * A signal between a direct call's two devices: an offer or an answer carries its sdp, a candidate its candidate
- */
-export type Signal = {
-    /**
-     * The call
-     */
-    call_id: string;
-    candidate?: IceCandidate;
-    /**
-     * When it was sent
-     */
-    created_at: string;
-    /**
-     * From which device
-     */
-    from_device_id: string;
-    /**
-     * Who sent it
-     */
-    from_user_id: string;
-    /**
-     * An offer's or an answer's SDP (absent on a candidate or a bye)
-     */
-    sdp?: string;
-    /**
-     * Its place in the call's order
-     */
-    seq: number;
-    /**
-     * For which device
-     */
-    to_device_id: string;
-    /**
-     * What it is
-     */
-    type: "offer" | "answer" | "candidate" | "bye";
-};
-/**
- * Signals
- */
-export type SignalList = {
-    /**
-     * The signals, in order
-     */
-    signals: Signal[];
-};
-/**
- * A signal to the other device
- */
-export type SignalRequest = {
-    candidate?: IceCandidate;
-    /**
-     * The device sending it
-     */
-    device_id: string;
-    /**
-     * An offer's or an answer's SDP (32 KiB at most)
-     */
-    sdp?: string | null;
-    /**
-     * What it is
-     */
-    type: "offer" | "answer" | "candidate" | "bye";
-};
-/**
- * A signal kept
- */
-export type SignalSent = {
-    /**
-     * Its place in the call's order
-     */
-    seq: number;
-};
 /**
  * A call to make
  */
@@ -606,7 +462,7 @@ export declare function client(t: Transport): {
     /**
      * Call people
      *
-     * Rings one person (a direct call, between the two devices) or asks several into a group call (on the media server), from the caller's device. `ring: false` makes a group call that rings no one: the people asked join it when they like (a huddle). A call to someone who is calling the caller this moment is that call, answered (200). A call to someone in another call — or being rung by one — ends at once, `busy`, and they hear they missed it. Who may be called is the project's: no one who blocked the caller or whom they blocked, no deleted account, a conversation's members alone when it names one (`conversation_id`), and whom the project's hook allows (`calls.can_call`). A call from a conversation is kept in it, as a `call` message.
+     * Rings one person (a direct call) or asks several into a group call, from the caller's device; either is a room on the media server, which the caller's device is in from the start (`POST /calls/{call_id}/media`). `ring: false` makes a group call that rings no one: the people asked join it when they like (a huddle). A call to someone who is calling the caller this moment is that call, answered (200). A call to someone in another call — or being rung by one — ends at once, `busy`, and they hear they missed it. Who may be called is the project's: no one who blocked the caller or whom they blocked, no deleted account, a conversation's members alone when it names one (`conversation_id`), and whom the project's hook allows (`calls.can_call`). A call from a conversation is kept in it, as a `call` message.
      */
     startCall(input: {
         body: StartCallRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
@@ -652,7 +508,7 @@ export declare function client(t: Transport): {
     /**
      * Let an agent in
      *
-     * Lets the project's agent into the call as a bot: a participant everyone in it hears (and sees), listed as a bot (`kind` bot; on the media server, an agent). The ticket is the media server's url and an access token its open-source client and agent libraries connect with as they are — LiveKit's: the agent receives each person's audio as a track of its own, named by their user id, and publishes its own. A direct call between two devices moves to the media server for it, going on. Palbase runs no agent: transcribing, answering, taking notes are the agent's. The `calls.call.started` and `calls.participant.joined` webhooks are when to send one in.
+     * Lets the project's agent into the call as a bot: a participant everyone in it hears (and sees), listed as a bot (`kind` bot; on the media server, an agent). The ticket is the media server's url and an access token its open-source client and agent libraries connect with as they are — LiveKit's: the agent receives each person's audio as a track of its own, named by their user id, and publishes its own. What the media server sends it is billed as anyone's; past a Free project's call data no new agent comes in (`429 quota_exceeded`), one in the call already gets its way back in. Palbase runs no agent: transcribing, answering, taking notes are the agent's. The `calls.call.started` and `calls.participant.joined` webhooks are when to send one in.
      */
     createCallTicket(input: {
         path: {
@@ -672,7 +528,7 @@ export declare function client(t: Transport): {
     /**
      * Set call settings
      *
-     * What it names changes: how many people (and bots) a call holds (2 to 100), whether every direct call's media goes through the relay (no one learns another's address, at the price of a hop), how many calls a person may start in an hour, and the hook asked whom one may call (`calls.can_call`; null: none). A hook set for the first time is given its signing secret, here, once.
+     * What it names changes: how many people (and bots) a call holds (2 to 100), how many calls a person may start in an hour, and the hook asked whom one may call (`calls.can_call`; null: none). A hook set for the first time is given its signing secret, here, once.
      */
     putCallSettings(input: {
         body: CallSettingsRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
@@ -758,7 +614,7 @@ export declare function client(t: Transport): {
     /**
      * How the media flows
      *
-     * How the device's media flows in the call it is in. A direct call (`p2p`): the ICE servers its connection uses — STUN, and the relay with a credential of the device's own, revoked as it leaves — whether every packet goes through the relay (`ice_transport_policy` relay, the project's `relay_all`), and whether this device makes the offer. A group (`sfu`): the media server's url and a ticket into the call's room.
+     * A ticket into the call's room on the platform's media server, where every call's media flows — one to one or in a group — for the device the reader is in the call on: the media server's url, the ticket, the room. What the media server sends the call's people is what the project's calls are billed by.
      */
     getCallMedia(input: {
         path: {
@@ -770,7 +626,7 @@ export declare function client(t: Transport): {
     /**
      * Ask more people in
      *
-     * Asks more people into a call the reader is in, ringing them (or not: `ring: false`). A direct call becomes a group on the media server: its devices are told (`mode` sfu on their channel) and move there, the call going on.
+     * Asks more people into a call the reader is in, ringing them (or not: `ring: false`). A direct call becomes a group, going on in the same room.
      */
     inviteToCall(input: {
         path: {
@@ -779,32 +635,5 @@ export declare function client(t: Transport): {
         body: InviteRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, Call>>;
-    /**
-     * Signals missed
-     *
-     * The signals for the device after `after` (the last seq it has), in order: what it missed of what was told.
-     */
-    listCallSignals(input: {
-        path: {
-            call_id: string;
-        };
-        query: {
-            device_id: string; /** The last seq the device has (0: from the first) */
-            after?: number;
-        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
-        signal?: AbortSignal;
-    }): Promise<Reply<200, SignalList>>;
-    /**
-     * Signal the other device
-     *
-     * An offer, an answer, a candidate or a goodbye for the other device of a direct call — kept for it, and told to it on its channel (`signal`) as it is sent. Nothing goes before the call is answered: no address leaves a device for someone who did not pick up.
-     */
-    sendCallSignal(input: {
-        path: {
-            call_id: string;
-        };
-        body: SignalRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
-        signal?: AbortSignal;
-    }): Promise<Reply<202, SignalSent>>;
 };
 export type Client = ReturnType<typeof client>;

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

@@ -307,7 +307,7 @@ export type MachineCreate = {
      */
     always_on?: boolean;
     /**
-     * Whether a pull request opened against its branch is previewed: its head built into a machine of its own, <name>-pr<n>, in this environment, with this environment's settings and secrets, answering at <name>-pr<n>-<ref> until the pull request closes; the pull request is told where in a comment. Turn it on in an environment kept for previews, not production's: the pull request's code runs with the environment's secrets. A machine read with Palbase's GitHub App alone (source.access app).
+     * Whether a pull request opened against its branch is previewed: its head built into a machine of its own, <name>-pr<n>, in this environment, with this environment's settings and secrets, answering at <name>-pr<n>-<ref> until the pull request closes; the pull request is told where in a comment. Turn it on in an environment kept for previews, not production's: the pull request's code runs with the environment's secrets. A machine read with a platform's tokens (source.access token) previews what its platform puts (PUT /machines/{name}/previews/{pull_request}), no comment written.
      */
     previews?: boolean;
     /**
@@ -1857,6 +1857,23 @@ export type PreviewOpened = {
      */
     commit: string;
 };
+/**
+ * A platform's pull request: its branch — one of the machine's repository's own — the head its machine's preview builds, and the token it is read with.
+ */
+export type PreviewDeploy = {
+    /**
+     * The pull request's branch, of the machine's repository itself: a fork's pull request is not built with the environment's secrets.
+     */
+    branch: string;
+    /**
+     * The branch's head, its full SHA: a newer push answers 409 commit_not_head. Left out, the branch's head.
+     */
+    commit?: string;
+    /**
+     * A GitHub App installation's token (ghs_…) for the machine's repository alone, read-only: used once, never kept.
+     */
+    git_access_token: string;
+};
 /** Palbase Machines */
 export declare function client(t: Transport): {
     /**
@@ -2024,6 +2041,31 @@ export declare function client(t: Transport): {
         }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, PreviewList>>;
+    /**
+     * Open or update a platform's pull request preview
+     *
+     * For a machine read with a platform's tokens (source.access token: PalCore's, whose repositories have no Palbase App, so no pull request is heard here): opens the preview of the pull request at the head of its branch — one of the machine's repository's own: a fork's is not built — its own machine, <name>-pr<n>, and a database of its own when the machine runs its database's migrations — or builds the open one at it, and opens one that went idle again. The branch is read with git_access_token, a GitHub App installation's token for the machine's repository alone (ghs_…), once; a commit named must be the branch's head (409 commit_not_head). Its address and state are read with GET /machines/{name}/previews; the platform tells its pull request itself. Refused in a production environment (409 previews_in_production), for a machine read with Palbase's GitHub App (409 previews_from_github), with previews off (409 previews_off), and when the environment's limits refuse the preview (409 preview_refused, with why).
+     */
+    putMachinePreview(input: {
+        path: {
+            name: string; /** The pull request's number. */
+            pull_request: number;
+        };
+        body: PreviewDeploy; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<202, PreviewOpened>>;
+    /**
+     * Close a platform's pull request preview
+     *
+     * For a machine read with a platform's tokens: closes the preview of the pull request, its pull request closed — its machine and its own database are deleted at once. A machine read with Palbase's GitHub App has its previews closed as GitHub tells (409 previews_from_github).
+     */
+    deleteMachinePreview(input: {
+        path: {
+            name: string; /** The pull request's number. */
+            pull_request: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
     /**
      * List a machine's domains
      *
@@ -2721,7 +2763,7 @@ export declare function client(t: Transport): {
     /**
      * Open a machine's pull request preview again
      *
-     * Opens a machine's preview of an open pull request again, at the pull request's head: one closed for want of a push (state idle: no push for 3 days, its machine and its own database taken away) or refused at its last push (state refused) is made anew, with a new, empty database of its own when the machine runs its database's migrations. One open goes on as it is, and its 3 days start again. A fork's preview under fork protection opens only at a head an admin authorized (409 preview_waits_authorization); one the environment's limits refuse again answers 409 preview_refused, with why.
+     * Opens a machine's preview of an open pull request again, at the pull request's head: one closed for want of a push (state idle: no push for 3 days, its machine and its own database taken away) or refused at its last push (state refused) is made anew, with a new, empty database of its own when the machine runs its database's migrations. One open goes on as it is, and its 3 days start again. A fork's preview under fork protection opens only at a head an admin authorized (409 preview_waits_authorization); one the environment's limits refuse again answers 409 preview_refused, with why. A machine read with a platform's tokens has an idle or refused preview opened again by its platform, with a token (PUT /machines/{name}/previews/{pull_request}): 409 preview_needs_token.
      */
     openMachinePreview(input: {
         path: {

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

@@ -22,7 +22,7 @@ export interface RemoteParticipant {
     name: string | null;
     imageUrl: string | null;
     bot: boolean;
-    /** Their audio and video: one stream for the whole call, whichever way the media flows. */
+    /** Their audio and video: one stream for the whole call, the same object while they are in it. */
     stream: MediaStream;
     /** Their microphone is heard. */
     audio: boolean;
@@ -37,8 +37,6 @@ export interface CallState {
     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;
@@ -64,15 +62,13 @@ export interface StartCallOptions {
     /** 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;
+    /** A microphone (and camera) stream the app opened already; left open when the call ends. */
     media?: MediaStream;
 }
 export interface HistoryOptions {
@@ -86,16 +82,10 @@ export interface HistoryOptions {
 }
 /** 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;
 }
@@ -116,28 +106,17 @@ export declare class CallSession {
     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 owners;
     private readonly mutedInRoom;
     private readonly players;
     private sink;
@@ -156,7 +135,7 @@ export declare class CallSession {
     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. */
+    /** Asks more people in (ringing them unless ring is false): a direct call becomes a group, going on in the same room. */
     invite(userIds: string | string[], o?: {
         ring?: boolean;
     }): Promise<void>;
@@ -178,18 +157,9 @@ export declare class CallSession {
     /** 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. */
+    /** The camera's track now (null: off): sent to the room in place of the one before. */
     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;
+    /** 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;
     private heard;

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

@@ -72,7 +72,7 @@ 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). */
+    /** How the signed-in person's calls go (pb.calls): the others' voices played by themselves (playAudio). */
     calls?: CallsOptions;
 }
 /**