palbase 0.27.0 → 0.28.0

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

@@ -0,0 +1,810 @@
+import { type Reply, type Transport } from '../transport.js';
+/**
+ * A call
+ */
+export type Call = {
+    /**
+     * When a direct call was answered
+     */
+    answered_at: string | null;
+    /**
+     * Who called
+     */
+    caller_id: string;
+    /**
+     * The conversation it was made from (kept there as a call message)
+     */
+    conversation_id: string | null;
+    /**
+     * When it was made
+     */
+    created_at: string;
+    /**
+     * Why it ended
+     */
+    end_reason: string | null;
+    /**
+     * When it ended
+     */
+    ended_at: string | null;
+    /**
+     * Who ended it (hung up, canceled, declined; whose device went silent)
+     */
+    ended_by: string | null;
+    /**
+     * The call's id
+     */
+    id: string;
+    /**
+     * Two people, or a group
+     */
+    kind: "direct" | "group";
+    /**
+     * How many it holds
+     */
+    max_participants: number;
+    /**
+     * The caller's app's own words about the call (shown to the people rung)
+     */
+    metadata: {
+        [key: string]: string;
+    };
+    /**
+     * Between two devices, or through the media server
+     */
+    mode: "p2p" | "sfu";
+    /**
+     * Its people and bots
+     */
+    participants: Participant[];
+    /**
+     * Whether it rings the people asked (false: a huddle they join)
+     */
+    ring: boolean;
+    /**
+     * When a direct call's ring ends, unanswered
+     */
+    ring_until: string | null;
+    /**
+     * Ringing (a direct call not answered yet), going on, or over
+     */
+    state: "ringing" | "active" | "ended";
+    /**
+     * Grows with every change: keep the highest seen
+     */
+    version: number;
+    /**
+     * A video call (else voice)
+     */
+    video: boolean;
+};
+/**
+ * What a calls webhook says of a call
+ */
+export type CallEvent = {
+    /**
+     * The call
+     */
+    call_id: string;
+    /**
+     * Who called
+     */
+    caller_id: string;
+    /**
+     * The conversation it was made from
+     */
+    conversation_id: string | null;
+    /**
+     * Why it ended (ended)
+     */
+    end_reason?: string;
+    /**
+     * direct or group
+     */
+    kind: string;
+    /**
+     * p2p or sfu
+     */
+    mode: string;
+    /**
+     * user or bot
+     */
+    participant_kind?: string;
+    /**
+     * The call's room on the media server
+     */
+    room?: string | null;
+    /**
+     * The call's state
+     */
+    state: string;
+    /**
+     * The participant (joined, left)
+     */
+    user_id?: string;
+    /**
+     * A video call
+     */
+    video: boolean;
+};
+/**
+ * A page of calls
+ */
+export type CallPage = {
+    /**
+     * The calls
+     */
+    calls: Call[];
+    /**
+     * The next page's cursor; absent on the last
+     */
+    next_cursor?: string;
+};
+/**
+ * A refusal, with the call as it is
+ */
+export type CallRefused = {
+    call: Call;
+    /**
+     * The refusal's name
+     */
+    error: string;
+    /**
+     * What it means
+     */
+    error_description: string;
+};
+/**
+ * How the project runs its calls
+ */
+export type CallSettings = {
+    /**
+     * How many calls one person may start in an hour
+     */
+    calls_per_hour: number;
+    /**
+     * The hook asked whom one may call; null: anyone may call anyone (blocks aside)
+     */
+    hook: HookSettings | null;
+    /**
+     * The hook's signing secret: here once, as it is made
+     */
+    hook_secret?: string;
+    /**
+     * 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)
+ */
+export type CallSettingsRequest = {
+    /**
+     * 1 to 1,000
+     */
+    calls_per_hour?: number;
+    /**
+     * The hook to ask; null removes it
+     */
+    hook?: HookSettings | null;
+    /**
+     * 2 to 100
+     */
+    max_participants?: number;
+    /**
+     * Relay every direct call
+     */
+    relay_all?: boolean;
+};
+/**
+ * The device
+ */
+export type DeviceRequest = {
+    /**
+     * The device (the app's install) it is done on
+     */
+    device_id: string;
+};
+/**
+ * An error
+ */
+export type ErrorResponse = {
+    /**
+     * The error's name
+     */
+    error: string;
+    /**
+     * What it means
+     */
+    error_description: string;
+    /**
+     * The request's id
+     */
+    request_id?: string;
+    [key: string]: unknown;
+};
+/**
+ * A call's state, as a heartbeat finds it
+ */
+export type Heartbeat = {
+    /**
+     * Why it ended
+     */
+    end_reason: string | null;
+    /**
+     * The reader is in it on this device
+     */
+    in_call: boolean;
+    /**
+     * The call's state
+     */
+    state: "ringing" | "active" | "ended";
+    /**
+     * The call's version
+     */
+    version: number;
+};
+/**
+ * The hook
+ */
+export type HookSettings = {
+    /**
+     * A hook that does not answer: refuse the call, or let it
+     */
+    on_error?: "deny" | "allow";
+    /**
+     * How long it is waited for (100 to 5,000; 2,000)
+     */
+    timeout_ms?: number;
+    /**
+     * The project's endpoint, asked whom one may call
+     */
+    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
+ */
+export type InviteRequest = {
+    /**
+     * Ring them (true, by default)
+     */
+    ring?: boolean;
+    /**
+     * Who to ask in
+     */
+    user_ids: string[];
+};
+/**
+ * How a device's media flows
+ */
+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;
+    /**
+     * The ticket into the call's room
+     */
+    token: string | null;
+    /**
+     * The media server's url (wss://)
+     */
+    url: string | null;
+};
+/**
+ * A person, or a bot, in a call
+ */
+export type Participant = {
+    /**
+     * The device they are in it on (answered on)
+     */
+    device_id: string | null;
+    /**
+     * Their picture
+     */
+    image_url: string | null;
+    /**
+     * When they were rung or asked
+     */
+    invited_at: string;
+    /**
+     * When their present stretch in the call began
+     */
+    joined_at: string | null;
+    /**
+     * A person, or the project's agent
+     */
+    kind: "user" | "bot";
+    /**
+     * When they last left
+     */
+    left_at: string | null;
+    /**
+     * Their name, as their profile shows it
+     */
+    name: string | null;
+    /**
+     * The one who called, the one called (a direct call), or a member
+     */
+    role: "caller" | "callee" | "member";
+    /**
+     * How long they have been in it, their stretches before the present one summed
+     */
+    seconds: number;
+    /**
+     * Where they are in the call: rung, asked (a call that does not ring), in it, left, turned it down, missed it, busy
+     */
+    state: "ringing" | "invited" | "joined" | "left" | "declined" | "missed" | "busy";
+    /**
+     * The person's id — or a bot's identity (bot:<identity>)
+     */
+    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
+ */
+export type StartCallRequest = {
+    /**
+     * The caller's picture to show those rung
+     */
+    caller_image_url?: string | null;
+    /**
+     * The caller's name to show those rung (else their messaging profile's)
+     */
+    caller_name?: string | null;
+    /**
+     * The conversation it is made from: its members alone may be called, and it keeps the call
+     */
+    conversation_id?: string | null;
+    /**
+     * The device the call is made on
+     */
+    device_id: string;
+    /**
+     * A group call even with one person asked (others may be asked later): on the media server
+     */
+    group?: boolean;
+    /**
+     * The app's own words about the call (32 strings, 2 KiB at most)
+     */
+    metadata?: {
+        [key: string]: string;
+    };
+    /**
+     * 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)
+     */
+    user_ids: string[];
+    /**
+     * A video call (else voice)
+     */
+    video?: boolean;
+};
+/**
+ * A way in for an agent
+ */
+export type Ticket = {
+    call: Call;
+    /**
+     * When the token ends
+     */
+    expires_at: string;
+    /**
+     * The agent's identity in the call
+     */
+    identity: string;
+    /**
+     * The call's room
+     */
+    room: string;
+    /**
+     * The access token the agent connects with
+     */
+    token: string;
+    /**
+     * The media server's url (wss://)
+     */
+    url: string;
+};
+/**
+ * An agent to let in
+ */
+export type TicketRequest = {
+    /**
+     * It speaks (and shows) too (true, by default); false: it listens only
+     */
+    can_publish?: boolean;
+    /**
+     * The agent's identity in the call (bot:<identity>): 1 to 64 letters, digits, _ . -
+     */
+    identity: string;
+    /**
+     * Its own words (32 strings, 2 KiB at most)
+     */
+    metadata?: {
+        [key: string]: string;
+    };
+    /**
+     * Its name, as the call lists it
+     */
+    name?: string | null;
+};
+/** The events this module sends the project's webhooks (x-palbase-events), by type: each one's payload, the event's data. */
+export interface Events {
+    /**
+     * calls.call.ended: a call ended (end_reason says why).
+     */
+    "calls.call.ended": CallEvent;
+    /**
+     * calls.call.started: a call was made — ringing, or a group going on.
+     */
+    "calls.call.started": CallEvent;
+    /**
+     * calls.participant.joined: a person answered or joined, or a bot came into the room.
+     */
+    "calls.participant.joined": CallEvent;
+    /**
+     * calls.participant.left: a person or a bot left the call.
+     */
+    "calls.participant.left": CallEvent;
+}
+/** Palbase Calls */
+export declare function client(t: Transport): {
+    /**
+     * My calls
+     *
+     * The reader's calls, newest first: their history, with how each went for them (their participant's state — `missed` among them).
+     */
+    listCalls(input?: {
+        query?: {
+            limit?: number; /** The previous page's next_cursor */
+            cursor?: string; /** Only the calls the person missed (or was busy for) */
+            missed?: boolean; /** Only the calls in this state */
+            state?: "ringing" | "active" | "ended";
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CallPage>>;
+    /**
+     * 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.
+     */
+    startCall(input: {
+        body: StartCallRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Call> | Reply<201, Call>>;
+    /**
+     * The project's calls
+     *
+     * The project's calls, newest first; `user_id`, a person's (`missed` with it, the ones they missed); `state`, those in it.
+     */
+    adminListCalls(input?: {
+        query?: {
+            limit?: number; /** The previous page's next_cursor */
+            cursor?: string; /** A person's calls */
+            user_id?: string; /** Only the calls the person missed (or was busy for) */
+            missed?: boolean; /** Only the calls in this state */
+            state?: "ringing" | "active" | "ended";
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CallPage>>;
+    /**
+     * A call
+     *
+     * A call of the project's, as it is now.
+     */
+    adminGetCall(input: {
+        path: {
+            call_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Call>>;
+    /**
+     * End a call
+     *
+     * Ends the call for everyone in it (`ended`): their apps are told, its room closes.
+     */
+    adminEndCall(input: {
+        path: {
+            call_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Call>>;
+    /**
+     * 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.
+     */
+    createCallTicket(input: {
+        path: {
+            call_id: string;
+        };
+        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>>;
+    /**
+     * Call settings
+     *
+     * How the project runs its calls. The hook's secret is never read back.
+     */
+    getCallSettings(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CallSettings>>;
+    /**
+     * 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.
+     */
+    putCallSettings(input: {
+        body: CallSettingsRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CallSettings>>;
+    /**
+     * A new hook secret
+     *
+     * The hook's signing secret made anew, given here once; the old one signs nothing more.
+     */
+    rotateCallHookSecret(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CallSettings>>;
+    /**
+     * A call
+     *
+     * A call of the reader's, as it is now. An app that missed a word on its channel reads the call here.
+     */
+    getCall(input: {
+        path: {
+            call_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Call>>;
+    /**
+     * Answer a call
+     *
+     * Answers the call on the device: the first of the person's devices to answer has it, and their others stop ringing (the call's snapshot on their channel; a silent push to an Android device woken by the ring). A device that lost its last call (its app killed) answers on: that call ends.
+     */
+    acceptCall(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. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Call>>;
+    /**
+     * Turn a call down
+     *
+     * Turns the call down on every device of the reader's: a direct call ends (`declined`); in a group, the reader is not rung any more and may still join.
+     */
+    declineCall(input: {
+        path: {
+            call_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Call>>;
+    /**
+     * Still in the call
+     *
+     * The device saying it is still in the call — every 15 seconds while it is; a device silent 45 seconds is taken for gone (a direct call ends, `failed`). It answers the call's state and version: an app whose snapshot is older reads the call.
+     */
+    callHeartbeat(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. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Heartbeat>>;
+    /**
+     * Join a group call
+     *
+     * Comes into a group call the reader was asked to — rung, missed, declined, or in before — on the device.
+     */
+    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. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Call>>;
+    /**
+     * Hang up
+     *
+     * Takes the reader out of the call. A direct call ends for both — `canceled` while it rings (the person called missed it), `hung_up` once answered; a group goes on while a person is in it or being rung. Leaving a call that is over is done.
+     */
+    leaveCall(input: {
+        path: {
+            call_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Call>>;
+    /**
+     * 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.
+     */
+    getCallMedia(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. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Media>>;
+    /**
+     * 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.
+     */
+    inviteToCall(input: {
+        path: {
+            call_id: string;
+        };
+        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>;