@dtelecom/server-sdk-node 0.2.6 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,15 +8,17 @@ Node.js RTC SDK for dTelecom — join rooms as a WebRTC participant for AI bots.
8
8
  - **Audio receive** — subscribe to remote audio as PCM16 streams (16kHz for STT)
9
9
  - **Audio send** — publish PCM16 audio as Opus (from TTS or any source)
10
10
  - **Data channels** — send/receive messages via reliable or lossy channels
11
- - **Pure TypeScript WebRTC** — uses [werift](https://github.com/nicejs/werift-webrtc) (no native WebRTC deps)
12
- - **Opus codec** — uses [@discordjs/opus](https://github.com/discordjs/opus) (native libopus bindings)
11
+ - **Pure TypeScript WebRTC** — uses [werift](https://github.com/shinyoshiaki/werift-webrtc) (no native WebRTC deps)
12
+ - **Opus codec** — [opusscript](https://github.com/abalabahaha/opusscript) (libopus compiled to WASM; nothing to build at install)
13
13
 
14
14
  ## Install
15
15
 
16
16
  ```bash
17
- npm install @dtelecom/server-sdk-node @discordjs/opus
17
+ npm install @dtelecom/server-sdk-node
18
18
  ```
19
19
 
20
+ Requires Node.js 22 or later. Nothing is compiled at install time.
21
+
20
22
  ## Quick Start: Echo Bot
21
23
 
22
24
  ```typescript
@@ -132,7 +134,7 @@ npx tsx examples/send-audio.ts --room test --input hello.pcm
132
134
  | Package | Purpose | Native? |
133
135
  |---|---|---|
134
136
  | `werift` | WebRTC (ICE, DTLS, SRTP) | No (pure TS) |
135
- | `@discordjs/opus` | Opus encode/decode | Yes (libopus) |
137
+ | `opusscript` | Opus encode and decode | No (WASM) |
136
138
  | `ws` | WebSocket client | No |
137
139
  | `protobufjs` | Protobuf encode/decode | No |
138
140
 
package/dist/index.d.ts CHANGED
@@ -446,6 +446,12 @@ declare class RTCEngine extends TypedEmitter<EngineEvents> {
446
446
  private joinResponse;
447
447
  private publishWaiters;
448
448
  private _negotiateResolve;
449
+ /** Negotiations run one at a time: there is one slot for the pending answer. */
450
+ private negotiateChain;
451
+ /** The publisher has an applied answer, so its data channels can open. */
452
+ private publisherNegotiated;
453
+ /** A negotiation started only to open the data channels, shared by concurrent senders. */
454
+ private dataNegotiation;
449
455
  private _publisherConnectedResolve;
450
456
  get isConnected(): boolean;
451
457
  get publisherPC(): RTCPeerConnection | null;
@@ -465,9 +471,19 @@ declare class RTCEngine extends TypedEmitter<EngineEvents> {
465
471
  disableDtx?: boolean;
466
472
  muted?: boolean;
467
473
  }): Promise<TrackPublishedResponse>;
474
+ /** Offers the publisher's current tracks and data channels; one negotiation at a time. */
468
475
  negotiate(): Promise<void>;
476
+ private runNegotiate;
469
477
  /** Wait for publisher ICE to reach connected state (DTLS+SRTP ready). */
470
478
  waitForPublisherConnected(timeoutMs?: number): Promise<void>;
479
+ /**
480
+ * Opens a publisher data channel before the first message. With subscriber-primary joins the
481
+ * publisher connection is only negotiated when something is published, so a bot that has not
482
+ * published a track negotiates it here (the offer carries the data channels). Throws when the
483
+ * channel does not open in time.
484
+ */
485
+ ensureDataChannelOpen(kind: 'reliable' | 'lossy', timeoutMs?: number): Promise<void>;
486
+ /** Sends on an open publisher data channel; throws when it is not open. */
471
487
  sendData(data: Uint8Array, kind: 'reliable' | 'lossy'): void;
472
488
  disconnect(): Promise<void>;
473
489
  private buildIceServers;
@@ -712,6 +728,8 @@ declare abstract class Participant extends TypedEmitter<ParticipantEvents> {
712
728
  name: string;
713
729
  metadata: string;
714
730
  state: ParticipantInfo_State;
731
+ /** What the participant's token allows, as the node reports it. */
732
+ permissions?: ParticipantPermission;
715
733
  protected _trackPublications: Map<string, TrackPublication>;
716
734
  constructor(sid: string, identity: string, name?: string, metadata?: string);
717
735
  get trackPublications(): Map<string, TrackPublication>;
@@ -725,6 +743,8 @@ interface DataPublishOptions {
725
743
  destinationSids?: string[];
726
744
  /** Topic for the data message */
727
745
  topic?: string;
746
+ /** How long to wait for the data channel to open on first use (default 15 s). */
747
+ timeoutMs?: number;
728
748
  }
729
749
  declare class LocalParticipant extends Participant {
730
750
  private engine;
@@ -747,8 +767,11 @@ declare class LocalParticipant extends Participant {
747
767
  /**
748
768
  * Publish data to the room.
749
769
  *
770
+ * Works before any track is published: the first call opens the data channel. Rejects when the
771
+ * participant may not publish data, or the channel does not open within `timeoutMs`.
772
+ *
750
773
  * @param data The data payload
751
- * @param options Delivery options (kind, destinations, topic)
774
+ * @param options Delivery options (kind, destinations, topic, timeoutMs)
752
775
  */
753
776
  publishData(data: Uint8Array, options?: DataPublishOptions): Promise<void>;
754
777
  }
package/dist/index.js CHANGED
@@ -1450,6 +1450,11 @@ var SignalClient = class extends TypedEmitter {
1450
1450
 
1451
1451
  // src/engine.ts
1452
1452
  var log2 = createLogger("RTCEngine");
1453
+ function parseTrickleCandidate(candidateInit) {
1454
+ const init = JSON.parse(candidateInit);
1455
+ if (init.sdpMid === "") delete init.sdpMid;
1456
+ return new import_werift.RTCIceCandidate(init);
1457
+ }
1453
1458
  var RTCEngine = class extends TypedEmitter {
1454
1459
  signal;
1455
1460
  publisher = null;
@@ -1464,6 +1469,12 @@ var RTCEngine = class extends TypedEmitter {
1464
1469
  joinResponse = null;
1465
1470
  publishWaiters = /* @__PURE__ */ new Map();
1466
1471
  _negotiateResolve = null;
1472
+ /** Negotiations run one at a time: there is one slot for the pending answer. */
1473
+ negotiateChain = Promise.resolve();
1474
+ /** The publisher has an applied answer, so its data channels can open. */
1475
+ publisherNegotiated = false;
1476
+ /** A negotiation started only to open the data channels, shared by concurrent senders. */
1477
+ dataNegotiation = null;
1467
1478
  _publisherConnectedResolve = null;
1468
1479
  get isConnected() {
1469
1480
  return this._isConnected;
@@ -1559,7 +1570,14 @@ var RTCEngine = class extends TypedEmitter {
1559
1570
  this.signal.sendAddTrack(request);
1560
1571
  });
1561
1572
  }
1562
- async negotiate() {
1573
+ /** Offers the publisher's current tracks and data channels; one negotiation at a time. */
1574
+ negotiate() {
1575
+ const run = this.negotiateChain.then(() => this.runNegotiate());
1576
+ this.negotiateChain = run.catch(() => {
1577
+ });
1578
+ return run;
1579
+ }
1580
+ async runNegotiate() {
1563
1581
  if (!this.publisher) {
1564
1582
  throw new Error("Publisher PC not initialized");
1565
1583
  }
@@ -1600,11 +1618,49 @@ var RTCEngine = class extends TypedEmitter {
1600
1618
  };
1601
1619
  });
1602
1620
  }
1621
+ /**
1622
+ * Opens a publisher data channel before the first message. With subscriber-primary joins the
1623
+ * publisher connection is only negotiated when something is published, so a bot that has not
1624
+ * published a track negotiates it here (the offer carries the data channels). Throws when the
1625
+ * channel does not open in time.
1626
+ */
1627
+ async ensureDataChannelOpen(kind, timeoutMs = 15e3) {
1628
+ const channel = kind === "reliable" ? this.reliableChannel : this.lossyChannel;
1629
+ if (!channel) throw new Error("Not connected");
1630
+ if (channel.readyState === "open") return;
1631
+ if (channel.readyState === "closing" || channel.readyState === "closed") {
1632
+ throw new Error(`Data channel ${kind} is closed`);
1633
+ }
1634
+ if (!this.publisherNegotiated) {
1635
+ if (!this.dataNegotiation) {
1636
+ log2.debug("Negotiating the publisher to open its data channels");
1637
+ this.dataNegotiation = this.negotiate().finally(() => {
1638
+ this.dataNegotiation = null;
1639
+ });
1640
+ }
1641
+ await this.dataNegotiation;
1642
+ }
1643
+ if (channel.readyState === "open") return;
1644
+ await new Promise((resolve, reject) => {
1645
+ const timer = setTimeout(() => {
1646
+ subscription.unSubscribe();
1647
+ reject(new Error(`Data channel ${kind} did not open within ${timeoutMs}ms`));
1648
+ }, timeoutMs);
1649
+ const subscription = channel.stateChanged.subscribe((state) => {
1650
+ if (state === "open" || state === "closed") {
1651
+ clearTimeout(timer);
1652
+ subscription.unSubscribe();
1653
+ if (state === "open") resolve();
1654
+ else reject(new Error(`Data channel ${kind} is closed`));
1655
+ }
1656
+ });
1657
+ });
1658
+ }
1659
+ /** Sends on an open publisher data channel; throws when it is not open. */
1603
1660
  sendData(data, kind) {
1604
1661
  const channel = kind === "reliable" ? this.reliableChannel : this.lossyChannel;
1605
1662
  if (!channel || channel.readyState !== "open") {
1606
- log2.warn(`Data channel ${kind} not open`);
1607
- return;
1663
+ throw new Error(`Data channel ${kind} not open`);
1608
1664
  }
1609
1665
  channel.send(Buffer.from(data));
1610
1666
  }
@@ -1779,6 +1835,7 @@ var RTCEngine = class extends TypedEmitter {
1779
1835
  );
1780
1836
  log2.debug("Set publisher remote description");
1781
1837
  this.flushPendingCandidates(0 /* PUBLISHER */);
1838
+ this.publisherNegotiated = true;
1782
1839
  if (this._negotiateResolve) {
1783
1840
  this._negotiateResolve();
1784
1841
  this._negotiateResolve = null;
@@ -1789,8 +1846,7 @@ var RTCEngine = class extends TypedEmitter {
1789
1846
  });
1790
1847
  this.signal.on("trickle", async (trickle) => {
1791
1848
  try {
1792
- const candidateInit = JSON.parse(trickle.candidateInit);
1793
- const candidate = new import_werift.RTCIceCandidate(candidateInit);
1849
+ const candidate = parseTrickleCandidate(trickle.candidateInit);
1794
1850
  const pc = trickle.target === 0 /* PUBLISHER */ ? this.publisher : this.subscriber;
1795
1851
  if (!pc) return;
1796
1852
  if (pc.remoteDescription) {
@@ -1893,33 +1949,12 @@ var AudioFrame = class _AudioFrame {
1893
1949
  };
1894
1950
 
1895
1951
  // src/audio/opus-encoder.ts
1952
+ var import_opusscript = __toESM(require("opusscript"));
1896
1953
  var log3 = createLogger("OpusEncoder");
1897
1954
  var OPUS_FRAME_DURATION_MS = 20;
1898
1955
  var OPUS_SAMPLE_RATE = 48e3;
1899
1956
  var OPUS_FRAME_SIZE = OPUS_SAMPLE_RATE * OPUS_FRAME_DURATION_MS / 1e3;
1900
1957
  var VALID_OPUS_RATES = [8e3, 12e3, 16e3, 24e3, 48e3];
1901
- var OpusEncoderClass = null;
1902
- var opusLibraryName = "";
1903
- function getOpusEncoder() {
1904
- if (!OpusEncoderClass) {
1905
- try {
1906
- const opus = require("@discordjs/opus");
1907
- OpusEncoderClass = opus.OpusEncoder;
1908
- opusLibraryName = "@discordjs/opus (native)";
1909
- } catch {
1910
- try {
1911
- const OpusScript = require("opusscript");
1912
- OpusEncoderClass = OpusScript;
1913
- opusLibraryName = "opusscript (WASM)";
1914
- } catch {
1915
- throw new Error(
1916
- "No Opus library found. Install @discordjs/opus (recommended) or opusscript (WASM fallback)."
1917
- );
1918
- }
1919
- }
1920
- }
1921
- return OpusEncoderClass;
1922
- }
1923
1958
  var OpusEncoder = class {
1924
1959
  encoder;
1925
1960
  channels;
@@ -1937,22 +1972,16 @@ var OpusEncoder = class {
1937
1972
  }
1938
1973
  this.channels = channels;
1939
1974
  this.frameSize = sampleRate * OPUS_FRAME_DURATION_MS / 1e3;
1940
- const Encoder = getOpusEncoder();
1941
- this.encoder = new Encoder(sampleRate, channels);
1942
- if (typeof this.encoder.setBitrate === "function") {
1943
- this.encoder.setBitrate(bitrate);
1944
- }
1945
- if (typeof this.encoder.applyEncoderCTL === "function") {
1946
- try {
1947
- this.encoder.applyEncoderCTL(4016, 1);
1948
- log3.info(`Opus encoder: ${opusLibraryName}, ${sampleRate}Hz, ${channels}ch, ${bitrate / 1e3}kbps, frameSize=${this.frameSize}, DTX=on`);
1949
- } catch (err) {
1950
- log3.warn("Failed to enable DTX:", err);
1951
- log3.info(`Opus encoder: ${opusLibraryName}, ${sampleRate}Hz, ${channels}ch, ${bitrate / 1e3}kbps, frameSize=${this.frameSize}`);
1952
- }
1953
- } else {
1954
- log3.info(`Opus encoder: ${opusLibraryName}, ${sampleRate}Hz, ${channels}ch, ${bitrate / 1e3}kbps, frameSize=${this.frameSize}`);
1975
+ this.encoder = new import_opusscript.default(sampleRate, channels, import_opusscript.default.Application.AUDIO);
1976
+ this.encoder.setBitrate(bitrate);
1977
+ let dtx = false;
1978
+ try {
1979
+ this.encoder.encoderCTL(4016, 1);
1980
+ dtx = true;
1981
+ } catch (err) {
1982
+ log3.warn("Failed to enable DTX:", err);
1955
1983
  }
1984
+ log3.info(`Opus encoder: opusscript, ${sampleRate}Hz, ${channels}ch, ${bitrate / 1e3}kbps, frameSize=${this.frameSize}${dtx ? ", DTX=on" : ""}`);
1956
1985
  }
1957
1986
  /**
1958
1987
  * Encode a PCM16 frame to Opus.
@@ -1961,13 +1990,12 @@ var OpusEncoder = class {
1961
1990
  */
1962
1991
  encode(pcm) {
1963
1992
  const buf = pcm instanceof Int16Array ? Buffer.from(pcm.buffer, pcm.byteOffset, pcm.byteLength) : pcm;
1993
+ if (!this.encoder) throw new Error("Opus encoder destroyed");
1964
1994
  return this.encoder.encode(buf, this.frameSize);
1965
1995
  }
1966
- /** Clean up native resources */
1996
+ /** Free the WASM encoder. */
1967
1997
  destroy() {
1968
- if (this.encoder && typeof this.encoder.delete === "function") {
1969
- this.encoder.delete();
1970
- }
1998
+ this.encoder?.delete();
1971
1999
  this.encoder = null;
1972
2000
  }
1973
2001
  };
@@ -2534,6 +2562,8 @@ var Participant = class extends TypedEmitter {
2534
2562
  name;
2535
2563
  metadata;
2536
2564
  state;
2565
+ /** What the participant's token allows, as the node reports it. */
2566
+ permissions;
2537
2567
  _trackPublications = /* @__PURE__ */ new Map();
2538
2568
  constructor(sid, identity, name = "", metadata = "") {
2539
2569
  super();
@@ -2554,6 +2584,7 @@ var Participant = class extends TypedEmitter {
2554
2584
  this.name = info.name;
2555
2585
  this.metadata = info.metadata;
2556
2586
  this.state = info.state;
2587
+ if (info.permission) this.permissions = info.permission;
2557
2588
  if (metadataChanged) {
2558
2589
  this.emit("metadataChanged", info.metadata);
2559
2590
  }
@@ -2629,10 +2660,16 @@ var LocalParticipant = class extends Participant {
2629
2660
  /**
2630
2661
  * Publish data to the room.
2631
2662
  *
2663
+ * Works before any track is published: the first call opens the data channel. Rejects when the
2664
+ * participant may not publish data, or the channel does not open within `timeoutMs`.
2665
+ *
2632
2666
  * @param data The data payload
2633
- * @param options Delivery options (kind, destinations, topic)
2667
+ * @param options Delivery options (kind, destinations, topic, timeoutMs)
2634
2668
  */
2635
2669
  async publishData(data, options = {}) {
2670
+ if (this.permissions && !this.permissions.canPublishData) {
2671
+ throw new Error("Participant lacks canPublishData");
2672
+ }
2636
2673
  const kind = options.kind ?? 0 /* RELIABLE */;
2637
2674
  const destinationSids = options.destinationSids ?? [];
2638
2675
  const topic = options.topic;
@@ -2647,6 +2684,7 @@ var LocalParticipant = class extends Participant {
2647
2684
  };
2648
2685
  const encoded = DataPacket.encode(packet).finish();
2649
2686
  const channelKind = kind === 0 /* RELIABLE */ ? "reliable" : "lossy";
2687
+ await this.engine.ensureDataChannelOpen(channelKind, options.timeoutMs);
2650
2688
  this.engine.sendData(new Uint8Array(encoded), channelKind);
2651
2689
  }
2652
2690
  };
@@ -2861,6 +2899,7 @@ var Room = class extends TypedEmitter {
2861
2899
  join.participant.name,
2862
2900
  join.participant.metadata
2863
2901
  );
2902
+ this.localParticipant.permissions = join.participant.permission;
2864
2903
  }
2865
2904
  for (const info of join.otherParticipants) {
2866
2905
  this.getOrCreateParticipant(info);