@babelforce/babelconnect-sdk 0.1.0 → 0.7.0

package/README.md

@@ -22,7 +22,7 @@ messaging) on top of `babelconnect-server`. Two ways to use it:
 npm install @babelforce/babelconnect-sdk
 ```
 
-ESM-only, targets ES2022. Runs in modern browsers; Node 18+ for control-only (no-audio) use. Native WebRTC
+ESM-only, targets ES2022. Runs in modern browsers; Node 20+ for control-only (no-audio) use. Native WebRTC
 audio requires a browser (microphone permission).
 
 ## Quickstart — programmatic client (with audio)
@@ -90,8 +90,10 @@ bc.session.set({ number: "+49301234567" }); // correlate / prefill
 (`setPresence`, `setDisplayAs`, `setAgentNumber`, `setWebrtc`), and history/contacts fetches (`getHistory`,
 `getSmsThread`, `getPhonebook`).
 
-Full API reference and the embedding guide:
-**[babelconnect-sdk-docs](https://babelforce.github.io/babelconnect-sdk-docs/)**.
+Full docs — API reference, guides, and the embedding guide:
+**[babelconnect SDK docs](https://babelforce.github.io/babelconnect-sdk/)**. Good starting points:
+the **[tutorial](https://babelforce.github.io/babelconnect-sdk/docs/tutorial/first-softphone)** and,
+if you hit a snag, **[troubleshooting](https://babelforce.github.io/babelconnect-sdk/docs/guides/troubleshooting)**.
 
 ## How it works
 

package/dist/auth.d.ts

@@ -1,3 +1,59 @@
+/** The default OAuth public client id for the babelconnect agent app (no secret; PKCE). */
+export declare const DEFAULT_CLIENT_ID = "babelconnect";
+/** A parsed OAuth token response: the bearer plus, when the grant returns them, the rotating refresh token and the access-token lifetime (seconds). */
+export interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    token_type?: string;
+}
+/** A PKCE code verifier + S256 challenge (RFC 7636). */
+export interface PkceChallenge {
+    /** The high-entropy secret to keep client-side and send with {@link authorizationCodeGrant}. */
+    codeVerifier: string;
+    /** The base64url(SHA-256(codeVerifier)) value to send with {@link buildAuthorizeUrl}. */
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}
+/**
+ * Generate a PKCE code verifier + S256 challenge (RFC 7636). Pass `codeChallenge` to
+ * {@link buildAuthorizeUrl} and keep `codeVerifier` to later exchange the returned code via
+ * {@link authorizationCodeGrant}. Uses the Web Crypto API (Node 18+ / browsers).
+ */
+export declare function pkceChallenge(): Promise<PkceChallenge>;
+export interface AuthorizeUrlOptions {
+    /** babelconnect-server origin (the same one used for gRPC-web); the authorize endpoint lives on the backend behind the same origin. */
+    serverUrl: string;
+    /** OAuth client id (defaults to {@link DEFAULT_CLIENT_ID} = `"babelconnect"`). */
+    clientId?: string;
+    /** The registered callback URL the backend redirects to with the code. */
+    redirectUri: string;
+    /** OAuth scope (e.g. `"*"`). */
+    scope: string;
+    codeChallenge: string;
+    /** Opaque CSRF token echoed back by the backend; verify it on return. */
+    state?: string;
+    codeChallengeMethod?: "S256" | "plain";
+}
+/**
+ * Build the `GET {serverUrl}/oauth/authorize` URL that starts the Authorization Code + PKCE flow.
+ * Redirect the user to it; the backend redirects back to `redirectUri` with a `code` (and `state`).
+ */
+export declare function buildAuthorizeUrl(opts: AuthorizeUrlOptions): string;
+/**
+ * Exchange an authorization `code` (from the PKCE consent redirect) for tokens via the
+ * authorization_code grant against `POST {serverUrl}/oauth/token`. Public clients pass only
+ * `codeVerifier` (no secret). Returns the access token (and a rotating refresh token when the
+ * backend grants offline access) — pass `access_token` to {@link BabelconnectClient.connect}.
+ */
+export declare function authorizationCodeGrant(opts: {
+    serverUrl: string;
+    code: string;
+    redirectUri: string;
+    clientId?: string;
+    codeVerifier: string;
+    clientSecret?: string;
+}): Promise<TokenResponse>;
 /**
  * Exchange an agent email/password for a bearer token via babelconnect-server's
  * OAuth password-grant endpoint (`POST {serverUrl}/oauth/token`).
@@ -19,3 +75,23 @@ export declare function passwordGrant(opts: {
     pass: string;
     clientId?: string;
 }): Promise<string>;
+/**
+ * Revoke an OAuth token on sign-out (RFC 7009) via babelconnect-server's
+ * `POST {serverUrl}/oauth/revoke` (proxied same-origin like `/oauth/token`).
+ *
+ * Form-urlencoded `token` (+ `token_type_hint` and optional `clientId`); the
+ * bearer is also carried for backends that authenticate the revoke. Best-effort:
+ * revocation returns 200 even for an unknown token, so a non-2xx is ignored (the
+ * session is ending regardless) — only a transport error rejects.
+ *
+ * @param opts.serverUrl babelconnect-server origin, e.g. `https://agent.example.com`
+ * @param opts.token the token to revoke (also sent as the bearer)
+ * @param opts.tokenTypeHint RFC 7009 hint (defaults to `"access_token"`)
+ * @param opts.clientId optional OAuth client id
+ */
+export declare function revokeToken(opts: {
+    serverUrl: string;
+    token: string;
+    tokenTypeHint?: string;
+    clientId?: string;
+}): Promise<void>;

