@babelforce/babelconnect-sdk 0.9.1 → 0.11.0

package/dist/client.d.ts

@@ -150,3 +150,8 @@ export declare class BabelconnectClient {
     private rawSend;
     private closeAllMedia;
 }
+/**
+ * Stamp the SDK identity (name + build version) onto a request's headers — sent
+ * on every unary + streaming call so the server can identify the client (APP-A5).
+ */
+export declare function applySdkHeaders(header: Headers): void;

package/dist/client.js

@@ -1,8 +1,9 @@
 import { createClient, } from "@connectrpc/connect";
 import { createGrpcWebTransport } from "@connectrpc/connect-web";
+import { SDK_VERSION } from "./version.js";
 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 { AddConferenceMember, AnswerCall, CallDirection, CallLifecycle, CallSource, Command, EndConference, Error as BcError, FlagRecording, Hangup, HistoryRequest, SmsThreadRequest, PhonebookRequest, HoldConferenceMember, Hold, KickConferenceMember, LeaveConference, MarkConversationRead, Mute, MuteConferenceMember, PlaceCall, Pong, 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, MediaError, toRTCIceServers, } from "./media.js";
 import { StateCache } from "./state-cache.js";
 /**
  * The TypeScript "dumb renderer" client: opens the `Subscribe`/`Send` gRPC-web
@@ -346,6 +347,15 @@ export class BabelconnectClient {
         // pass so a 15s heartbeat doesn't trigger a no-op reconcile every tick.
         if (u.update.case === "keepalive")
             return;
+        // Ping: reply with a Pong echoing the seq so the server can measure RTT +
+        // liveness (CALL-M6). Control-only, like keepalive — short-circuited before the
+        // cache and the ready/flush logic so it is never mistaken for the snapshot.
+        if (u.update.case === "ping") {
+            void this.rawSend(new Command({
+                command: { case: "pong", value: new Pong({ seq: u.update.value.seq }) },
+            }));
+            return;
+        }
         // First message = the snapshot ⇒ the session is registered server-side, so
         // flush intents queued during connect() (register(), an early dial, …).
         if (!this.ready) {
@@ -420,9 +430,15 @@ export class BabelconnectClient {
             }));
         }
         catch (e) {
+            // CALL-M5: a Media impl classifies a mic-acquisition failure (no mic,
+            // permission denied, device busy) into a distinct code via MediaError;
+            // anything else stays the opaque catch-all. The distinct code lets the
+            // UI/host explain the cause instead of showing a raw WebRTC string.
+            const code = e instanceof MediaError ? e.code : "media_answer_failed";
+            const message = e instanceof MediaError ? e.message : String(e);
             this.opts.onError?.(new BcError({
-                code: "media_answer_failed",
-                message: String(e),
+                code,
+                message,
                 callId: call.id,
             }));
         }
@@ -458,10 +474,22 @@ export class BabelconnectClient {
         await Promise.all(all.map((m) => m.close()));
     }
 }
-/** An interceptor that attaches the bearer token to every gRPC-web call. */
+/**
+ * Stamp the SDK identity (name + build version) onto a request's headers — sent
+ * on every unary + streaming call so the server can identify the client (APP-A5).
+ */
+export function applySdkHeaders(header) {
+    header.set("x-babelconnect-sdk", "ts");
+    header.set("x-babelconnect-sdk-version", SDK_VERSION);
+}
+/**
+ * An interceptor that attaches the bearer token and the SDK identity headers to
+ * every gRPC-web call (unary + the long-lived Subscribe stream).
+ */
 function authInterceptor(token) {
     return (next) => (req) => {
         req.header.set("Authorization", `Bearer ${token}`);
+        applySdkHeaders(req.header);
         return next(req);
     };
 }

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

@@ -332,6 +332,18 @@ export declare class Identity extends Message<Identity> {
      * @generated from field: babelconnect.v1.AgentState state = 5;
      */
     state: AgentState;
+    /**
+     * account / company display name, when known (ACC-E1)
+     *
+     * @generated from field: string account_name = 6;
+     */
+    accountName: string;
+    /**
+     * accounts this agent may switch to (ACC-E2)
+     *
+     * @generated from field: repeated babelconnect.v1.Account accounts = 7;
+     */
+    accounts: Account[];
     constructor(data?: PartialMessage<Identity>);
     static readonly runtime: typeof proto3;
     static readonly typeName = "babelconnect.v1.Identity";
@@ -341,6 +353,41 @@ export declare class Identity extends Message<Identity> {
     static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): Identity;
     static equals(a: Identity | PlainMessage<Identity> | undefined, b: Identity | PlainMessage<Identity> | undefined): boolean;
 }
