@unboundcx/sdk-internal 2.1.0 → 2.3.0

package/index.js

@@ -9,6 +9,10 @@ import { InternalSocketService } from './services/socket.js';
 import { InternalMasterAuthService } from './services/masterAuth.js';
 import { InternalBrandingService } from './services/branding.js';
 import { InternalPhoneNumbersService } from './services/phoneNumbers.js';
+import { InternalVideoService } from './services/video.js';
+import { InternalVoicemailService } from './services/voicemail.js';
+import { InternalVoiceService } from './services/voice.js';
+import { buildObjectEventV2 } from './utils/buildObjectEventV2.js';
 
 export class InternalSDK {
   constructor(sdk, buildMasterApiAuthFn) {
@@ -24,6 +28,9 @@ export class InternalSDK {
     this.masterAuth = new InternalMasterAuthService(sdk);
     this.branding = new InternalBrandingService(sdk);
     this.phoneNumbers = new InternalPhoneNumbersService(sdk);
+    this.video = new InternalVideoService(sdk);
+    this.voicemail = new InternalVoicemailService(sdk);
+    this.voice = new InternalVoiceService(sdk);
 
     // Proxy all base SDK properties and methods
     this._proxyBaseSDK();
@@ -97,6 +104,34 @@ export class InternalSDK {
     }
     return this.sdk.token;
   }
+
+  /**
+   * Governed escape hatch for internal routes reached by path-as-data
+   * mechanisms (e.g. a voice-app webhook command that carries its target
+   * `url` at runtime), where a typed per-route method isn't possible
+   * because the caller doesn't know the route ahead of time. This is the
+   * ONLY sanctioned way to hit an internal route this way — if you know
+   * the route at write time, add (or use) a typed method on the matching
+   * service instead of calling this directly.
+   *
+   * @param {string} path - Must start with '/internal/'.
+   * @param {object} body
+   * @param {object} [options]
+   * @param {number} [options.timeoutMs]
+   */
+  async post(path, body, { timeoutMs } = {}) {
+    if (typeof path !== 'string' || !path.startsWith('/internal/')) {
+      throw new Error(
+        `InternalSDK.post: path must be a string starting with '/internal/', got: ${path}`,
+      );
+    }
+
+    const params = { body };
+    if (timeoutMs) params.timeoutMs = timeoutMs;
+
+    const result = await this.sdk._fetch(path, 'POST', params);
+    return result;
+  }
 }
 
 // Extension pattern for the main SDK
@@ -126,3 +161,7 @@ export { InternalSocketService } from './services/socket.js';
 export { InternalMasterAuthService } from './services/masterAuth.js';
 export { InternalBrandingService } from './services/branding.js';
 export { InternalPhoneNumbersService } from './services/phoneNumbers.js';
+export { InternalVideoService } from './services/video.js';
+export { InternalVoicemailService } from './services/voicemail.js';
+export { InternalVoiceService } from './services/voice.js';
+export { buildObjectEventV2 } from './utils/buildObjectEventV2.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk-internal",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Internal SDK extension for Unbound - Provides access to internal APIs and administrative functions",
   "main": "index.js",
   "type": "module",
@@ -32,6 +32,7 @@
   "files": [
     "*.js",
     "services/**/*.js",
+    "utils/**/*.js",
     "types/**/*.d.ts",
     "README.md",
     "LICENSE"
@@ -43,6 +44,9 @@
     },
     "./services/*": {
       "import": "./services/*.js"
+    },
+    "./utils/*": {
+      "import": "./utils/*.js"
     }
   },
   "scripts": {

package/services/video.js

@@ -0,0 +1,111 @@
+export class InternalVideoService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Meet PSTN bridge join (D2/D3/D10). Called by media-manager's `webhook`
+   * v2 command from the meetDialIn app once the caller has DTMF'd a
+   * meetingId + PIN. Matches
+   * app1-api/src/services/INTERNAL/video/controllers/meetJoin.js.
+   *
+   * POST /internal/video/meetJoin
+   * Body: { callId, from, variables: { meetingId, meetingPin, attempt? } }
+   */
+  async meetJoin({ callId, from, variables }) {
+    this.sdk.validateParams(
+      { callId },
+      {
+        callId: { type: 'string', required: true },
+        from: { type: 'string', required: false },
+        variables: { type: 'object', required: false },
+      },
+    );
+
+    const body = { callId };
+    if (from) body.from = from;
+    if (variables) body.variables = variables;
+
+    const params = {
+      body,
+    };
+
+    const result = await this.sdk._fetch(
+      '/internal/video/meetJoin',
+      'POST',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Meet PSTN bridge D9 (phone-hangs-up teardown). POST when a callId ==
+   * sipCallId leg observed on an active Meet participant ends. Matches
+   * app1-api/src/services/INTERNAL/video/controllers/meetCallEnded.js.
+   *
+   * POST /internal/video/meetCallEnded
+   * Body: { sipCallId, accountId }
+   */
+  async meetCallEnded({ sipCallId, accountId }) {
+    this.sdk.validateParams(
+      { sipCallId, accountId },
+      {
+        sipCallId: { type: 'string', required: true },
+        accountId: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: { sipCallId, accountId },
+    };
+
+    const result = await this.sdk._fetch(
+      '/internal/video/meetCallEnded',
+      'POST',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Meet PSTN bridge dial-out status callback. media-manager's
+   * DialEventHandler posts here (fire-and-forget) for pre-answer progress
+   * ('trying' | 'ringing' | 'answered') and terminal 'failed' outcomes on a
+   * standalone-outbound leg placed via placeOutboundCall's statusWebhook.
+   * Matches
+   * app1-api/src/services/INTERNAL/video/controllers/meetOutboundStatus.js.
+   *
+   * The api controller is intentionally tolerant of unknown/extra fields
+   * (it only requires participantId, roomId, event), so this method passes
+   * the payload through as-is rather than enumerating every static field —
+   * add a typed field here if a fixed shape solidifies.
+   *
+   * POST /internal/video/meetOutboundStatus
+   * Body: { event, callId, requestId, participantId, roomId, reason? }
+   */
+  async meetOutboundStatus(payload) {
+    this.sdk.validateParams(
+      { payload },
+      {
+        payload: { type: 'object', required: true },
+      },
+    );
+    const { event, participantId, roomId } = payload || {};
+    if (!event || !participantId || !roomId) {
+      throw new Error(
+        'meetOutboundStatus requires event, participantId, and roomId.',
+      );
+    }
+
+    const params = {
+      body: payload,
+    };
+
+    const result = await this.sdk._fetch(
+      '/internal/video/meetOutboundStatus',
+      'POST',
+      params,
+    );
+    return result;
+  }
+}

package/services/voice.js

@@ -0,0 +1,39 @@
+export class InternalVoiceService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Bulk write endpoint for the CDR discrete-event timeline (WP6.5).
+   * Emitters (sip-processor / media-manager / task-router) call this to
+   * report events; fire-and-forget semantics are the CALLER's job, not
+   * this method's. Matches
+   * app1-api/src/services/INTERNAL/voice/controllers/createCdrEvents.js.
+   *
+   * POST /internal/voice/cdrEvents
+   * Body: {
+   *   accountId,
+   *   events: [{ cdrId, sipCallId?, eventType, ts, actorType, actorId?, data? }]
+   * } -- max 50 events per request (enforced by the api).
+   */
+  async createCdrEvents({ accountId, events }) {
+    this.sdk.validateParams(
+      { accountId, events },
+      {
+        accountId: { type: 'string', required: true },
+        events: { type: 'array', required: true },
+      },
+    );
+
+    const params = {
+      body: { accountId, events },
+    };
+
+    const result = await this.sdk._fetch(
+      '/internal/voice/cdrEvents',
+      'POST',
+      params,
+    );
+    return result;
+  }
+}

package/services/voicemail.js

@@ -0,0 +1,47 @@
+export class InternalVoicemailService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * app1-transcription reports the result of a batch voicemail
+   * transcription here after POST /transcription/voicemail finishes
+   * (success or failure). Matches
+   * app1-api/src/services/INTERNAL/voicemail/controllers/transcriptionComplete.js.
+   *
+   * POST /internal/voicemail/transcription
+   * Body: { accountId, voicemailMessageId, transcription, transcriptionStatus }
+   */
+  async transcriptionComplete({
+    accountId,
+    voicemailMessageId,
+    transcription,
+    transcriptionStatus,
+  }) {
+    this.sdk.validateParams(
+      { accountId, voicemailMessageId, transcriptionStatus },
+      {
+        accountId: { type: 'string', required: true },
+        voicemailMessageId: { type: 'string', required: true },
+        transcription: { type: 'string', required: false },
+        transcriptionStatus: { type: 'string', required: true },
+      },
+    );
+
+    const params = {
+      body: {
+        accountId,
+        voicemailMessageId,
+        transcription,
+        transcriptionStatus,
+      },
+    };
+
+    const result = await this.sdk._fetch(
+      '/internal/voicemail/transcription',
+      'POST',
+      params,
+    );
+    return result;
+  }
+}

package/utils/buildObjectEventV2.js

@@ -0,0 +1,74 @@
+/**
+ * Build a spec-valid `objects.event.v2` envelope for non-api writers
+ * (task-router, cdr-user-status, ...) that mutate object-backed tables with
+ * raw SQL and need to emit live-update events without an HTTP round-trip
+ * through app1-api.
+ *
+ * Pure helper — no NATS/publish side effects. Callers publish the returned
+ * `{ subject, payload }` themselves via their own service's NATS client and
+ * subject-prefix handling.
+ *
+ * @param {Object} params
+ * @param {'create'|'update'|'delete'} params.action
+ * @param {string} params.objectName - plural object/table name, e.g. 'tasks'
+ * @param {string} params.accountId
+ * @param {string|number} params.recordTypeId
+ * @param {Object|null} [params.oldRow] - full pre-mutation row image; null for 'create'
+ * @param {Object|null} [params.newRow] - full post-mutation row image; null for 'delete'
+ * @param {number} [params.now] - ms timestamp used for rowVersion/ts; defaults to Date.now()
+ * @returns {{ subject: string, payload: Object }}
+ */
+export function buildObjectEventV2({
+  action,
+  objectName,
+  accountId,
+  recordTypeId,
+  oldRow = null,
+  newRow = null,
+  now,
+}) {
+  const changedFields =
+    oldRow && newRow ? diffChangedFields(oldRow, newRow) : [];
+
+  const ts = now ?? Date.now();
+
+  return {
+    subject: 'objects.event.v2',
+    payload: {
+      action,
+      objectName,
+      accountId,
+      recordTypeId,
+      oldRow,
+      newRow,
+      changedFields,
+      rowVersion: ts,
+      ts,
+      sourceCluster: process.env.CLUSTER_NAME || 'unknown',
+    },
+  };
+}
+
+function diffChangedFields(oldRow, newRow) {
+  const fields = new Set([...Object.keys(oldRow), ...Object.keys(newRow)]);
+  const changed = [];
+  for (const field of fields) {
+    if (!isEqualValue(oldRow[field], newRow[field])) {
+      changed.push(field);
+    }
+  }
+  return changed;
+}
+
+function isEqualValue(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null) return a === b;
+  if (typeof a === 'object' && typeof b === 'object') {
+    try {
+      return JSON.stringify(a) === JSON.stringify(b);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}