package/dist/auth.js

@@ -1,3 +1,68 @@
+/** The default OAuth public client id for the babelconnect agent app (no secret; PKCE). */
+export const DEFAULT_CLIENT_ID = "babelconnect";
+/** base64url-encode bytes without padding (RFC 4648 §5) — the encoding PKCE requires. */
+function base64url(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+ * Generate a PKCE code verifier + S256 challenge (RFC 7636). Pass `codeChallenge` to
+ * {@link buildAuthorizeUrl} and keep `codeVerifier` to later exchange the returned code via
+ * {@link authorizationCodeGrant}. Uses the Web Crypto API (Node 18+ / browsers).
+ */
+export async function pkceChallenge() {
+    const codeVerifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(codeVerifier));
+    return { codeVerifier, codeChallenge: base64url(new Uint8Array(digest)), codeChallengeMethod: "S256" };
+}
+/**
+ * Build the `GET {serverUrl}/oauth/authorize` URL that starts the Authorization Code + PKCE flow.
+ * Redirect the user to it; the backend redirects back to `redirectUri` with a `code` (and `state`).
+ */
+export function buildAuthorizeUrl(opts) {
+    const base = opts.serverUrl.replace(/\/+$/, "");
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: opts.clientId ?? DEFAULT_CLIENT_ID,
+        redirect_uri: opts.redirectUri,
+        scope: opts.scope,
+        code_challenge: opts.codeChallenge,
+        code_challenge_method: opts.codeChallengeMethod ?? "S256",
+    });
+    if (opts.state !== undefined)
+        params.set("state", opts.state);
+    return `${base}/oauth/authorize?${params.toString()}`;
+}
+/**
+ * Exchange an authorization `code` (from the PKCE consent redirect) for tokens via the
+ * authorization_code grant against `POST {serverUrl}/oauth/token`. Public clients pass only
+ * `codeVerifier` (no secret). Returns the access token (and a rotating refresh token when the
+ * backend grants offline access) — pass `access_token` to {@link BabelconnectClient.connect}.
+ */
+export async function authorizationCodeGrant(opts) {
+    const base = opts.serverUrl.replace(/\/+$/, "");
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code: opts.code,
+        redirect_uri: opts.redirectUri,
+        client_id: opts.clientId ?? DEFAULT_CLIENT_ID,
+        code_verifier: opts.codeVerifier,
+    });
+    if (opts.clientSecret !== undefined)
+        body.set("client_secret", opts.clientSecret);
+    const resp = await fetch(`${base}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    });
+    const json = (await resp.json().catch(() => ({})));
+    if (!resp.ok || !json.access_token) {
+        throw new Error(`authorization_code grant failed (status ${resp.status})`);
+    }
+    return json;
+}
 /**
  * Exchange an agent email/password for a bearer token via babelconnect-server's
  * OAuth password-grant endpoint (`POST {serverUrl}/oauth/token`).
@@ -32,3 +97,34 @@ export async function passwordGrant(opts) {
     }
     return json.access_token;
 }
+/**
+ * Revoke an OAuth token on sign-out (RFC 7009) via babelconnect-server's
+ * `POST {serverUrl}/oauth/revoke` (proxied same-origin like `/oauth/token`).
+ *
+ * Form-urlencoded `token` (+ `token_type_hint` and optional `clientId`); the
+ * bearer is also carried for backends that authenticate the revoke. Best-effort:
+ * revocation returns 200 even for an unknown token, so a non-2xx is ignored (the
+ * session is ending regardless) — only a transport error rejects.
+ *
+ * @param opts.serverUrl babelconnect-server origin, e.g. `https://agent.example.com`
+ * @param opts.token the token to revoke (also sent as the bearer)
+ * @param opts.tokenTypeHint RFC 7009 hint (defaults to `"access_token"`)
+ * @param opts.clientId optional OAuth client id
+ */
+export async function revokeToken(opts) {
+    const base = opts.serverUrl.replace(/\/+$/, "");
+    const body = new URLSearchParams({
+        token: opts.token,
+        token_type_hint: opts.tokenTypeHint ?? "access_token",
+    });
+    if (opts.clientId)
+        body.set("client_id", opts.clientId);
+    await fetch(`${base}/oauth/revoke`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Authorization: `Bearer ${opts.token}`,
+        },
+        body,
+    });
+}

package/dist/client.d.ts