+/**
+ * Account is one tenant the signed-in agent can operate in — the switchable set
+ * (agent-role only) surfaced for the account picker (ACC-E2). Sourced from
+ * GET /api/v2/user/accounts.
+ *
+ * @generated from message babelconnect.v1.Account
+ */
+export declare class Account extends Message<Account> {
+    /**
+     * customer / account id
+     *
+     * @generated from field: string id = 1;
+     */
+    id: string;
+    /**
+     * company / display name
+     *
+     * @generated from field: string name = 2;
+     */
+    name: string;
+    /**
+     * the account this session is currently scoped to
+     *
+     * @generated from field: bool current = 3;
+     */
+    current: boolean;
+    constructor(data?: PartialMessage<Account>);
+    static readonly runtime: typeof proto3;
+    static readonly typeName = "babelconnect.v1.Account";
+    static readonly fields: FieldList;
+    static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): Account;
+    static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): Account;
+    static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): Account;
+    static equals(a: Account | PlainMessage<Account> | undefined, b: Account | PlainMessage<Account> | undefined): boolean;
+}
 /**
  * AgentView is the complete per-agent state the server owns and renders to. A
  * snapshot carries the whole view; patches carry entity-level deltas.
@@ -532,6 +579,12 @@ export declare class FeatureAccount extends Message<FeatureAccount> {
      * @generated from field: bool show_status = 3;
      */
     showStatus: boolean;
+    /**
+     * the multi-account switcher (ACC-E2)
+     *
+     * @generated from field: bool allow_account_switch = 4;
+     */
+    allowAccountSwitch: boolean;
     constructor(data?: PartialMessage<FeatureAccount>);
     static readonly runtime: typeof proto3;
     static readonly typeName = "babelconnect.v1.FeatureAccount";
