livekit-server-sdk 2.15.5 → 2.17.0

package/src/LiveKitAPI.ts

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { AgentDispatchClient } from './AgentDispatchClient.js';
+import type { ClientOptions } from './ClientOptions.js';
+import { ConnectorClient } from './ConnectorClient.js';
+import { EgressClient } from './EgressClient.js';
+import { IngressClient } from './IngressClient.js';
+import { RoomServiceClient } from './RoomServiceClient.js';
+import { SipClient } from './SipClient.js';
+
+/** Server host and non-auth options, shared by both authentication modes. */
+interface LiveKitAPICommonOptions {
+  /** Server host, including protocol. Falls back to the `LIVEKIT_URL` env var. */
+  host?: string;
+  /** Optional timeout, in seconds, for all server requests. */
+  requestTimeout?: number;
+  /**
+   * Whether to fail over to alternative regions on retryable errors (LiveKit
+   * Cloud hosts only). Defaults to true; set to false to disable.
+   */
+  failover?: boolean;
+}
+
+/** API key and secret authentication (recommended for backend use). */
+interface ApiKeyAuth {
+  /** API key. Falls back to the `LIVEKIT_API_KEY` env var. */
+  apiKey?: string;
+  /** API secret. Falls back to the `LIVEKIT_API_SECRET` env var. */
+  secret?: string;
+  token?: never;
+}
+
+/** Pre-signed token authentication (client-side use; no secret required). */
+interface TokenAuth {
+  /** Pre-signed token, sent verbatim. Falls back to the `LIVEKIT_TOKEN` env var. */
+  token: string;
+  apiKey?: never;
+  secret?: never;
+}
+
+/**
+ * Options for {@link LiveKitAPI}. Provide either an `apiKey` and `secret` or a
+ * pre-signed `token` — the two modes are mutually exclusive. Any omitted value
+ * falls back to its environment variable (`LIVEKIT_URL`, `LIVEKIT_API_KEY`,
+ * `LIVEKIT_API_SECRET`, `LIVEKIT_TOKEN`).
+ */
+export type LiveKitAPIOptions = LiveKitAPICommonOptions & (ApiKeyAuth | TokenAuth);
+
+/**
+ * A single entry point to every LiveKit server API, exposing each service
+ * through a property, e.g. `api.room.createRoom(...)`.
+ *
+ * @example
+ * ```ts
+ * const api = new LiveKitAPI({ apiKey, secret }); // or new LiveKitAPI() to read from env
+ * await api.room.createRoom({ name: 'my-room' });
+ * ```
+ */
+export class LiveKitAPI {
+  private readonly _room: RoomServiceClient;
+
+  private readonly _egress: EgressClient;
+
+  private readonly _ingress: IngressClient;
+
+  private readonly _sip: SipClient;
+
+  private readonly _agentDispatch: AgentDispatchClient;
+
+  private readonly _connector: ConnectorClient;
+
+  /**
+   * @param options - server host, credentials, and client options; each value
+   *   falls back to its environment variable when omitted.
+   */
+  constructor(options: LiveKitAPIOptions = {}) {
+    const host = options.host || process.env.LIVEKIT_URL;
+    if (!host) {
+      throw new Error('host is required (pass it or set LIVEKIT_URL)');
+    }
+    const { apiKey, secret } = options;
+    // Only fall back to LIVEKIT_TOKEN when no explicit credentials were given, so
+    // an ambient token can't silently override a passed-in api key and secret.
+    const token = options.token || (apiKey || secret ? undefined : process.env.LIVEKIT_TOKEN);
+    if (!token && !(apiKey ?? process.env.LIVEKIT_API_KEY)) {
+      throw new Error('either a token or an API key and secret are required');
+    }
+
+    const clientOptions: ClientOptions = {
+      requestTimeout: options.requestTimeout,
+      failover: options.failover,
+      token,
+    };
+    this._room = new RoomServiceClient(host, apiKey, secret, clientOptions);
+    this._egress = new EgressClient(host, apiKey, secret, clientOptions);
+    this._ingress = new IngressClient(host, apiKey, secret, clientOptions);
+    this._sip = new SipClient(host, apiKey, secret, clientOptions);
+    this._agentDispatch = new AgentDispatchClient(host, apiKey, secret, clientOptions);
+    this._connector = new ConnectorClient(host, apiKey, secret, clientOptions);
+  }
+
+  get room(): RoomServiceClient {
+    return this._room;
+  }
+
+  get egress(): EgressClient {
+    return this._egress;
+  }
+
+  get ingress(): IngressClient {
+    return this._ingress;
+  }
+
+  get sip(): SipClient {
+    return this._sip;
+  }
+
+  get agentDispatch(): AgentDispatchClient {
+    return this._agentDispatch;
+  }
+
+  get connector(): ConnectorClient {
+    return this._connector;
+  }
+}

