@signalhousellc/sdk 1.0.56 → 1.0.62

package/src/domains/Voice.js

@@ -1,6 +1,9 @@
 import { SipTrunks } from "./voice/SipTrunks.js";
 import { SipProfiles } from "./voice/SipProfiles.js";
+import { ProgrammableVoiceProfiles } from "./voice/ProgrammableVoiceProfiles.js";
 import { Calls } from "./voice/Calls.js";
+import { CallLogs } from "./voice/CallLogs.js";
+import { GlobalVoiceSettings } from "./voice/GlobalVoiceSettings.js";
 import { Tokens } from "./voice/Tokens.js";
 
 /**
@@ -9,10 +12,13 @@ import { Tokens } from "./voice/Tokens.js";
  * namespace, accessed via `sdk.voice.*`.
  *
  * Sub-resources:
- * - `sdk.voice.sipTrunks`   — SIP trunk (peer-to-peer connections to PBX/carrier).
- * - `sdk.voice.sipProfiles` — SIP profile / endpoint (single registerable UA).
- * - `sdk.voice.calls`       — Outbound call origination + call log queries.
- * - `sdk.voice.tokens`      — Mint ephemeral SIP credentials for the browser voice SDK.
+ * - `sdk.voice.sipTrunks`                 — SIP trunk (peer-to-peer connections to PBX/carrier).
+ * - `sdk.voice.sipProfiles`               — SIP profile / endpoint (single registerable UA).
+ * - `sdk.voice.programmableVoiceProfiles` — Programmable Voice Profile (route a set of numbers through Signal House).
+ * - `sdk.voice.calls`                     — Twilio-compat programmatic call control (create/hangup/etc.).
+ * - `sdk.voice.callLogs`                  — Account-scoped call history: list/get + presigned recording.
+ * - `sdk.voice.globalVoiceSettings`       — Account-wide voice defaults (accepted regions, max spend, E911).
+ * - `sdk.voice.tokens`                    — Mint ephemeral SIP credentials for the browser voice SDK.
  */
 export class Voice {
 	constructor(client, enableAdmin) {
@@ -20,7 +26,10 @@ export class Voice {
 		this.enableAdmin = enableAdmin;
 		this.sipTrunks = new SipTrunks(client, enableAdmin);
 		this.sipProfiles = new SipProfiles(client, enableAdmin);
+		this.programmableVoiceProfiles = new ProgrammableVoiceProfiles(client, enableAdmin);
 		this.calls = new Calls(client, enableAdmin);
+		this.callLogs = new CallLogs(client, enableAdmin);
+		this.globalVoiceSettings = new GlobalVoiceSettings(client, enableAdmin);
 		this.tokens = new Tokens(client, enableAdmin);
 	}
 }

package/src/domains/voice/CallLogs.js

@@ -0,0 +1,105 @@
+/**
+ * @typedef {Object} ListCallLogsFilters
+ * @property {number} [page] - 1-indexed page (default 1).
+ * @property {number} [limit] - Page size (default 20, max 1000).
+ * @property {"INBOUND"|"OUTBOUND"|"INTERNAL"} [direction] - Filter by direction.
+ * @property {"QUEUED"|"RINGING"|"IN_PROGRESS"|"COMPLETED"|"FAILED"|"BUSY"|"NO_ANSWER"|"CANCELED"} [status] - Filter by status.
+ * @property {"SIP_TRUNK"|"PROGRAMMABLE_VOICE"|"AI_VOICE"|"WEBRTC"|"VOICEMAIL"|"CONFERENCE"|"PSTN"} [callSource] - Filter by how the call was handled.
+ * @property {string} [subgroupId] - Filter by owning subgroup.
+ * @property {string} [sipTrunkId] - Filter by SIP trunk id.
+ * @property {string} [programmableVoiceProfileId] - Filter by Programmable Voice Profile id.
+ * @property {string} [from] - Filter by caller number (contains).
+ * @property {string} [to] - Filter by called number (contains).
+ * @property {string} [q] - Free-text search over callId / from / to.
+ * @property {"positive"|"negative"|"neutral"} [sentiment] - Filter by sentiment.
+ * @property {boolean} [voicemail] - When true, return only voicemails (metadata.voicemail=true).
+ * @property {boolean} [hasRecording] - When true, only calls that have a recording (callRecordingUrl set).
+ * @property {boolean} [excludeVoicemail] - When true, exclude voicemails (used by the Call Recordings view).
+ * @property {string} [dateFrom] - ISO-8601 lower bound on start time.
+ * @property {string} [dateTo] - ISO-8601 upper bound on start time.
+ * @property {string} [sort] - Sort field (default startTime).
+ * @property {"asc"|"desc"} [order] - Sort order (default desc).
+ */
+
+/**
+ * Call Logs — the account-scoped voice call history (voice-backend
+ * `/voice/api/v1/call-logs`). Distinct from `voice.calls`, which is the
+ * Twilio-compatible programmatic call-control surface; this is the richer log
+ * read surface with cost, recording, and voice-config attribution used by the
+ * portal Call Logs view. Accessed via `sdk.voice.callLogs`.
+ */
+export class CallLogs {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * List call logs for the current account, paginated and filterable.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} [params] - Request parameters.
+	 * @param {ListCallLogsFilters} [params.filters] - Optional filters.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<Object>} `{ success, data: [...call logs], meta: { total, page, limit, totalPages } }`.
+	 */
+	async list({ filters = {}, options = {} } = {}) {
+		const query = new URLSearchParams();
+		for (const [k, v] of Object.entries(filters)) {
+			if (v !== undefined && v !== null && v !== "") query.set(k, String(v));
+		}
+		const qs = query.toString();
+		const path = qs ? `/voice/api/v1/call-logs?${qs}` : `/voice/api/v1/call-logs`;
+		return this.client(path, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single call log by its UUID or callId.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The call log UUID or callId.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ success, data: { ...call log } }`.
+	 */
+	async get({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/api/v1/call-logs/${safeId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a short-TTL presigned playback URL for a call's recording. Account-scoped
+	 * — only the owning account can presign. 404 if the call has no recording.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The call log UUID or callId.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ success, data: { callId, url, expiresIn } }`.
+	 */
+	async getRecording({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/api/v1/call-logs/${safeId}/recording`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Mark a voicemail (a call log with a recording) read or unread. Account-scoped.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The call log UUID or callId.
+	 * @param {boolean} [params.read=true] - true = read, false = unread.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ success, data: { id, voicemailReadAt } }`.
+	 */
+	async markVoicemailRead({ id, read = true, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/api/v1/call-logs/${safeId}/voicemail-read`, { method: "PATCH", body: { read }, ...options });
+	}
+}

package/src/domains/voice/GlobalVoiceSettings.js

@@ -0,0 +1,48 @@
+/**
+ * @typedef {Object} GlobalVoiceSettingsData
+ * @property {string[]} [acceptedRegions] - Accepted regions as country calling codes; empty = all allowed.
+ * @property {number|null} [maxSpendPerMinute] - Baseline max spend per minute (dollars); null = no limit.
+ * @property {boolean} [e911Enabled] - Whether numbers may dial 911.
+ */
+
+/**
+ * Global Voice Settings — account-wide voice defaults (accepted regions, max
+ * spend per minute, E911). SIP trunks and Programmable Voice Profiles override
+ * these. Calls the voice-backend service mounted under /voice. Accessed via
+ * `sdk.voice.globalVoiceSettings`.
+ */
+export class GlobalVoiceSettings {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * Get the current account's global voice settings. Returns `data: null` if the
+	 * account has never configured them (defaults apply).
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} [params] - Request parameters.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<Object>} `{ success, data: { accountId, acceptedRegions, maxSpendPerMinute, e911Enabled, ... } | null }`.
+	 */
+	async get({ options = {} } = {}) {
+		return this.client(`/voice/api/v1/global-voice-settings`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Upsert the account's global voice settings. Partial — only the fields you
+	 * provide are written; omitted fields are preserved.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {GlobalVoiceSettingsData} params.settingsData - Fields to set.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If settingsData is missing.
+	 * @returns {Promise<Object>} `{ success, data: { ...settings } }`.
+	 */
+	async update({ settingsData, options = {} }) {
+		this.client._require({ settingsData });
+		return this.client(`/voice/api/v1/global-voice-settings`, { method: "PUT", body: settingsData, ...options });
+	}
+}

package/src/domains/voice/ProgrammableVoiceProfiles.js

@@ -0,0 +1,181 @@
+/**
+ * @typedef {Object} CreateProgrammableVoiceProfileData
+ * @property {string} name - Profile name (required).
+ * @property {string[]} subgroupIds - Subgroups this profile spans (required, at least one).
+ * @property {string} [region] - Region/POP label.
+ * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"} [routeAction] - Inbound call action (default "FORWARD"). Deliver the call to a PSTN number (FORWARD), ring the profile's subgroup registered softphones (WEBRTC), send to a SIP trunk (SIP_TRUNK), or ring a registered SIP endpoint (SIP_PROFILE).
+ * @property {string} [forwardToE164] - Destination number, required when routeAction is "FORWARD".
+ * @property {number} [forwardAfterSeconds] - Ring seconds before the action fires.
+ * @property {string} [routeSipTrunkId] - SIP trunk id, required when routeAction is "SIP_TRUNK".
+ * @property {string} [routeSipProfileId] - SIP endpoint id, required when routeAction is "SIP_PROFILE".
+ * @property {boolean} [recordingEnabled] - Record calls on this profile.
+ * @property {boolean} [enabled] - Active state (default true).
+ */
+
+/**
+ * @typedef {Object} UpdateProgrammableVoiceProfileData
+ * @property {string} [name] - Profile name.
+ * @property {string[]} [subgroupIds] - Subgroups this profile spans.
+ * @property {string|null} [region] - Region/POP label.
+ * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"} [routeAction] - Inbound call action (FORWARD | WEBRTC | SIP_TRUNK | SIP_PROFILE).
+ * @property {string|null} [forwardToE164] - FORWARD destination.
+ * @property {number|null} [forwardAfterSeconds] - Ring seconds before the action fires.
+ * @property {string|null} [routeSipTrunkId] - SIP trunk id (required when routeAction is "SIP_TRUNK").
+ * @property {string|null} [routeSipProfileId] - SIP endpoint id (required when routeAction is "SIP_PROFILE").
+ * @property {boolean} [recordingEnabled] - Record calls on this profile.
+ * @property {boolean} [enabled] - Active state.
+ */
+
+/**
+ * Programmable Voice Profile management. A Programmable Voice Profile groups a
+ * set of the account's numbers (across one or more subgroups) under a single
+ * inbound call-handling decision routed through Signal House's own voice servers
+ * — the same idea as a SIP trunk, but without a customer SBC. A number can
+ * belong to at most one profile and is mutually exclusive with SIP trunks.
+ *
+ * Calls the voice-backend service mounted under /voice. Accessed via
+ * `sdk.voice.programmableVoiceProfiles`.
+ */
+export class ProgrammableVoiceProfiles {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * List all Programmable Voice Profiles for the current account.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} [params] - Request parameters.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<Object>} `{ profiles: [...] }`.
+	 */
+	async list({ options = {} } = {}) {
+		return this.client(`/voice/api/v1/programmable-voice-profiles`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single Programmable Voice Profile by ID.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The profile UUID.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 */
+	async get({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/api/v1/programmable-voice-profiles/${safeId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create a Programmable Voice Profile.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {CreateProgrammableVoiceProfileData} params.profileData - The profile to create.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If profileData is missing.
+	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 */
+	async create({ profileData, options = {} }) {
+		this.client._require({ profileData });
+		return this.client(`/voice/api/v1/programmable-voice-profiles`, { method: "POST", body: profileData, ...options });
+	}
+
+	/**
+	 * Update an existing Programmable Voice Profile (partial).
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The profile UUID.
+	 * @param {UpdateProgrammableVoiceProfileData} params.updateData - Fields to update.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or updateData is missing.
+	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 */
+	async update({ id, updateData, options = {} }) {
+		this.client._require({ id, updateData });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/api/v1/programmable-voice-profiles/${safeId}`, { method: "PATCH", body: updateData, ...options });
+	}
+
+	/**
+	 * Toggle a profile active/inactive.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The profile UUID.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 */
+	async toggleActive({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/api/v1/programmable-voice-profiles/${safeId}/toggle-active`, { method: "POST", ...options });
+	}
+
+	/**
+	 * Delete a Programmable Voice Profile. Its number assignments cascade away,
+	 * so those numbers fall back to subgroup/global routing.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The profile UUID.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ message: string }`.
+	 */
+	async delete({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/api/v1/programmable-voice-profiles/${safeId}`, { method: "DELETE", ...options });
+	}
+
+	/**
+	 * Assign a phone number (by E.164) to this profile. Rejected if the number is
+	 * already configured on a SIP trunk/endpoint or another profile — it must be
+	 * de-configured there first (mutual exclusivity).
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The profile UUID.
+	 * @param {string} params.e164 - The phone number in E.164 (a leading "+" is optional).
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or e164 is missing.
+	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 */
+	async assignNumber({ id, e164, options = {} }) {
+		this.client._require({ id, e164 });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/api/v1/programmable-voice-profiles/${safeId}/assign-number`, {
+			method: "POST",
+			body: { e164 },
+			...options,
+		});
+	}
+
+	/**
+	 * Unassign a phone number (by E.164) from this profile.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The profile UUID.
+	 * @param {string} params.e164 - The phone number in E.164 (a leading "+" is optional).
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or e164 is missing.
+	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 */
+	async unassignNumber({ id, e164, options = {} }) {
+		this.client._require({ id, e164 });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/api/v1/programmable-voice-profiles/${safeId}/unassign-number`, {
+			method: "POST",
+			body: { e164 },
+			...options,
+		});
+	}
+}

package/src/domains/voice/SipTrunks.js

@@ -157,4 +157,41 @@ export class SipTrunks {
 	async getPops({ options = {} } = {}) {
 		return this.client(`/voice/sip-trunks/pops`, { method: "GET", ...options });
 	}
+
+	/**
+	 * Attach one or more phone numbers (by E.164) to a SIP trunk — routes each
+	 * DID down the trunk. Idempotent; numbers already configured on a SIP profile
+	 * are skipped and returned in `skipped` with a reason.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP trunk UUID.
+	 * @param {string[]} params.phoneNumbers - Phone numbers in E.164 (a leading "+" is optional).
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or phoneNumbers is missing.
+	 * @returns {Promise<Object>} `{ assigned: string[], skipped: { e164, reason }[] }`.
+	 */
+	async assignNumbers({ id, phoneNumbers, options = {} }) {
+		this.client._require({ id, phoneNumbers });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-trunks/${safeId}/assign-numbers`, { method: "POST", body: { phoneNumbers }, ...options });
+	}
+
+	/**
+	 * Detach one or more phone numbers (by E.164) from a SIP trunk — removes each
+	 * number's SIP_TRUNK inbound route when it points at this trunk.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP trunk UUID.
+	 * @param {string[]} params.phoneNumbers - Phone numbers in E.164 (a leading "+" is optional).
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or phoneNumbers is missing.
+	 * @returns {Promise<Object>} `{ unassigned: string[] }`.
+	 */
+	async unassignNumbers({ id, phoneNumbers, options = {} }) {
+		this.client._require({ id, phoneNumbers });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-trunks/${safeId}/unassign-numbers`, { method: "POST", body: { phoneNumbers }, ...options });
+	}
 }