@@ -8,7 +8,7 @@ export interface ConnectOptions {
     token: string;
     /** Per-call WebRTC leg. Defaults to {@link browserMediaFactory}; pass `null` for a control-only client. */
     mediaFactory?: MediaFactory | null;
-    /** Auto-answer the agent's own OUTBOUND ringing leg (default `true`). INBOUND waits for {@link answerCall}. */
+    /** Auto-answer the agent's own OUTBOUND ringing leg (default `true`). INBOUND waits for {@link BabelconnectClient.answerCall}. */
     autoAnswer?: boolean;
     /** Out-of-band server notices (command rejections) + local media failures. */
     onError?: (err: BcError) => void;
@@ -34,7 +34,18 @@ export declare class BabelconnectClient {
     private readonly pending;
     private closed;
     private constructor();
-    /** Open the session and start mirroring server state. */
+    /**
+     * Open the session and start mirroring server state. Returns synchronously and queues intents until the
+     * stream is live, so you can subscribe and register immediately.
+     *
+     * @example
+     * ```ts
+     * const bc = BabelconnectClient.connect({ serverUrl, token });
+     * bc.subscribe(render);          // render(AgentView) on every update
+     * bc.register();                 // announce reachability + load deployment data
+     * bc.placeCall("+15551234567");  // the result arrives as a callUpsert patch
+     * ```
+     */
     static connect(opts: ConnectOptions): BabelconnectClient;
     /** The current view (deep copy). */
     get view(): AgentView;
@@ -42,6 +53,12 @@ export declare class BabelconnectClient {
     subscribe(fn: (v: AgentView) => void): () => void;
     /** The first active call, or undefined. */
     activeCall(): CallState | undefined;
+    /**
+     * Announce the agent and load its deployment data (presence options, caller-ID numbers, phonebook, feature
+     * config) — call this once after {@link BabelconnectClient.subscribe}. It also marks the agent
+     * **WebRTC-reachable** on the backend, so a control-only client that takes calls should follow it with
+     * {@link BabelconnectClient.setWebrtc}(false) + {@link BabelconnectClient.setAgentNumber}.
+     */
     register(capabilities?: string[]): void;
     placeCall(to: string, opts?: {
         displayAsTo?: string;
@@ -51,10 +68,15 @@ export declare class BabelconnectClient {
     }): void;
     /** Manually answer a RINGING call by id (no-op under autoAnswer once already answered). */
     answerCall(callId: string): Promise<void>;
+    /** End (or reject) a call by id. */
     hangup(callId: string): void;
+    /** Mute or unmute the agent's own leg of a call. */
     mute(callId: string, on: boolean): void;
+    /** Put a call on hold or retrieve it. */
     hold(callId: string, on: boolean): void;
+    /** Send DTMF tones into the call (e.g. an IVR menu choice). Valid characters: `0`–`9`, `*`, `#`, `A`–`D`. */
     sendDigits(callId: string, digits: string): void;
+    /** Set the outbound caller ID the consumer sees (choose from `agent.availableNumbers`). */
     setDisplayAs(number: string): void;
     /** Switch presence (the selector): "available" or a configured pause reason (see `AgentInfo.presenceOptions`). */
     setPresence(name: string): void;
@@ -64,24 +86,40 @@ export declare class BabelconnectClient {
         agentId?: string;
         applicationId?: string;
     }): void;
+    /** Open a conference around the current call. `hold` parks that call while you add members and consult. */
     startConference(hold?: boolean): void;
+    /** Invite a participant — pass exactly one of `agentId` or `number`. Starts a conference first if none is active. */
     addConferenceMember(opts: {
         agentId?: string;
         number?: string;
     }): void;
+    /** Remove a member from the conference (moderator only). */
     kickConferenceMember(memberId: string): void;
+    /** Hold or unhold an individual conference member (moderator only). */
     holdConferenceMember(memberId: string, on: boolean): void;
+    /** Mute or unmute an individual conference member (moderator only). */
     muteConferenceMember(memberId: string, on: boolean): void;
+    /** End the whole conference for everyone (moderator only). */
     endConference(): void;
+    /** Drop only the agent's own leg; the other members stay connected. */
     leaveConference(): void;
+    /** Add seconds to the after-call-work countdown (default 30). Show only when `wrapUp.canExtend`. */
     wrapUpExtend(seconds?: number): void;
+    /** End after-call work early. Show only when `wrapUp.canCancel`. */
     wrapUpCancel(): void;
+    /** Clear a blocked line (busy / unreachable / declined) so new calls reach the agent again. */
     resetLineStatus(): void;
+    /** Begin recording the current call. Gated on `agent.canRecord`. */
     startRecording(callId: string): void;
+    /** Stop the call's active recording. */
     stopRecording(callId: string): void;
+    /** Toggle the "flagged" mark on the call's active recording. */
     flagRecording(callId: string): void;
+    /** Replace the tags on the call's active recording (choose from `agent.availableTags`). */
     setRecordingTags(callId: string, tags: string[]): void;
+    /** Turn the in-browser WebRTC phone on or off. With it off, set an agent number so calls bridge there. */
     setWebrtc(on: boolean): void;
+    /** Set the agent's external phone number; the backend bridges calls there when WebRTC is off. */
     setAgentNumber(number: string): void;
     /** Send an SMS. `from` may be empty (server picks the default); `session` carries CTI/embedding correlation. */
     sendSms(to: string, text: string, opts?: {

package/dist/client.js

@@ -1,8 +1,8 @@
-import { createClient } from "@connectrpc/connect";
+import { createClient, } from "@connectrpc/connect";
 import { createGrpcWebTransport } from "@connectrpc/connect-web";
 import { Agent } from "./gen/babelconnect/v1/babelconnect_connect.js";
 import { AddConferenceMember, AnswerCall, CallDirection, CallLifecycle, CallSource, Command, EndConference, Error as BcError, FlagRecording, Hangup, HistoryRequest, SmsThreadRequest, PhonebookRequest, HoldConferenceMember, Hold, KickConferenceMember, LeaveConference, MarkConversationRead, Mute, MuteConferenceMember, PlaceCall, Register, ResetLineStatus, SendDigits, SendSmsRequest, SetAgentNumber, SetConversationOpen, SetDisplayAs, SetPresence, SetWebrtc, StartConference, StartRecording, StopRecording, SetRecordingTags, SubscribeRequest, Transfer, WrapUpCancel, WrapUpExtend, } from "./gen/babelconnect/v1/babelconnect_pb.js";
-import { browserMediaFactory, toRTCIceServers } from "./media.js";
+import { browserMediaFactory, toRTCIceServers, } from "./media.js";
 import { StateCache } from "./state-cache.js";
 /**
  * The TypeScript "dumb renderer" client: opens the `Subscribe`/`Send` gRPC-web
@@ -28,7 +28,18 @@ export class BabelconnectClient {
         });
         this.rpc = createClient(Agent, transport);
     }
-    /** Open the session and start mirroring server state. */
+    /**
+     * Open the session and start mirroring server state. Returns synchronously and queues intents until the
+     * stream is live, so you can subscribe and register immediately.
+     *
+     * @example
+     * ```ts
+     * const bc = BabelconnectClient.connect({ serverUrl, token });
+     * bc.subscribe(render);          // render(AgentView) on every update
+     * bc.register();                 // announce reachability + load deployment data
+     * bc.placeCall("+15551234567");  // the result arrives as a callUpsert patch
+     * ```
+     */
     static connect(opts) {
         const c = new BabelconnectClient(opts);
         void c.runSubscribe();
@@ -47,8 +58,16 @@ export class BabelconnectClient {
         return this.cache.current.activeCalls[0];
     }
     // --- intents ---
+    /**
+     * Announce the agent and load its deployment data (presence options, caller-ID numbers, phonebook, feature
+     * config) — call this once after {@link BabelconnectClient.subscribe}. It also marks the agent
+     * **WebRTC-reachable** on the backend, so a control-only client that takes calls should follow it with
+     * {@link BabelconnectClient.setWebrtc}(false) + {@link BabelconnectClient.setAgentNumber}.
+     */
     register(capabilities = ["webrtc"]) {
-        this.send(new Command({ command: { case: "register", value: new Register({ capabilities }) } }));
+        this.send(new Command({
+            command: { case: "register", value: new Register({ capabilities }) },
+        }));
     }
     placeCall(to, opts = {}) {
         this.send(new Command({
@@ -70,24 +89,41 @@ export class BabelconnectClient {
         if (call)
             await this.doAnswer(call);
     }
+    /** End (or reject) a call by id. */
     hangup(callId) {
-        this.send(new Command({ command: { case: "hangup", value: new Hangup({ callId }) } }));
+        this.send(new Command({
+            command: { case: "hangup", value: new Hangup({ callId }) },
+        }));
     }
+    /** Mute or unmute the agent's own leg of a call. */
     mute(callId, on) {
-        this.send(new Command({ command: { case: "mute", value: new Mute({ callId, on }) } }));
+        this.send(new Command({
+            command: { case: "mute", value: new Mute({ callId, on }) },
+        }));
     }
+    /** Put a call on hold or retrieve it. */
     hold(callId, on) {
-        this.send(new Command({ command: { case: "hold", value: new Hold({ callId, on }) } }));
+        this.send(new Command({
+            command: { case: "hold", value: new Hold({ callId, on }) },
+        }));
     }
+    /** Send DTMF tones into the call (e.g. an IVR menu choice). Valid characters: `0`–`9`, `*`, `#`, `A`–`D`. */
     sendDigits(callId, digits) {
-        this.send(new Command({ command: { case: "dtmf", value: new SendDigits({ callId, digits }) } }));
+        this.send(new Command({
+            command: { case: "dtmf", value: new SendDigits({ callId, digits }) },
+        }));
     }
+    /** Set the outbound caller ID the consumer sees (choose from `agent.availableNumbers`). */
     setDisplayAs(number) {
-        this.send(new Command({ command: { case: "setDisplayAs", value: new SetDisplayAs({ number }) } }));
+        this.send(new Command({
+            command: { case: "setDisplayAs", value: new SetDisplayAs({ number }) },
+        }));
     }
     /** Switch presence (the selector): "available" or a configured pause reason (see `AgentInfo.presenceOptions`). */
     setPresence(name) {
-        this.send(new Command({ command: { case: "setPresence", value: new SetPresence({ name }) } }));
+        this.send(new Command({
+            command: { case: "setPresence", value: new SetPresence({ name }) },
+        }));
     }
     /** Transfer to exactly one of `to` (number), `agentId`, or `applicationId`; `warm` = attended. */
     transfer(callId, to, opts = {}) {
@@ -105,78 +141,165 @@ export class BabelconnectClient {
         }));
     }
     // --- Conferences ---
+    /** Open a conference around the current call. `hold` parks that call while you add members and consult. */
     startConference(hold = false) {
-        this.send(new Command({ command: { case: "startConference", value: new StartConference({ hold }) } }));
+        this.send(new Command({
+            command: {
+                case: "startConference",
+                value: new StartConference({ hold }),
+            },
+        }));
     }
+    /** Invite a participant — pass exactly one of `agentId` or `number`. Starts a conference first if none is active. */
     addConferenceMember(opts) {
         this.send(new Command({
             command: {
                 case: "addConferenceMember",
-                value: new AddConferenceMember({ agentId: opts.agentId ?? "", number: opts.number ?? "" }),
+                value: new AddConferenceMember({
+                    agentId: opts.agentId ?? "",
+                    number: opts.number ?? "",
+                }),
             },
         }));
     }
+    /** Remove a member from the conference (moderator only). */
     kickConferenceMember(memberId) {
-        this.send(new Command({ command: { case: "kickConferenceMember", value: new KickConferenceMember({ memberId }) } }));
+        this.send(new Command({
+            command: {
+                case: "kickConferenceMember",
+                value: new KickConferenceMember({ memberId }),
+            },
+        }));
     }
+    /** Hold or unhold an individual conference member (moderator only). */
     holdConferenceMember(memberId, on) {
-        this.send(new Command({ command: { case: "holdConferenceMember", value: new HoldConferenceMember({ memberId, on }) } }));
+        this.send(new Command({
+            command: {
+                case: "holdConferenceMember",
+                value: new HoldConferenceMember({ memberId, on }),
+            },
+        }));
     }
+    /** Mute or unmute an individual conference member (moderator only). */
     muteConferenceMember(memberId, on) {
-        this.send(new Command({ command: { case: "muteConferenceMember", value: new MuteConferenceMember({ memberId, on }) } }));
+        this.send(new Command({
+            command: {
+                case: "muteConferenceMember",
+                value: new MuteConferenceMember({ memberId, on }),
+            },
+        }));
     }
+    /** End the whole conference for everyone (moderator only). */
     endConference() {
-        this.send(new Command({ command: { case: "endConference", value: new EndConference({}) } }));
+        this.send(new Command({
+            command: { case: "endConference", value: new EndConference({}) },
+        }));
     }
+    /** Drop only the agent's own leg; the other members stay connected. */
     leaveConference() {
-        this.send(new Command({ command: { case: "leaveConference", value: new LeaveConference({}) } }));
+        this.send(new Command({
+            command: { case: "leaveConference", value: new LeaveConference({}) },
+        }));
     }
+    /** Add seconds to the after-call-work countdown (default 30). Show only when `wrapUp.canExtend`. */
     wrapUpExtend(seconds = 30) {
-        this.send(new Command({ command: { case: "wrapUpExtend", value: new WrapUpExtend({ seconds }) } }));
+        this.send(new Command({
+            command: { case: "wrapUpExtend", value: new WrapUpExtend({ seconds }) },
+        }));
     }
+    /** End after-call work early. Show only when `wrapUp.canCancel`. */
     wrapUpCancel() {
-        this.send(new Command({ command: { case: "wrapUpCancel", value: new WrapUpCancel({}) } }));
+        this.send(new Command({
+            command: { case: "wrapUpCancel", value: new WrapUpCancel({}) },
+        }));
     }
+    /** Clear a blocked line (busy / unreachable / declined) so new calls reach the agent again. */
     resetLineStatus() {
-        this.send(new Command({ command: { case: "resetLineStatus", value: new ResetLineStatus({}) } }));
+        this.send(new Command({
+            command: { case: "resetLineStatus", value: new ResetLineStatus({}) },
+        }));
     }
+    /** Begin recording the current call. Gated on `agent.canRecord`. */
     startRecording(callId) {
-        this.send(new Command({ command: { case: "startRecording", value: new StartRecording({ callId }) } }));
+        this.send(new Command({
+            command: {
+                case: "startRecording",
+                value: new StartRecording({ callId }),
+            },
+        }));
     }
+    /** Stop the call's active recording. */
     stopRecording(callId) {
-        this.send(new Command({ command: { case: "stopRecording", value: new StopRecording({ callId }) } }));
+        this.send(new Command({
+            command: {
+                case: "stopRecording",
+                value: new StopRecording({ callId }),
+            },
+        }));
     }
+    /** Toggle the "flagged" mark on the call's active recording. */
     flagRecording(callId) {
-        this.send(new Command({ command: { case: "flagRecording", value: new FlagRecording({ callId }) } }));
+        this.send(new Command({
+            command: {
+                case: "flagRecording",
+                value: new FlagRecording({ callId }),
+            },
+        }));
     }
+    /** Replace the tags on the call's active recording (choose from `agent.availableTags`). */
     setRecordingTags(callId, tags) {
-        this.send(new Command({ command: { case: "setRecordingTags", value: new SetRecordingTags({ callId, tags }) } }));
+        this.send(new Command({
+            command: {
+                case: "setRecordingTags",
+                value: new SetRecordingTags({ callId, tags }),
+            },
+        }));
     }
+    /** Turn the in-browser WebRTC phone on or off. With it off, set an agent number so calls bridge there. */
     setWebrtc(on) {
-        this.send(new Command({ command: { case: "setWebrtc", value: new SetWebrtc({ on }) } }));
+        this.send(new Command({
+            command: { case: "setWebrtc", value: new SetWebrtc({ on }) },
+        }));
     }
+    /** Set the agent's external phone number; the backend bridges calls there when WebRTC is off. */
     setAgentNumber(number) {
-        this.send(new Command({ command: { case: "setAgentNumber", value: new SetAgentNumber({ number }) } }));
+        this.send(new Command({
+            command: {
+                case: "setAgentNumber",
+                value: new SetAgentNumber({ number }),
+            },
+        }));
     }
     /** Send an SMS. `from` may be empty (server picks the default); `session` carries CTI/embedding correlation. */
     sendSms(to, text, opts = {}) {
         this.send(new Command({
             command: {
                 case: "sendSms",
-                value: new SendSmsRequest({ to, text, from: opts.from ?? "", session: opts.session ?? {} }),
+                value: new SendSmsRequest({
+                    to,
+                    text,
+                    from: opts.from ?? "",
+                    session: opts.session ?? {},
+                }),
             },
         }));
     }
     /** Open (reopen) or close (resolve) an SMS conversation. */
     setConversationOpen(conversationId, open) {
         this.send(new Command({
-            command: { case: "setConversationOpen", value: new SetConversationOpen({ conversationId, open }) },
+            command: {
+                case: "setConversationOpen",
+                value: new SetConversationOpen({ conversationId, open }),
+            },
         }));
     }
     /** Clear the unread count on an SMS conversation (the agent opened its thread). */
     markConversationRead(conversationId) {
         this.send(new Command({
-            command: { case: "markConversationRead", value: new MarkConversationRead({ conversationId }) },
+            command: {
+                case: "markConversationRead",
+                value: new MarkConversationRead({ conversationId }),
+            },
         }));
     }
     /** Fetch a page of the agent's call history (the History tab). */
@@ -207,7 +330,9 @@ export class BabelconnectClient {
     // --- internals ---
     async runSubscribe() {
         try {
-            for await (const u of this.rpc.subscribe(new SubscribeRequest({}), { signal: this.abort.signal })) {
+            for await (const u of this.rpc.subscribe(new SubscribeRequest({}), {
+                signal: this.abort.signal,
+            })) {
                 this.onUpdate(u);
             }
         }
@@ -217,6 +342,10 @@ export class BabelconnectClient {
         }
     }
     onUpdate(u) {
+        // Keepalive heartbeat: transport-only, no state — skip the cache/reconcile
+        // pass so a 15s heartbeat doesn't trigger a no-op reconcile every tick.
+        if (u.update.case === "keepalive")
+            return;
         // First message = the snapshot ⇒ the session is registered server-side, so
         // flush intents queued during connect() (register(), an early dial, …).
         if (!this.ready) {
@@ -229,7 +358,8 @@ export class BabelconnectClient {
             this.opts.onError?.(u.update.value);
             return;
         }
-        if (u.update.case === "patch" && u.update.value.change.case === "notification") {
+        if (u.update.case === "patch" &&
+            u.update.value.change.case === "notification") {
             this.opts.onNotification?.(u.update.value.change.value);
             return;
         }
@@ -263,9 +393,15 @@ export class BabelconnectClient {
     async doAnswer(call) {
         if (this.answering.has(call.id) || this.media.has(call.id))
             return;
-        const factory = this.opts.mediaFactory === undefined ? browserMediaFactory : this.opts.mediaFactory;
+        const factory = this.opts.mediaFactory === undefined
+            ? browserMediaFactory
+            : this.opts.mediaFactory;
         if (!factory) {
-            this.opts.onError?.(new BcError({ code: "no_media", message: "no media factory configured", callId: call.id }));
+            this.opts.onError?.(new BcError({
+                code: "no_media",
+                message: "no media factory configured",
+                callId: call.id,
+            }));
             return;
         }
         this.answering.add(call.id);
@@ -276,10 +412,19 @@ export class BabelconnectClient {
             // undefined so the Media's own fallback applies.
             const answerSdp = await media.answer(call.webrtcOffer, toRTCIceServers(call.iceServers));
             this.media.set(call.id, media);
-            this.send(new Command({ command: { case: "answer", value: new AnswerCall({ callId: call.id, sdp: answerSdp }) } }));
+            this.send(new Command({
+                command: {
+                    case: "answer",
+                    value: new AnswerCall({ callId: call.id, sdp: answerSdp }),
+                },
+            }));
         }
         catch (e) {
-            this.opts.onError?.(new BcError({ code: "media_answer_failed", message: String(e), callId: call.id }));
+            this.opts.onError?.(new BcError({
+                code: "media_answer_failed",
+                message: String(e),
+                callId: call.id,
+            }));
         }
         finally {
             this.answering.delete(call.id);

package/dist/embed/index.d.ts

@@ -2,7 +2,7 @@
  * `@babelforce/babelconnect-sdk/embed` — embed the babelconnect agent app (the
  * server-served Flutter web app) into a host page via an `<iframe>` and a two-way
  * `postMessage` bridge. See the Embedding guide at
- * https://babelforce.github.io/babelconnect-sdk-docs/ for the full protocol.
+ * https://babelforce.github.io/babelconnect-sdk/ for the full protocol.
  * The embedded app talks only to babelconnect-server.
  *
  * @example

package/dist/embed/index.js

@@ -2,7 +2,7 @@
  * `@babelforce/babelconnect-sdk/embed` — embed the babelconnect agent app (the
  * server-served Flutter web app) into a host page via an `<iframe>` and a two-way
  * `postMessage` bridge. See the Embedding guide at
- * https://babelforce.github.io/babelconnect-sdk-docs/ for the full protocol.
+ * https://babelforce.github.io/babelconnect-sdk/ for the full protocol.
  * The embedded app talks only to babelconnect-server.
  *
  * @example

package/dist/gen/babelconnect/v1/babelconnect_pb.d.ts

@@ -707,6 +707,15 @@ export declare class AgentInfo extends Message<AgentInfo> {
      * @generated from field: string account_name = 17;
      */
     accountName: string;
+    /**
+     * Involuntary line block: the ACD/platform marked the agent busy / unreachable /
+     * declined (a recoverable state cleared via ResetLineStatus) — distinct from a
+     * chosen "busy" presence the agent (or sign-out-as-busy) selected. Drives the
+     * line-blocked banner + Reset; a voluntary busy presence leaves this false.
+     *
+     * @generated from field: bool line_blocked = 18;
+     */
+    lineBlocked: boolean;
     constructor(data?: PartialMessage<AgentInfo>);
     static readonly runtime: typeof proto3;
     static readonly typeName = "babelconnect.v1.AgentInfo";
@@ -990,7 +999,9 @@ export declare class WrapUpStatus extends Message<WrapUpStatus> {
  * open the client receives a snapshot; thereafter partial patches. `seq` is
  * monotonic across snapshot+patch — a gap means the client should resubscribe
  * for a fresh snapshot. `error` is an out-of-band notice (command rejection /
- * server warning) and does NOT advance `seq`.
+ * server warning) and does NOT advance `seq`. `keepalive` is an empty transport
+ * heartbeat (see Keepalive) that likewise does NOT advance `seq` and carries no
+ * state — client caches must ignore it.
  *
  * @generated from message babelconnect.v1.StateUpdate
  */
@@ -1020,6 +1031,12 @@ export declare class StateUpdate extends Message<StateUpdate> {
          */
         value: Error;
         case: "error";
+    } | {
+        /**
+         * @generated from field: babelconnect.v1.Keepalive keepalive = 5;
+         */
+        value: Keepalive;
+        case: "keepalive";
     } | {
         case: undefined;
         value?: undefined;
@@ -1033,6 +1050,26 @@ export declare class StateUpdate extends Message<StateUpdate> {
     static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): StateUpdate;
     static equals(a: StateUpdate | PlainMessage<StateUpdate> | undefined, b: StateUpdate | PlainMessage<StateUpdate> | undefined): boolean;
 }
+/**
+ * Keepalive is an empty heartbeat frame sent on the Session/Subscribe streams so
+ * idle connections through proxies/LBs are not closed as idle. Notably the AWS
+ * Classic ELB in front of ingress-nginx (dev/prod EKS) has a 300s connection
+ * idle timeout; without these frames a quiet agent's gRPC-web server-stream is
+ * killed after 5 min. The server sends one every ~15s. It carries no state and
+ * does NOT advance `seq`; client caches treat a keepalive StateUpdate as a no-op.
+ *
+ * @generated from message babelconnect.v1.Keepalive
+ */
+export declare class Keepalive extends Message<Keepalive> {
+    constructor(data?: PartialMessage<Keepalive>);
+    static readonly runtime: typeof proto3;
+    static readonly typeName = "babelconnect.v1.Keepalive";
+    static readonly fields: FieldList;
+    static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): Keepalive;
+    static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): Keepalive;
+    static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): Keepalive;
+    static equals(a: Keepalive | PlainMessage<Keepalive> | undefined, b: Keepalive | PlainMessage<Keepalive> | undefined): boolean;
+}
 /**
  * Patch is an entity-level delta applied mechanically by the client cache:
  * replace the agent block, upsert/remove a call by id, or set wrap-up.

package/dist/gen/babelconnect/v1/babelconnect_pb.js

@@ -998,6 +998,15 @@ export class AgentInfo extends Message {
      * @generated from field: string account_name = 17;
      */
     accountName = "";
+    /**
+     * Involuntary line block: the ACD/platform marked the agent busy / unreachable /
+     * declined (a recoverable state cleared via ResetLineStatus) — distinct from a
+     * chosen "busy" presence the agent (or sign-out-as-busy) selected. Drives the
+     * line-blocked banner + Reset; a voluntary busy presence leaves this false.
+     *
+     * @generated from field: bool line_blocked = 18;
+     */
+    lineBlocked = false;
     constructor(data) {
         super();
         proto3.util.initPartial(data, this);
@@ -1022,6 +1031,7 @@ export class AgentInfo extends Message {
         { no: 15, name: "username", kind: "scalar", T: 9 /* ScalarType.STRING */ },
         { no: 16, name: "account_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
         { no: 17, name: "account_name", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+        { no: 18, name: "line_blocked", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
     ]);
     static fromBinary(bytes, options) {
         return new AgentInfo().fromBinary(bytes, options);
@@ -1428,7 +1438,9 @@ export class WrapUpStatus extends Message {
  * open the client receives a snapshot; thereafter partial patches. `seq` is
  * monotonic across snapshot+patch — a gap means the client should resubscribe
  * for a fresh snapshot. `error` is an out-of-band notice (command rejection /
- * server warning) and does NOT advance `seq`.
+ * server warning) and does NOT advance `seq`. `keepalive` is an empty transport
+ * heartbeat (see Keepalive) that likewise does NOT advance `seq` and carries no
+ * state — client caches must ignore it.
  *
  * @generated from message babelconnect.v1.StateUpdate
  */
@@ -1452,6 +1464,7 @@ export class StateUpdate extends Message {
         { no: 2, name: "snapshot", kind: "message", T: AgentView, oneof: "update" },
         { no: 3, name: "patch", kind: "message", T: Patch, oneof: "update" },
         { no: 4, name: "error", kind: "message", T: Error, oneof: "update" },
+        { no: 5, name: "keepalive", kind: "message", T: Keepalive, oneof: "update" },
     ]);
     static fromBinary(bytes, options) {
         return new StateUpdate().fromBinary(bytes, options);
@@ -1466,6 +1479,37 @@ export class StateUpdate extends Message {
         return proto3.util.equals(StateUpdate, a, b);
     }
 }
+/**
+ * Keepalive is an empty heartbeat frame sent on the Session/Subscribe streams so
+ * idle connections through proxies/LBs are not closed as idle. Notably the AWS
+ * Classic ELB in front of ingress-nginx (dev/prod EKS) has a 300s connection
+ * idle timeout; without these frames a quiet agent's gRPC-web server-stream is
+ * killed after 5 min. The server sends one every ~15s. It carries no state and
+ * does NOT advance `seq`; client caches treat a keepalive StateUpdate as a no-op.
+ *
+ * @generated from message babelconnect.v1.Keepalive
+ */
+export class Keepalive extends Message {
+    constructor(data) {
+        super();
+        proto3.util.initPartial(data, this);
+    }
+    static runtime = proto3;
+    static typeName = "babelconnect.v1.Keepalive";
+    static fields = proto3.util.newFieldList(() => []);
+    static fromBinary(bytes, options) {
+        return new Keepalive().fromBinary(bytes, options);
+    }
+    static fromJson(jsonValue, options) {
+        return new Keepalive().fromJson(jsonValue, options);
+    }
+    static fromJsonString(jsonString, options) {
+        return new Keepalive().fromJsonString(jsonString, options);
+    }
+    static equals(a, b) {
+        return proto3.util.equals(Keepalive, a, b);
+    }
+}
 /**
  * Patch is an entity-level delta applied mechanically by the client cache:
  * replace the agent block, upsert/remove a call by id, or set wrap-up.

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  */
 export { BabelconnectClient, type ConnectOptions } from "./client.js";
 export { StateCache } from "./state-cache.js";
-export { passwordGrant } from "./auth.js";
+export { passwordGrant, revokeToken, pkceChallenge, buildAuthorizeUrl, authorizationCodeGrant, DEFAULT_CLIENT_ID, type TokenResponse, type PkceChallenge, type AuthorizeUrlOptions, } from "./auth.js";
 export { BrowserWebrtcMedia, browserMediaFactory, type Media, type MediaFactory } from "./media.js";
 export * from "./gen/babelconnect/v1/babelconnect_pb.js";
 export { Agent } from "./gen/babelconnect/v1/babelconnect_connect.js";

package/dist/index.js

@@ -11,7 +11,7 @@
  */
 export { BabelconnectClient } from "./client.js";
 export { StateCache } from "./state-cache.js";
-export { passwordGrant } from "./auth.js";
+export { passwordGrant, revokeToken, pkceChallenge, buildAuthorizeUrl, authorizationCodeGrant, DEFAULT_CLIENT_ID, } from "./auth.js";
 export { BrowserWebrtcMedia, browserMediaFactory } from "./media.js";
 // The generated babelconnect.v1 messages + enums (AgentView, CallState, Command, …)
 // and the Agent service descriptor.

package/dist/state-cache.d.ts

@@ -1,6 +1,6 @@
 import { AgentView, type StateUpdate } from "./gen/babelconnect/v1/babelconnect_pb.js";
 /**
- * The client-side mirror of the server-authoritative {@link AgentView}.
+ * The client-side mirror of the server-authoritative `AgentView`.
  *
  * It applies `StateUpdate` snapshots and entity-level patches **mechanically** —
  * there is no domain logic here, by design: the server reduces, the client

package/dist/state-cache.js

@@ -1,6 +1,6 @@
 import { AgentView } from "./gen/babelconnect/v1/babelconnect_pb.js";
 /**
- * The client-side mirror of the server-authoritative {@link AgentView}.
+ * The client-side mirror of the server-authoritative `AgentView`.
  *
  * It applies `StateUpdate` snapshots and entity-level patches **mechanically** —
  * there is no domain logic here, by design: the server reduces, the client

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@babelforce/babelconnect-sdk",
-  "version": "0.1.0",
+  "version": "0.7.0",
   "description": "TypeScript SDK for babelconnect — server-authoritative agent state over gRPC-web, native WebRTC audio, and an embeddable widget (iframe + postMessage) for the Flutter web app.",
   "license": "Apache-2.0",
-  "homepage": "https://babelforce.github.io/babelconnect-sdk-docs/",
+  "homepage": "https://babelforce.github.io/babelconnect-sdk/",
   "type": "module",
   "sideEffects": false,
   "files": [
@@ -39,8 +39,8 @@
   "devDependencies": {
     "@bufbuild/protoc-gen-es": "^1.10.1",
     "@connectrpc/protoc-gen-connect-es": "^1.6.1",
-    "typedoc": "^0.27.0",
-    "typedoc-plugin-markdown": "^4.4.0",
+    "typedoc": "~0.27.0",
+    "typedoc-plugin-markdown": "4.4.0",
     "typescript": "^5.6.0"
   },
   "publishConfig": {