@@ -716,6 +769,14 @@ export declare class AgentInfo extends Message<AgentInfo> {
      * @generated from field: bool line_blocked = 18;
      */
     lineBlocked: boolean;
+    /**
+     * Accounts this agent may switch to without re-logging-in (agent-role only,
+     * resolved at auth from GET /api/v2/user/accounts). One is marked `current`.
+     * Drives the Account tab's switcher; empty/single ⇒ no picker (ACC-E2).
+     *
+     * @generated from field: repeated babelconnect.v1.Account accounts = 19;
+     */
+    accounts: Account[];
     constructor(data?: PartialMessage<AgentInfo>);
     static readonly runtime: typeof proto3;
     static readonly typeName = "babelconnect.v1.AgentInfo";
@@ -1037,6 +1098,12 @@ export declare class StateUpdate extends Message<StateUpdate> {
          */
         value: Keepalive;
         case: "keepalive";
+    } | {
+        /**
+         * @generated from field: babelconnect.v1.Ping ping = 6;
+         */
+        value: Ping;
+        case: "ping";
     } | {
         case: undefined;
         value?: undefined;
@@ -1070,6 +1137,30 @@ export declare class Keepalive extends Message<Keepalive> {
     static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): Keepalive;
     static equals(a: Keepalive | PlainMessage<Keepalive> | undefined, b: Keepalive | PlainMessage<Keepalive> | undefined): boolean;
 }
+/**
+ * Ping is a liveness probe the server sends on the heartbeat tick (replacing the
+ * bare Keepalive frame). The client echoes `seq` back in a Pong command; the server
+ * measures round-trip time (RTT) from the reply and tracks per-session liveness.
+ * Like Keepalive it keeps the connection warm, carries no state, and does NOT
+ * advance `seq` — caches ignore it, and the reply is handled in the client's stream
+ * loop, not the state reducer. (APP-A5/CALL-M6.)
+ *
+ * @generated from message babelconnect.v1.Ping
+ */
+export declare class Ping extends Message<Ping> {
+    /**
+     * @generated from field: uint64 seq = 1;
+     */
+    seq: bigint;
+    constructor(data?: PartialMessage<Ping>);
+    static readonly runtime: typeof proto3;
+    static readonly typeName = "babelconnect.v1.Ping";
+    static readonly fields: FieldList;
+    static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): Ping;
+    static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): Ping;
+    static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): Ping;
+    static equals(a: Ping | PlainMessage<Ping> | undefined, b: Ping | PlainMessage<Ping> | 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.
@@ -1455,6 +1546,14 @@ export declare class Command extends Message<Command> {
          */
         value: MarkConversationRead;
         case: "markConversationRead";
+    } | {
+        /**
+         * reply to a server Ping (liveness + RTT); echoes Ping.seq
+         *
+         * @generated from field: babelconnect.v1.Pong pong = 30;
+         */
+        value: Pong;
+        case: "pong";
     } | {
         case: undefined;
         value?: undefined;
@@ -1468,6 +1567,27 @@ export declare class Command extends Message<Command> {
     static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): Command;
     static equals(a: Command | PlainMessage<Command> | undefined, b: Command | PlainMessage<Command> | undefined): boolean;
 }
+/**
+ * Pong replies to a server Ping (StateUpdate.ping), echoing its `seq` so the server
+ * can match it to the outstanding ping and compute RTT. Sent automatically by the
+ * SDK from its stream-receive loop — not a user intent. (APP-A5/CALL-M6.)
+ *
+ * @generated from message babelconnect.v1.Pong
+ */
+export declare class Pong extends Message<Pong> {
+    /**
+     * @generated from field: uint64 seq = 1;
+     */
+    seq: bigint;
+    constructor(data?: PartialMessage<Pong>);
+    static readonly runtime: typeof proto3;
+    static readonly typeName = "babelconnect.v1.Pong";
+    static readonly fields: FieldList;
+    static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): Pong;
+    static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): Pong;
+    static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): Pong;
+    static equals(a: Pong | PlainMessage<Pong> | undefined, b: Pong | PlainMessage<Pong> | undefined): boolean;
+}
 /**
  * @generated from message babelconnect.v1.Register
  */

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

