livekit-server-sdk 2.2.0 → 2.4.0

package/src/SipClient.ts

@@ -0,0 +1,277 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import {
+  CreateSIPDispatchRuleRequest,
+  CreateSIPParticipantRequest,
+  CreateSIPTrunkRequest,
+  DeleteSIPDispatchRuleRequest,
+  DeleteSIPTrunkRequest,
+  ListSIPDispatchRuleRequest,
+  ListSIPDispatchRuleResponse,
+  ListSIPTrunkRequest,
+  ListSIPTrunkResponse,
+  SIPDispatchRule,
+  SIPDispatchRuleDirect,
+  SIPDispatchRuleIndividual,
+  SIPDispatchRuleInfo,
+  SIPParticipantInfo,
+  SIPTrunkInfo,
+} from '@livekit/protocol';
+import ServiceBase from './ServiceBase.js';
+import { Rpc, TwirpRpc, livekitPackage } from './TwirpRPC.js';
+
+const svc = 'SIP';
+
+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 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;
+}
+
+/**
+ * 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
+   */
+  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({}));
+    return SIPTrunkInfo.fromJson(data, { ignoreUnknownFields: true });
+  }
+
+  async listSipTrunk(): Promise<Array<SIPTrunkInfo>> {
+    const req: Partial<ListSIPTrunkRequest> = {};
+    const data = await this.rpc.request(
+      svc,
+      'ListSIPTrunk',
+      new ListSIPTrunkRequest(req).toJson(),
+      await this.authHeader({}),
+    );
+    return ListSIPTrunkResponse.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({}),
+    );
+    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({}),
+    );
+    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({}),
+    );
+    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({}),
+    );
+    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;
+
+    if (opts !== undefined) {
+      participantIdentity = opts.participantIdentity || '';
+      participantName = opts.participantName || '';
+      participantMetadata = opts.participantMetadata || '';
+      dtmf = opts.dtmf || '';
+      playRingtone = opts.playRingtone || false;
+    }
+
+    const req = new CreateSIPParticipantRequest({
+      sipTrunkId: sipTrunkId,
+      sipCallTo: number,
+      roomName: roomName,
+      participantIdentity: participantIdentity,
+      participantName: participantName,
+      participantMetadata: participantMetadata,
+      dtmf: dtmf,
+      playRingtone: playRingtone,
+    }).toJson();
+
+    const data = await this.rpc.request(
+      svc,
+      'CreateSIPParticipant',
+      req,
+      await this.authHeader({}),
+    );
+    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',
+    ]);
+  });
+});

package/src/grants.ts