package/src/RoomServiceClient.ts

@@ -131,11 +131,11 @@ export class RoomServiceClient extends ServiceBase {
    * @param options - client options
    */
   constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
-    super(apiKey, secret);
-    const rpcOptions = options?.requestTimeout
-      ? { requestTimeout: options.requestTimeout }
-      : undefined;
-    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
+    super({ apiKey, secret, token: options?.token });
+    this.rpc = new TwirpRpc(host, livekitPackage, {
+      requestTimeout: options?.requestTimeout,
+      failover: options?.failover,
+    });
   }
 
   /**

package/src/ServiceBase.ts

@@ -4,6 +4,20 @@
 import { AccessToken } from './AccessToken.js';
 import type { SIPGrant, VideoGrant } from './grants.js';
 
+/**
+ * Authentication options for a service client.
+ */
+export interface ServiceBaseOptions {
+  /** API Key. */
+  apiKey?: string;
+  /** API Secret. */
+  secret?: string;
+  /** Token TTL. Defaults to `10m`. */
+  ttl?: string;
+  /** Pre-signed token; sent verbatim, skipping per-call signing. */
+  token?: string;
+}
+
 /**
  * Utilities to handle authentication
  */
@@ -12,20 +26,37 @@ export class ServiceBase {
 
   private readonly secret?: string;
 
+  private readonly token?: string;
+
   private readonly ttl: string;
 
   /**
+   * @param options - authentication options
+   */
+  constructor(options?: ServiceBaseOptions);
+  /**
+   * @deprecated pass a {@link ServiceBaseOptions} object instead.
    * @param apiKey - API Key.
    * @param secret - API Secret.
    * @param ttl - token TTL
    */
-  constructor(apiKey?: string, secret?: string, ttl?: string) {
-    this.apiKey = apiKey;
-    this.secret = secret;
-    this.ttl = ttl || '10m';
+  constructor(apiKey?: string, secret?: string, ttl?: string);
+  constructor(apiKeyOrOptions?: string | ServiceBaseOptions, secret?: string, ttl?: string) {
+    const options: ServiceBaseOptions =
+      typeof apiKeyOrOptions === 'object'
+        ? apiKeyOrOptions
+        : { apiKey: apiKeyOrOptions, secret, ttl };
+    this.apiKey = options.apiKey;
+    this.secret = options.secret;
+    this.ttl = options.ttl || '10m';
+    this.token = options.token;
   }
 
   async authHeader(grant: VideoGrant, sip?: SIPGrant): Promise<Record<string, string>> {
+    // A pre-signed token is sent verbatim; the caller is responsible for its grants.
+    if (this.token) {
+      return { Authorization: `Bearer ${this.token}` };
+    }
     const at = new AccessToken(this.apiKey, this.secret, { ttl: this.ttl });
     if (grant) {
       at.addGrant(grant);

package/src/SipClient.ts

@@ -7,6 +7,7 @@ import type {
   Pagination,
   RoomConfiguration,
   SIPHeaderOptions,
+  SIPMediaConfig,
   SIPMediaEncryption,
   SIPOutboundConfig,
 } from '@livekit/protocol';
@@ -27,6 +28,7 @@ import {
   ListSIPTrunkRequest,
   ListSIPTrunkResponse,
   SIPDispatchRule,
+  SIPDispatchRuleCallee,
   SIPDispatchRuleDirect,
   SIPDispatchRuleIndividual,
   SIPDispatchRuleInfo,
@@ -43,7 +45,17 @@ import {
 import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import type { Rpc } from './TwirpRPC.js';
-import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
+import { ServerError, SipCallError, TwirpRpc, livekitPackage } from './TwirpRPC.js';
+import { DEFAULT_RINGING_TIMEOUT_SECONDS, dialRequestTimeout } from './dialTimeout.js';
+
+// A SIP dialing failure carries a SIP status in its error metadata; surface it as
+// a SipCallError so callers can branch on the SIP code.
+function asSipCallError(e: unknown): unknown {
+  if (e instanceof ServerError && e.metadata && 'sip_status_code' in e.metadata) {
+    return SipCallError.fromServerError(e);
+  }
+  return e;
+}
 
 const svc = 'SIP';
 
@@ -80,7 +92,9 @@ export interface CreateSipInboundTrunkOptions {
   // Map SIP response headers from INVITE to sip.h.* participant attributes automatically.
   includeHeaders?: SIPHeaderOptions;
   krispEnabled?: boolean;
+  /** @deprecated - use `media.encryption` instead */
   mediaEncryption?: SIPMediaEncryption;
+  media?: SIPMediaConfig;
   /** Maximum time for a call to ring in seconds. */
   ringingTimeout?: number;
 }
@@ -98,7 +112,9 @@ export interface CreateSipOutboundTrunkOptions {
   headersToAttributes?: { [key: string]: string };
   // Map SIP response headers from INVITE to sip.h.* participant attributes automatically.
   includeHeaders?: SIPHeaderOptions;
+  /** @deprecated - use `media.encryption` instead */
   mediaEncryption?: SIPMediaEncryption;
+  media?: SIPMediaConfig;
 }
 
 export interface SipDispatchRuleDirect {
@@ -113,6 +129,14 @@ export interface SipDispatchRuleIndividual {
   pin?: string;
 }
 
+export interface SipDispatchRuleCallee {
+  type: 'callee';
+  roomPrefix: string;
+  pin?: string;
+  /** Optionally append a random suffix to the room name. */
+  randomize?: boolean;
+}
+
 export interface CreateSipDispatchRuleOptions {
   name?: string;
   metadata?: string;
@@ -156,8 +180,9 @@ export interface CreateSipParticipantOptions {
   krispEnabled?: boolean;
   /** If `true`, this will wait until the call is answered before returning. */
   waitUntilAnswered?: boolean;
-  /** Optional request timeout in seconds. default 60 seconds if waitUntilAnswered is true, otherwise 10 seconds */
+  /** Optional request timeout in seconds. Defaults to 30s when waitUntilAnswered is true (dialing takes time), otherwise the client default. */
   timeout?: number;
+  media?: SIPMediaConfig;
 }
 
 export interface ListSipDispatchRuleOptions {
@@ -194,7 +219,9 @@ export interface SipInboundTrunkUpdateOptions {
   authPassword?: string;
   name?: string;
   metadata?: string;
+  /** @deprecated - use `media.encryption` instead */
   mediaEncryption?: SIPMediaEncryption;
+  media?: SIPMediaConfig;
 }
 
 export interface SipOutboundTrunkUpdateOptions {
@@ -206,7 +233,9 @@ export interface SipOutboundTrunkUpdateOptions {
   destinationCountry?: string;
   name?: string;
   metadata?: string;
+  /** @deprecated - use `media.encryption` instead */
   mediaEncryption?: SIPMediaEncryption;
+  media?: SIPMediaConfig;
 }
 
 export interface TransferSipParticipantOptions {
@@ -214,6 +243,8 @@ export interface TransferSipParticipantOptions {
   headers?: { [key: string]: string };
   /** Maximum time for the transfer destination to answer the call, in seconds. */
   ringingTimeout?: number;
+  /** Optional request timeout in seconds. Defaults to 30s (dialing takes time). */
+  timeout?: number;
 }
 
 /**
@@ -229,11 +260,11 @@ export class SipClient extends ServiceBase {
    * @param options - client options
    */
   constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
-    super(apiKey, secret);
-    const rpcOptions = options?.requestTimeout
-      ? { requestTimeout: options.requestTimeout }
-      : undefined;
-    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
+    super({ apiKey, secret, token: options?.token });
+    this.rpc = new TwirpRpc(host, livekitPackage, {
+      requestTimeout: options?.requestTimeout,
+      failover: options?.failover,
+    });
   }
 
   /**
@@ -316,6 +347,7 @@ export class SipClient extends ServiceBase {
         includeHeaders: opts.includeHeaders,
         krispEnabled: opts.krispEnabled,
         mediaEncryption: opts.mediaEncryption,
+        media: opts.media,
         ringingTimeout: opts.ringingTimeout
           ? new Duration({ seconds: BigInt(opts.ringingTimeout) })
           : undefined,
@@ -366,6 +398,7 @@ export class SipClient extends ServiceBase {
         includeHeaders: opts.includeHeaders,
         destinationCountry: opts.destinationCountry,
         mediaEncryption: opts.mediaEncryption,
+        media: opts.media,
       }),
     }).toJson();
 
@@ -450,7 +483,7 @@ export class SipClient extends ServiceBase {
    * @returns Created SIP dispatch rule
    */
   async createSipDispatchRule(
-    rule: SipDispatchRuleDirect | SipDispatchRuleIndividual,
+    rule: SipDispatchRuleDirect | SipDispatchRuleIndividual | SipDispatchRuleCallee,
     opts?: CreateSipDispatchRuleOptions,
   ): Promise<SIPDispatchRuleInfo> {
     if (opts === undefined) {
@@ -477,6 +510,17 @@ export class SipClient extends ServiceBase {
           }),
         },
       });
+    } else if (rule.type == 'callee') {
+      ruleProto = new SIPDispatchRule({
+        rule: {
+          case: 'dispatchRuleCallee',
+          value: new SIPDispatchRuleCallee({
+            roomPrefix: rule.roomPrefix,
+            pin: rule.pin || '',
+            randomize: rule.randomize || false,
+          }),
+        },
+      });
     }
 
     const req = new CreateSIPDispatchRuleRequest({
@@ -732,8 +776,13 @@ export class SipClient extends ServiceBase {
       opts = {};
     }
 
-    if (opts.timeout === undefined) {
-      opts.timeout = opts.waitUntilAnswered ? 60 : 10;
+    // Dialing a phone and waiting for an answer takes longer than a normal call,
+    // and the request must outlast ringing so the call can be answered. Pin the
+    // ring window explicitly so our request timeout doesn't depend on the server's
+    // default (which could change out from under us).
+    if (opts.waitUntilAnswered) {
+      opts.ringingTimeout ??= DEFAULT_RINGING_TIMEOUT_SECONDS;
+      opts.timeout = dialRequestTimeout(opts.timeout, opts.ringingTimeout);
     }
 
     const req = new CreateSIPParticipantRequest({
@@ -760,16 +809,21 @@ export class SipClient extends ServiceBase {
         : undefined,
       krispEnabled: opts.krispEnabled,
       waitUntilAnswered: opts.waitUntilAnswered,
+      media: opts.media,
     }).toJson();
 
-    const data = await this.rpc.request(
-      svc,
-      'CreateSIPParticipant',
-      req,
-      await this.authHeader({}, { call: true }),
-      opts.timeout,
-    );
-    return SIPParticipantInfo.fromJson(data, { ignoreUnknownFields: true });
+    try {
+      const data = await this.rpc.request(
+        svc,
+        'CreateSIPParticipant',
+        req,
+        await this.authHeader({}, { call: true }),
+        opts.timeout,
+      );
+      return SIPParticipantInfo.fromJson(data, { ignoreUnknownFields: true });
+    } catch (e) {
+      throw asSipCallError(e);
+    }
   }
 
   /**
@@ -790,6 +844,12 @@ export class SipClient extends ServiceBase {
       opts = {};
     }
 
+    // Transferring a call dials a phone, which takes longer than a normal call,
+    // so keep the request alive past ringing. Pin the ring window explicitly so
+    // our request timeout doesn't depend on the server's default.
+    opts.ringingTimeout ??= DEFAULT_RINGING_TIMEOUT_SECONDS;
+    opts.timeout = dialRequestTimeout(opts.timeout, opts.ringingTimeout);
+
     const req = new TransferSIPParticipantRequest({
       participantIdentity: participantIdentity,
       roomName: roomName,
@@ -801,11 +861,16 @@ export class SipClient extends ServiceBase {
         : undefined,
     }).toJson();
 
-    await this.rpc.request(
-      svc,
-      'TransferSIPParticipant',
-      req,
-      await this.authHeader({ roomAdmin: true, room: roomName }, { call: true }),
-    );
+    try {
+      await this.rpc.request(
+        svc,
+        'TransferSIPParticipant',
+        req,
+        await this.authHeader({ roomAdmin: true, room: roomName }, { call: true }),
+        opts.timeout,
+      );
+    } catch (e) {
+      throw asSipCallError(e);
+    }
   }
 }

package/src/TwirpRPC.test.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+import { ServerError, SipCallError } from './TwirpRPC.js';
+
+describe('SipCallError', () => {
+  it('renders the SIP status, Twirp code, and extra metadata', () => {
+    const err = SipCallError.fromServerError(
+      new ServerError(
+        'Too Many Requests',
+        'twirp error: sip status 486',
+        429,
+        'resource_exhausted',
+        {
+          sip_status_code: '486',
+          sip_status: 'Busy Here',
+          error_details: 'CAgS...base64...',
+          region: 'us-east',
+        },
+      ),
+    );
+
+    expect(err).toBeInstanceOf(ServerError);
+    expect(err.name).toBe('SipCallError');
+    expect(err.sipStatusCode).toBe(486);
+    expect(err.sipStatus).toBe('Busy Here');
+
+    const printed = err.toString();
+    expect(printed).toContain('SipCallError');
+    expect(printed).toContain('486');
+    expect(printed).toContain('Busy Here');
+    expect(printed).toContain('resource_exhausted');
+    expect(printed).toContain('region=us-east'); // other metadata is surfaced
+    expect(printed).not.toContain('error_details'); // opaque blob is omitted
+  });
+
+  it('falls back to the original message when there is no SIP status', () => {
+    const err = SipCallError.fromServerError(new ServerError('Internal', 'boom', 500, 'internal'));
+    expect(err.message).toBe('boom');
+  });
+});