livekit-server-sdk 2.3.0 → 2.5.0

package/src/SipClient.ts

@@ -0,0 +1,427 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import {
+  CreateSIPDispatchRuleRequest,
+  CreateSIPInboundTrunkRequest,
+  CreateSIPOutboundTrunkRequest,
+  CreateSIPParticipantRequest,
+  CreateSIPTrunkRequest,
+  DeleteSIPDispatchRuleRequest,
+  DeleteSIPTrunkRequest,
+  ListSIPDispatchRuleRequest,
+  ListSIPDispatchRuleResponse,
+  ListSIPInboundTrunkRequest,
+  ListSIPInboundTrunkResponse,
+  ListSIPOutboundTrunkRequest,
+  ListSIPOutboundTrunkResponse,
+  ListSIPTrunkRequest,
+  ListSIPTrunkResponse,
+  SIPDispatchRule,
+  SIPDispatchRuleDirect,
+  SIPDispatchRuleIndividual,
+  SIPDispatchRuleInfo,
+  SIPInboundTrunkInfo,
+  SIPOutboundTrunkInfo,
+  SIPParticipantInfo,
+  SIPTransport,
+  SIPTrunkInfo,
+} from '@livekit/protocol';
+import ServiceBase from './ServiceBase.js';
+import { Rpc, TwirpRpc, livekitPackage } from './TwirpRPC.js';
+
+const svc = 'SIP';
+
+/**
+ * @deprecated use CreateSipInboundTrunkOptions or CreateSipOutboundTrunkOptions
+ */
+export interface CreateSipTrunkOptions {
+  name?: string;
+  metadata?: string;
+  inbound_addresses?: string[];
+  inbound_numbers?: string[];
+  inbound_username?: string;
+  inbound_password?: string;
+  outbound_address?: string;
+  outbound_username?: string;
+  outbound_password?: string;
+}
+export interface CreateSipInboundTrunkOptions {
+  metadata?: string;
+  allowed_addresses?: string[];
+  allowed_numbers?: string[];
+  auth_username?: string;
+  auth_password?: string;
+}
+export interface CreateSipOutboundTrunkOptions {
+  metadata?: string;
+  transport: SIPTransport;
+  auth_username?: string;
+  auth_password?: string;
+}
+
+export interface SipDispatchRuleDirect {
+  type: 'direct';
+  roomName: string;
+  pin?: string;
+}
+
+export interface SipDispatchRuleIndividual {
+  type: 'individual';
+  roomPrefix: string;
+  pin?: string;
+}
+
+export interface CreateSipDispatchRuleOptions {
+  name?: string;
+  metadata?: string;
+  trunkIds?: string[];
+  hidePhoneNumber?: boolean;
+}
+
+export interface CreateSipParticipantOptions {
+  participantIdentity?: string;
+  participantName?: string;
+  participantMetadata?: string;
+  dtmf?: string;
+  playRingtone?: boolean;
+  hidePhoneNumber?: boolean;
+}
+
+/**
+ * Client to access Egress APIs
+ */
+export class SipClient extends ServiceBase {
+  private readonly rpc: Rpc;
+
+  /**
+   * @param host hostname including protocol. i.e. 'https://cluster.livekit.io'
+   * @param apiKey API Key, can be set in env var LIVEKIT_API_KEY
+   * @param secret API Secret, can be set in env var LIVEKIT_API_SECRET
+   */
+  constructor(host: string, apiKey?: string, secret?: string) {
+    super(apiKey, secret);
+    this.rpc = new TwirpRpc(host, livekitPackage);
+  }
+
+  /**
+   * @param number phone number of the trunk
+   * @param opts CreateSipTrunkOptions
+   * @deprecated use createSipInboundTrunk or createSipOutboundTrunk
+   */
+  async createSipTrunk(number: string, opts?: CreateSipTrunkOptions): Promise<SIPTrunkInfo> {
+    let inboundAddresses: string[] | undefined;
+    let inboundNumbers: string[] | undefined;
+    let inboundUsername: string = '';
+    let inboundPassword: string = '';
+    let outboundAddress: string = '';
+    let outboundUsername: string = '';
+    let outboundPassword: string = '';
+    let name: string = '';
+    let metadata: string = '';
+
+    if (opts !== undefined) {
+      inboundAddresses = opts.inbound_addresses;
+      inboundNumbers = opts.inbound_numbers;
+      inboundUsername = opts.inbound_username || '';
+      inboundPassword = opts.inbound_password || '';
+      outboundAddress = opts.outbound_address || '';
+      outboundUsername = opts.outbound_username || '';
+      outboundPassword = opts.outbound_password || '';
+      name = opts.name || '';
+      metadata = opts.metadata || '';
+    }
+
+    const req = new CreateSIPTrunkRequest({
+      name: name,
+      metadata: metadata,
+      inboundAddresses: inboundAddresses,
+      inboundNumbers: inboundNumbers,
+      inboundUsername: inboundUsername,
+      inboundPassword: inboundPassword,
+      outboundNumber: number,
+      outboundAddress: outboundAddress,
+      outboundUsername: outboundUsername,
+      outboundPassword: outboundPassword,
+    }).toJson();
+
+    const data = await this.rpc.request(
+      svc,
+      'CreateSIPTrunk',
+      req,
+      await this.authHeader({}, { admin: true }),
+    );
+    return SIPTrunkInfo.fromJson(data, { ignoreUnknownFields: true });
+  }
+
+  /**
+   @param name human-readable name of the trunk
+   * @param numbers phone numbers of the trunk
+   * @param opts CreateSipTrunkOptions
+   */
+  async createSipInboundTrunk(
+    name: string,
+    numbers: string[],
+    opts?: CreateSipInboundTrunkOptions,
+  ): Promise<SIPInboundTrunkInfo> {
+    let allowedAddresses: string[] | undefined;
+    let allowedNumbers: string[] | undefined;
+    let authUsername: string = '';
+    let authPassword: string = '';
+    let metadata: string = '';
+
+    if (opts !== undefined) {
+      allowedAddresses = opts.allowed_addresses;
+      allowedNumbers = opts.allowed_numbers;
+      authUsername = opts.auth_username || '';
+      authPassword = opts.auth_password || '';
+      metadata = opts.metadata || '';
+    }
+
+    const req = new CreateSIPInboundTrunkRequest({
+      trunk: new SIPInboundTrunkInfo({
+        name: name,
+        numbers: numbers,
+        metadata: metadata,
+        allowedAddresses: allowedAddresses,
+        allowedNumbers: allowedNumbers,
+        authUsername: authUsername,
+        authPassword: authPassword,
+      }),
+    }).toJson();
+
+    const data = await this.rpc.request(
+      svc,
+      'CreateSIPInboundTrunk',
+      req,
+      await this.authHeader({}, { admin: true }),
+    );
+    return SIPInboundTrunkInfo.fromJson(data, { ignoreUnknownFields: true });
+  }
+
+  /**
+   * @param name human-readable name of the trunk
+   * @param address hostname and port of the SIP server to dial
+   * @param numbers phone numbers of the trunk
+   * @param opts CreateSipTrunkOptions
+   */
+  async createSipOutboundTrunk(
+    name: string,
+    address: string,
+    numbers: string[],
+    opts?: CreateSipOutboundTrunkOptions,
+  ): Promise<SIPOutboundTrunkInfo> {
+    let authUsername: string = '';
+    let authPassword: string = '';
+    let transport: SIPTransport = SIPTransport.SIP_TRANSPORT_AUTO;
+    let metadata: string = '';
+
+    if (opts !== undefined) {
+      authUsername = opts.auth_username || '';
+      authPassword = opts.auth_password || '';
+      transport = opts.transport || SIPTransport.SIP_TRANSPORT_AUTO;
+      metadata = opts.metadata || '';
+    }
+
+    const req = new CreateSIPOutboundTrunkRequest({
+      trunk: new SIPOutboundTrunkInfo({
+        name: name,
+        address: address,
+        numbers: numbers,
+        metadata: metadata,
+        transport: transport,
+        authUsername: authUsername,
+        authPassword: authPassword,
+      }),
+    }).toJson();
+
+    const data = await this.rpc.request(
+      svc,
+      'CreateSIPOutboundTrunk',
+      req,
+      await this.authHeader({}, { admin: true }),
+    );
+    return SIPOutboundTrunkInfo.fromJson(data, { ignoreUnknownFields: true });
+  }
+
+  /**
+   * @deprecated use listSipInboundTrunk or listSipOutboundTrunk
+   */
+  async listSipTrunk(): Promise<Array<SIPTrunkInfo>> {
+    const req: Partial<ListSIPTrunkRequest> = {};
+    const data = await this.rpc.request(
+      svc,
+      'ListSIPTrunk',
+      new ListSIPTrunkRequest(req).toJson(),
+      await this.authHeader({}, { admin: true }),
+    );
+    return ListSIPTrunkResponse.fromJson(data, { ignoreUnknownFields: true }).items ?? [];
+  }
+
+  async listSipInboundTrunk(): Promise<Array<SIPInboundTrunkInfo>> {
+    const req: Partial<ListSIPInboundTrunkRequest> = {};
+    const data = await this.rpc.request(
+      svc,
+      'ListSIPInboundTrunk',
+      new ListSIPInboundTrunkRequest(req).toJson(),
+      await this.authHeader({}, { admin: true }),
+    );
+    return ListSIPInboundTrunkResponse.fromJson(data, { ignoreUnknownFields: true }).items ?? [];
+  }
+
+  async listSipOutboundTrunk(): Promise<Array<SIPOutboundTrunkInfo>> {
+    const req: Partial<ListSIPOutboundTrunkRequest> = {};
+    const data = await this.rpc.request(
+      svc,
+      'ListSIPOutboundTrunk',
+      new ListSIPOutboundTrunkRequest(req).toJson(),
+      await this.authHeader({}, { admin: true }),
+    );
+    return ListSIPOutboundTrunkResponse.fromJson(data, { ignoreUnknownFields: true }).items ?? [];
+  }
+
+  /**
+   * @param sipTrunkId sip trunk to delete
+   */
+  async deleteSipTrunk(sipTrunkId: string): Promise<SIPTrunkInfo> {
+    const data = await this.rpc.request(
+      svc,
+      'DeleteSIPTrunk',
+      new DeleteSIPTrunkRequest({ sipTrunkId }).toJson(),
+      await this.authHeader({}, { admin: true }),
+    );
+    return SIPTrunkInfo.fromJson(data, { ignoreUnknownFields: true });
+  }
+
+  /**
+   * @param rule sip dispatch rule
+   * @param opts CreateSipDispatchRuleOptions
+   */
+  async createSipDispatchRule(
+    rule: SipDispatchRuleDirect | SipDispatchRuleIndividual,
+    opts?: CreateSipDispatchRuleOptions,
+  ): Promise<SIPDispatchRuleInfo> {
+    let trunkIds: string[] | undefined;
+    let hidePhoneNumber: boolean = false;
+    let name: string = '';
+    let metadata: string = '';
+    let ruleProto: SIPDispatchRule | undefined = undefined;
+
+    if (opts !== undefined) {
+      trunkIds = opts.trunkIds;
+      hidePhoneNumber = opts.hidePhoneNumber || false;
+      name = opts.name || '';
+      metadata = opts.metadata || '';
+    }
+    if (rule.type == 'direct') {
+      ruleProto = new SIPDispatchRule({
+        rule: {
+          case: 'dispatchRuleDirect',
+          value: new SIPDispatchRuleDirect({
+            roomName: rule.roomName,
+            pin: rule.pin || '',
+          }),
+        },
+      });
+    } else if (rule.type == 'individual') {
+      ruleProto = new SIPDispatchRule({
+        rule: {
+          case: 'dispatchRuleIndividual',
+          value: new SIPDispatchRuleIndividual({
+            roomPrefix: rule.roomPrefix,
+            pin: rule.pin || '',
+          }),
+        },
+      });
+    }
+
+    const req = new CreateSIPDispatchRuleRequest({
+      rule: ruleProto,
+      trunkIds: trunkIds,
+      hidePhoneNumber: hidePhoneNumber,
+      name: name,
+      metadata: metadata,
+    }).toJson();
+
+    const data = await this.rpc.request(
+      svc,
+      'CreateSIPDispatchRule',
+      req,
+      await this.authHeader({}, { admin: true }),
+    );
+    return SIPDispatchRuleInfo.fromJson(data, { ignoreUnknownFields: true });
+  }
+
+  async listSipDispatchRule(): Promise<Array<SIPDispatchRuleInfo>> {
+    const req: Partial<ListSIPDispatchRuleRequest> = {};
+    const data = await this.rpc.request(
+      svc,
+      'ListSIPDispatchRule',
+      new ListSIPDispatchRuleRequest(req).toJson(),
+      await this.authHeader({}, { admin: true }),
+    );
+    return ListSIPDispatchRuleResponse.fromJson(data, { ignoreUnknownFields: true }).items ?? [];
+  }
+
+  /**
+   * @param sipDispatchRuleId sip trunk to delete
+   */
+  async deleteSipDispatchRule(sipDispatchRuleId: string): Promise<SIPDispatchRuleInfo> {
+    const data = await this.rpc.request(
+      svc,
+      'DeleteSIPDispatchRule',
+      new DeleteSIPDispatchRuleRequest({ sipDispatchRuleId }).toJson(),
+      await this.authHeader({}, { admin: true }),
+    );
+    return SIPDispatchRuleInfo.fromJson(data, { ignoreUnknownFields: true });
+  }
+
+  /**
+   * @param sipTrunkId sip trunk to use for the call
+   * @param number number to dial
+   * @param roomName room to attach the call to
+   * @param opts CreateSipParticipantOptions
+   */
+  async createSipParticipant(
+    sipTrunkId: string,
+    number: string,
+    roomName: string,
+    opts?: CreateSipParticipantOptions,
+  ): Promise<SIPParticipantInfo> {
+    let participantIdentity: string = '';
+    let participantName: string = '';
+    let participantMetadata: string = '';
+    let dtmf: string = '';
+    let playRingtone: boolean = false;
+    let hidePhoneNumber: boolean = false;
+
+    if (opts !== undefined) {
+      participantIdentity = opts.participantIdentity || '';
+      participantName = opts.participantName || '';
+      participantMetadata = opts.participantMetadata || '';
+      dtmf = opts.dtmf || '';
+      playRingtone = opts.playRingtone || false;
+      hidePhoneNumber = opts.hidePhoneNumber || false;
+    }
+
+    const req = new CreateSIPParticipantRequest({
+      sipTrunkId: sipTrunkId,
+      sipCallTo: number,
+      roomName: roomName,
+      participantIdentity: participantIdentity,
+      participantName: participantName,
+      participantMetadata: participantMetadata,
+      dtmf: dtmf,
+      playRingtone: playRingtone,
+      hidePhoneNumber: hidePhoneNumber,
+    }).toJson();
+
+    const data = await this.rpc.request(
+      svc,
+      'CreateSIPParticipant',
+      req,
+      await this.authHeader({}, { call: true }),
+    );
+    return SIPParticipantInfo.fromJson(data, { ignoreUnknownFields: true });
+  }
+}