@@ -0,0 +1,96 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { TrackSource } from '@livekit/protocol';
+import { JWTPayload } from 'jose';
+
+export function trackSourceToString(source: TrackSource) {
+  switch (source) {
+    case TrackSource.CAMERA:
+      return 'camera';
+    case TrackSource.MICROPHONE:
+      return 'microphone';
+    case TrackSource.SCREEN_SHARE:
+      return 'screen_share';
+    case TrackSource.SCREEN_SHARE_AUDIO:
+      return 'screen_share_audio';
+    default:
+      throw new TypeError(`Cannot convert TrackSource ${source} to string`);
+  }
+}
+
+export function claimsToJwtPayload(
+  grant: ClaimGrants,
+): JWTPayload & { video?: Record<string, unknown> } {
+  const claim: Record<string, any> = { ...grant };
+  // eslint-disable-next-line no-restricted-syntax
+  if (Array.isArray(claim.video?.canPublishSources)) {
+    claim.video.canPublishSources = claim.video.canPublishSources.map(trackSourceToString);
+  }
+  return claim;
+}
+
+export interface VideoGrant {
+  /** permission to create a room */
+  roomCreate?: boolean;
+
+  /** permission to join a room as a participant, room must be set */
+  roomJoin?: boolean;
+
+  /** permission to list rooms */
+  roomList?: boolean;
+
+  /** permission to start a recording */
+  roomRecord?: boolean;
+
+  /** permission to control a specific room, room must be set */
+  roomAdmin?: boolean;
+
+  /** name of the room, must be set for admin or join permissions */
+  room?: string;
+
+  /** permissions to control ingress, not specific to any room or ingress */
+  ingressAdmin?: boolean;
+
+  /**
+   * allow participant to publish. If neither canPublish or canSubscribe is set,
+   * both publish and subscribe are enabled
+   */
+  canPublish?: boolean;
+
+  /**
+   * TrackSource types that the participant is allowed to publish
+   * When set, it supersedes CanPublish. Only sources explicitly set here can be published
+   */
+  canPublishSources?: TrackSource[];
+
+  /** allow participant to subscribe to other tracks */
+  canSubscribe?: boolean;
+
+  /**
+   * allow participants to publish data, defaults to true if not set
+   */
+  canPublishData?: boolean;
+
+  /**
+   * by default, a participant is not allowed to update its own metadata
+   */
+  canUpdateOwnMetadata?: boolean;
+
+  /** participant isn't visible to others */
+  hidden?: boolean;
+
+  /** participant is recording the room, when set, allows room to indicate it's being recorded */
+  recorder?: boolean;
+
+  /** participant acts as a server side participant/bot/agent */
+  agent?: boolean;
+}
+
+/** @internal */
+export interface ClaimGrants extends JWTPayload {
+  name?: string;
+  video?: VideoGrant;
+  metadata?: string;
+  sha256?: string;
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './AccessToken.js';
+export * from './EgressClient.js';
+export * from './IngressClient.js';
+export * from './SipClient.js';
+export * from './RoomServiceClient.js';
+export * from './WebhookReceiver.js';
+export * from './grants.js';
+export {
+  AliOSSUpload,
+  AzureBlobUpload,
+  DirectFileOutput,
+  EgressInfo,
+  EncodedFileOutput,
+  EncodedFileType,
+  EncodingOptions,
+  EncodingOptionsPreset,
+  GCPUpload,
+  ImageOutput,
+  ParticipantEgressRequest,
+  RoomCompositeEgressRequest,
+  S3Upload,
+  SegmentedFileOutput,
+  SegmentedFileProtocol,
+  StreamOutput,
+  StreamProtocol,
+  TrackCompositeEgressRequest,
+  TrackEgressRequest,
+  WebEgressRequest,
+  IngressAudioEncodingOptions,
+  IngressAudioEncodingPreset,
+  IngressAudioOptions,
+  IngressInfo,
+  IngressInput,
+  IngressState,
+  IngressVideoEncodingOptions,
+  IngressVideoEncodingPreset,
+  IngressVideoOptions,
+  DataPacket_Kind,
+  ParticipantInfo,
+  ParticipantInfo_State,
+  ParticipantPermission,
+  Room,
+  TrackInfo,
+  TrackType,
+  TrackSource,
+  SIPTrunkInfo,
+  SIPDispatchRuleInfo,
+  SIPParticipantInfo,
+} from '@livekit/protocol';

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@2.0.0/schema.json",
-  "changelog": ["@livekit/changesets-changelog-github", { "repo": "livekit/server-sdk-js" }],
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

package/.eslintrc.cjs

@@ -1,17 +0,0 @@
-module.exports = {
-  extends: ['plugin:import/recommended', 'airbnb-typescript/base', 'prettier'],
-  parserOptions: {
-    project: './tsconfig.eslint.json',
-  },
-  ignorePatterns: ['src/proto', 'docs/', 'dist/', 'examples'],
-  rules: {
-    'import/export': 'off',
-    'max-classes-per-file': 'off',
-    'no-param-reassign': 'off',
-    'no-await-in-loop': 'off',
-    'consistent-return': 'off',
-    'class-methods-use-this': 'off',
-    '@typescript-eslint/no-use-before-define': 'off',
-    'no-restricted-syntax': ['error', 'WithStatement', "BinaryExpression[operator='in']"],
-  },
-};