@@ -471,6 +471,18 @@ export class Identity extends Message {
      * @generated from field: babelconnect.v1.AgentState state = 5;
      */
     state = AgentState.UNSPECIFIED;
+    /**
+     * account / company display name, when known (ACC-E1)
+     *
+     * @generated from field: string account_name = 6;
+     */
+    accountName = "";
+    /**
+     * accounts this agent may switch to (ACC-E2)
+     *
+     * @generated from field: repeated babelconnect.v1.Account accounts = 7;
+     */
+    accounts = [];
     constructor(data) {
         super();
         proto3.util.initPartial(data, this);
@@ -483,6 +495,8 @@ export class Identity extends Message {
         { no: 3, name: "number", kind: "scalar", T: 9 /* ScalarType.STRING */ },
         { no: 4, name: "username", kind: "scalar", T: 9 /* ScalarType.STRING */ },
         { no: 5, name: "state", kind: "enum", T: proto3.getEnumType(AgentState) },
+        { no: 6, name: "account_name", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+        { no: 7, name: "accounts", kind: "message", T: Account, repeated: true },
     ]);
     static fromBinary(bytes, options) {
         return new Identity().fromBinary(bytes, options);
@@ -497,6 +511,56 @@ export class Identity extends Message {
         return proto3.util.equals(Identity, a, b);
     }
 }
+/**
+ * Account is one tenant the signed-in agent can operate in — the switchable set
+ * (agent-role only) surfaced for the account picker (ACC-E2). Sourced from
+ * GET /api/v2/user/accounts.
+ *
+ * @generated from message babelconnect.v1.Account
+ */
+export class Account extends Message {
+    /**
+     * customer / account id
+     *
+     * @generated from field: string id = 1;
+     */
+    id = "";
+    /**
+     * company / display name
+     *
+     * @generated from field: string name = 2;
+     */
+    name = "";
+    /**
+     * the account this session is currently scoped to
+     *
+     * @generated from field: bool current = 3;
+     */
+    current = false;
+    constructor(data) {
+        super();
+        proto3.util.initPartial(data, this);
+    }
+    static runtime = proto3;
+    static typeName = "babelconnect.v1.Account";
+    static fields = proto3.util.newFieldList(() => [
+        { no: 1, name: "id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+        { no: 2, name: "name", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+        { no: 3, name: "current", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
+    ]);
+    static fromBinary(bytes, options) {
+        return new Account().fromBinary(bytes, options);
+    }
+    static fromJson(jsonValue, options) {
+        return new Account().fromJson(jsonValue, options);
+    }
+    static fromJsonString(jsonString, options) {
+        return new Account().fromJsonString(jsonString, options);
+    }
+    static equals(a, b) {
+        return proto3.util.equals(Account, a, b);
+    }
+}
 /**
  * AgentView is the complete per-agent state the server owns and renders to. A
  * snapshot carries the whole view; patches carry entity-level deltas.
@@ -767,6 +831,12 @@ export class FeatureAccount extends Message {
      * @generated from field: bool show_status = 3;
      */
     showStatus = false;
+    /**
+     * the multi-account switcher (ACC-E2)
+     *
+     * @generated from field: bool allow_account_switch = 4;
+     */
+    allowAccountSwitch = false;
     constructor(data) {
         super();
         proto3.util.initPartial(data, this);
@@ -777,6 +847,7 @@ export class FeatureAccount extends Message {
         { no: 1, name: "enabled", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
         { no: 2, name: "allow_device_switch", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
         { no: 3, name: "show_status", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
+        { no: 4, name: "allow_account_switch", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
     ]);
     static fromBinary(bytes, options) {
         return new FeatureAccount().fromBinary(bytes, options);
@@ -1007,6 +1078,14 @@ export class AgentInfo extends Message {
      * @generated from field: bool line_blocked = 18;
      */
     lineBlocked = false;
+    /**
+     * Accounts this agent may switch to without re-logging-in (agent-role only,
+     * resolved at auth from GET /api/v2/user/accounts). One is marked `current`.
+     * Drives the Account tab's switcher; empty/single ⇒ no picker (ACC-E2).
+     *
+     * @generated from field: repeated babelconnect.v1.Account accounts = 19;
+     */
+    accounts = [];
     constructor(data) {
         super();
         proto3.util.initPartial(data, this);
@@ -1032,6 +1111,7 @@ export class AgentInfo extends Message {
         { 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 */ },
+        { no: 19, name: "accounts", kind: "message", T: Account, repeated: true },
     ]);
     static fromBinary(bytes, options) {
         return new AgentInfo().fromBinary(bytes, options);
@@ -1465,6 +1545,7 @@ export class StateUpdate extends Message {
         { 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" },
+        { no: 6, name: "ping", kind: "message", T: Ping, oneof: "update" },
     ]);
     static fromBinary(bytes, options) {
         return new StateUpdate().fromBinary(bytes, options);
@@ -1510,6 +1591,43 @@ export class Keepalive extends Message {
         return proto3.util.equals(Keepalive, a, b);
     }
 }
+/**
+ * Ping is a liveness probe the server sends on the heartbeat tick (replacing the
+ * bare Keepalive frame). The client echoes `seq` back in a Pong command; the server
+ * measures round-trip time (RTT) from the reply and tracks per-session liveness.
+ * Like Keepalive it keeps the connection warm, carries no state, and does NOT
+ * advance `seq` — caches ignore it, and the reply is handled in the client's stream
+ * loop, not the state reducer. (APP-A5/CALL-M6.)
+ *
+ * @generated from message babelconnect.v1.Ping
+ */
+export class Ping extends Message {
+    /**
+     * @generated from field: uint64 seq = 1;
+     */
+    seq = protoInt64.zero;
+    constructor(data) {
+        super();
+        proto3.util.initPartial(data, this);
+    }
+    static runtime = proto3;
+    static typeName = "babelconnect.v1.Ping";
+    static fields = proto3.util.newFieldList(() => [
+        { no: 1, name: "seq", kind: "scalar", T: 4 /* ScalarType.UINT64 */ },
+    ]);
+    static fromBinary(bytes, options) {
+        return new Ping().fromBinary(bytes, options);
+    }
+    static fromJson(jsonValue, options) {
+        return new Ping().fromJson(jsonValue, options);
+    }
+    static fromJsonString(jsonString, options) {
+        return new Ping().fromJsonString(jsonString, options);
+    }
+    static equals(a, b) {
+        return proto3.util.equals(Ping, 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.
@@ -1695,6 +1813,7 @@ export class Command extends Message {
         { no: 27, name: "mute_conference_member", kind: "message", T: MuteConferenceMember, oneof: "command" },
         { no: 28, name: "set_conversation_open", kind: "message", T: SetConversationOpen, oneof: "command" },
         { no: 29, name: "mark_conversation_read", kind: "message", T: MarkConversationRead, oneof: "command" },
+        { no: 30, name: "pong", kind: "message", T: Pong, oneof: "command" },
     ]);
     static fromBinary(bytes, options) {
         return new Command().fromBinary(bytes, options);
@@ -1709,6 +1828,40 @@ export class Command extends Message {
         return proto3.util.equals(Command, a, b);
     }
 }
+/**
+ * Pong replies to a server Ping (StateUpdate.ping), echoing its `seq` so the server
+ * can match it to the outstanding ping and compute RTT. Sent automatically by the
+ * SDK from its stream-receive loop — not a user intent. (APP-A5/CALL-M6.)
+ *
+ * @generated from message babelconnect.v1.Pong
+ */
+export class Pong extends Message {
+    /**
+     * @generated from field: uint64 seq = 1;
+     */
+    seq = protoInt64.zero;
+    constructor(data) {
+        super();
+        proto3.util.initPartial(data, this);
+    }
+    static runtime = proto3;
+    static typeName = "babelconnect.v1.Pong";
+    static fields = proto3.util.newFieldList(() => [
+        { no: 1, name: "seq", kind: "scalar", T: 4 /* ScalarType.UINT64 */ },
+    ]);
+    static fromBinary(bytes, options) {
+        return new Pong().fromBinary(bytes, options);
+    }
+    static fromJson(jsonValue, options) {
+        return new Pong().fromJson(jsonValue, options);
+    }
+    static fromJsonString(jsonString, options) {
+        return new Pong().fromJsonString(jsonString, options);
+    }
+    static equals(a, b) {
+        return proto3.util.equals(Pong, a, b);
+    }
+}
 /**
  * @generated from message babelconnect.v1.Register
  */

package/dist/index.d.ts

@@ -12,6 +12,6 @@
 export { BabelconnectClient, type ConnectOptions } from "./client.js";
 export { StateCache } from "./state-cache.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 { BrowserWebrtcMedia, browserMediaFactory, MediaError, micErrorCode, MIC_NOT_FOUND, MIC_PERMISSION_DENIED, MIC_IN_USE, MEDIA_ANSWER_FAILED, 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

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

package/dist/media.d.ts

@@ -19,6 +19,33 @@ export interface Media {
 }
 /** Builds the {@link Media} for a given call id. */
 export type MediaFactory = (callId: string) => Media;
+/** No microphone hardware is available (`NotFoundError`). */
+export declare const MIC_NOT_FOUND = "mic_not_found";
+/** Microphone access was denied (`NotAllowedError` / `SecurityError`). */
+export declare const MIC_PERMISSION_DENIED = "mic_permission_denied";
+/** The microphone is held by another application (`NotReadableError` / `AbortError`). */
+export declare const MIC_IN_USE = "mic_in_use";
+/** The pre-existing catch-all, kept as the fallback when the cause is unclear. */
+export declare const MEDIA_ANSWER_FAILED = "media_answer_failed";
+/**
+ * Thrown by a {@link Media} implementation when it cannot start audio for a
+ * call — e.g. the microphone is missing, permission was denied, or the device
+ * is held by another app (CALL-M5). {@link code} is a stable classification the
+ * SDK surfaces on `onError` (and hosts receive as `cti.error`) so the UI can
+ * show cause-specific help instead of a raw WebRTC string.
+ */
+export declare class MediaError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Classify a caught `getUserMedia` failure into one of the mic error codes,
+ * falling back to {@link MEDIA_ANSWER_FAILED} when the cause can't be told
+ * apart. On the web the real `DOMException` is available so we read its `.name`;
+ * the string form is also scanned as a fallback (and to stay in step with the
+ * Dart classifier, which only has the collapsed `'Unable to getUserMedia: …'`).
+ */
+export declare function micErrorCode(error: unknown): string;
 /**
  * The default browser WebRTC backend: capture the mic, answer the server's offer
  * (non-trickle ICE), and play the remote audio through a hidden `<audio>` element.

package/dist/media.js

@@ -1,3 +1,57 @@
+/** No microphone hardware is available (`NotFoundError`). */
+export const MIC_NOT_FOUND = "mic_not_found";
+/** Microphone access was denied (`NotAllowedError` / `SecurityError`). */
+export const MIC_PERMISSION_DENIED = "mic_permission_denied";
+/** The microphone is held by another application (`NotReadableError` / `AbortError`). */
+export const MIC_IN_USE = "mic_in_use";
+/** The pre-existing catch-all, kept as the fallback when the cause is unclear. */
+export const MEDIA_ANSWER_FAILED = "media_answer_failed";
+/**
+ * Thrown by a {@link Media} implementation when it cannot start audio for a
+ * call — e.g. the microphone is missing, permission was denied, or the device
+ * is held by another app (CALL-M5). {@link code} is a stable classification the
+ * SDK surfaces on `onError` (and hosts receive as `cti.error`) so the UI can
+ * show cause-specific help instead of a raw WebRTC string.
+ */
+export class MediaError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "MediaError";
+    }
+}
+/**
+ * Classify a caught `getUserMedia` failure into one of the mic error codes,
+ * falling back to {@link MEDIA_ANSWER_FAILED} when the cause can't be told
+ * apart. On the web the real `DOMException` is available so we read its `.name`;
+ * the string form is also scanned as a fallback (and to stay in step with the
+ * Dart classifier, which only has the collapsed `'Unable to getUserMedia: …'`).
+ */
+export function micErrorCode(error) {
+    const name = typeof DOMException !== "undefined" && error instanceof DOMException
+        ? error.name
+        : "";
+    const s = `${name} ${String(error)}`.toLowerCase();
+    if (s.includes("notfound") || s.includes("not found") || s.includes("no device")) {
+        return MIC_NOT_FOUND;
+    }
+    if (s.includes("notallowed") ||
+        s.includes("permissiondenied") ||
+        s.includes("permission denied") ||
+        s.includes("security") ||
+        s.includes("denied")) {
+        return MIC_PERMISSION_DENIED;
+    }
+    if (s.includes("notreadable") ||
+        s.includes("trackstart") ||
+        s.includes("abort") ||
+        s.includes("in use") ||
+        s.includes("busy")) {
+        return MIC_IN_USE;
+    }
+    return MEDIA_ANSWER_FAILED;
+}
 /**
  * The default browser WebRTC backend: capture the mic, answer the server's offer
  * (non-trickle ICE), and play the remote audio through a hidden `<audio>` element.
@@ -35,8 +89,17 @@ export class BrowserWebrtcMedia {
             el.srcObject = stream;
             void el.play().catch(() => { });
         };
-        // Capture the microphone and add it to the peer.
-        const local = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
+        // Capture the microphone and add it to the peer. Classify a failure (no mic
+        // / permission denied / device busy) into a MediaError the SDK surfaces with
+        // a distinct code (CALL-M5) so the UI/host can explain it, instead of the
+        // opaque `media_answer_failed`.
+        let local;
+        try {
+            local = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
+        }
+        catch (e) {
+            throw new MediaError(micErrorCode(e), String(e));
+        }
         this.local = local;
         for (const track of local.getAudioTracks())
             pc.addTrack(track, local);

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.11.0";

package/dist/version.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-version.mjs (npm prebuild) from package.json.
+// Do not edit by hand.
+export const SDK_VERSION = "0.11.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babelforce/babelconnect-sdk",
-  "version": "0.9.1",
+  "version": "0.11.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/",
@@ -24,6 +24,7 @@
   },
   "scripts": {
     "generate": "echo 'run `task gen` at the repo root (buf generate emits src/gen)'",
+    "prebuild": "node scripts/gen-version.mjs",
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test test/*.test.mjs",