package/src/TwirpRPC.ts

@@ -0,0 +1,54 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import type { JsonValue } from '@bufbuild/protobuf';
+import camelcaseKeys from 'camelcase-keys';
+
+// twirp RPC adapter for client implementation
+
+const defaultPrefix = '/twirp';
+
+export const livekitPackage = 'livekit';
+export interface Rpc {
+  request(service: string, method: string, data: JsonValue, headers?: any): Promise<string>;
+}
+
+/**
+ * JSON based Twirp V7 RPC
+ */
+export class TwirpRpc {
+  host: string;
+
+  pkg: string;
+
+  prefix: string;
+
+  constructor(host: string, pkg: string, prefix?: string) {
+    if (host.startsWith('ws')) {
+      host = host.replace('ws', 'http');
+    }
+    this.host = host;
+    this.pkg = pkg;
+    this.prefix = prefix || defaultPrefix;
+  }
+
+  async request(service: string, method: string, data: any, headers?: any): Promise<any> {
+    const path = `${this.prefix}/${this.pkg}.${service}/${method}`;
+    const url = new URL(path, this.host);
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json;charset=UTF-8',
+        ...headers,
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Request failed with status ${response.status}: ${response.statusText}`);
+    }
+    const parsedResp = await response.json();
+    return camelcaseKeys(parsedResp, { deep: true });
+  }
+}

package/src/WebhookReceiver.test.ts

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+import { AccessToken } from './AccessToken.js';
+import { WebhookEvent, WebhookReceiver } from './WebhookReceiver.js';
+
+const testApiKey = 'abcdefg';
+const testSecret = 'abababa';
+
+describe('webhook receiver', () => {
+  const body =
+    '{"event":"room_started", "room":{"sid":"RM_TkVjUvAqgzKz", "name":"mytestroom", "emptyTimeout":300, "creationTime":"1628545903", "turnPassword":"ICkSr2rEeslkN6e9bXL4Ji5zzMD5Z7zzr6ulOaxMj6N", "enabledCodecs":[{"mime":"audio/opus"}, {"mime":"video/VP8"}]}}';
+  const sha = 'CoEQz1chqJ9bnZRcORddjplkvpjmPujmLTR42DbefYI=';
+  const t = new AccessToken(testApiKey, testSecret);
+  t.sha256 = sha;
+
+  const receiver = new WebhookReceiver(testApiKey, testSecret);
+
+  it('should receive and decode WebhookEvent', async () => {
+    const token = await t.toJwt();
+    const event = await receiver.receive(body, token);
+    expect(event).toBeTruthy();
+    expect(event.room?.name).toBe('mytestroom');
+    expect(event.event).toBe('room_started');
+  });
+});
+
+describe('decoding json payload', () => {
+  it('should allow server to return extra fields', () => {
+    const obj = {
+      type: 'room_started',
+      room: {
+        sid: 'RM_TkVjUvAqgzKz',
+        name: 'mytestroom',
+      },
+      extra: 'extra',
+    };
+
+    const event = new WebhookEvent(obj);
+    expect(event).toBeTruthy();
+    expect(event.room?.name).toBe('mytestroom');
+  });
+});

package/src/WebhookReceiver.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import type { BinaryReadOptions, JsonReadOptions, JsonValue } from '@bufbuild/protobuf';
+import { WebhookEvent as ProtoWebhookEvent } from '@livekit/protocol';
+import { TokenVerifier } from './AccessToken.js';
+
+export const authorizeHeader = 'Authorize';
+
+export class WebhookEvent extends ProtoWebhookEvent {
+  event: WebhookEventNames = '';
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): WebhookEvent {
+    return new WebhookEvent().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): WebhookEvent {
+    return new WebhookEvent().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): WebhookEvent {
+    return new WebhookEvent().fromJsonString(jsonString, options);
+  }
+}
+
+export type WebhookEventNames =
+  | 'room_started'
+  | 'room_finished'
+  | 'participant_joined'
+  | 'participant_left'
+  | 'track_published'
+  | 'track_unpublished'
+  | 'egress_started'
+  | 'egress_updated'
+  | 'egress_ended'
+  | 'ingress_started'
+  | 'ingress_ended'
+  /**
+   * @internal
+   * @note only used as a default value, not a valid webhook event
+   */
+  | '';
+
+export class WebhookReceiver {
+  private verifier: TokenVerifier;
+
+  constructor(apiKey: string, apiSecret: string) {
+    this.verifier = new TokenVerifier(apiKey, apiSecret);
+  }
+
+  /**
+   *
+   * @param body string of the posted body
+   * @param authHeader `Authorization` header from the request
+   * @param skipAuth true to skip auth validation
+   * @returns
+   */
+  async receive(
+    body: string,
+    authHeader?: string,
+    skipAuth: boolean = false,
+  ): Promise<WebhookEvent> {
+    // verify token
+    if (!skipAuth) {
+      if (!authHeader) {
+        throw new Error('authorization header is empty');
+      }
+      const claims = await this.verifier.verify(authHeader);
+      // confirm sha
+      const encoder = new TextEncoder();
+      const hash = await crypto.subtle.digest('SHA-256', encoder.encode(body));
+      const hashDecoded = btoa(
+        Array.from(new Uint8Array(hash))
+          .map((v) => String.fromCharCode(v))
+          .join(''),
+      );
+
+      if (claims.sha256 !== hashDecoded) {
+        throw new Error('sha256 checksum of body does not match');
+      }
+    }
+
+    return WebhookEvent.fromJson(JSON.parse(body), { ignoreUnknownFields: true });
+  }
+}

package/src/grants.test.ts

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { TrackSource } from '@livekit/protocol';
+import { describe, expect, it } from 'vitest';
+import { ClaimGrants, VideoGrant, claimsToJwtPayload } from './grants';
+
+describe('ClaimGrants are parsed correctly', () => {
+  it('parses TrackSource correctly to strings', () => {
+    const grant: VideoGrant = {
+      canPublishSources: [
+        TrackSource.CAMERA,
+        TrackSource.MICROPHONE,
+        TrackSource.SCREEN_SHARE,
+        TrackSource.SCREEN_SHARE_AUDIO,
+      ],
+    };
+
+    const claim: ClaimGrants = { video: grant };
+
+    const jwtPayload = claimsToJwtPayload(claim);
+    expect(jwtPayload.video).toBeTypeOf('object');
+    expect(jwtPayload.video?.canPublishSources).toEqual([
+      'camera',
+      'microphone',
+      'screen_share',
+      'screen_share_audio',
+    ]);
+  });
+});