@signalhousellc/sdk 1.5.1 → 1.6.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.
Files changed (54) hide show
  1. package/README.md +5 -56
  2. package/index.d.ts +1 -0
  3. package/index.js +2 -0
  4. package/package.json +32 -34
  5. package/voice-browser.d.ts +1 -0
  6. package/voice-browser.js +2 -0
  7. package/warn.js +7 -0
  8. package/webhooks.d.ts +1 -0
  9. package/webhooks.js +2 -0
  10. package/scripts/install-skills.mjs +0 -329
  11. package/skills/VENDORED.json +0 -22
  12. package/skills/signalhouse-10dlc/SKILL.md +0 -172
  13. package/skills/signalhouse-10dlc/examples/brightsmile-onboarding.md +0 -62
  14. package/skills/signalhouse-10dlc/references/tcr-rejection-causes.md +0 -104
  15. package/skills/signalhouse-advisor/SKILL.md +0 -84
  16. package/skills/signalhouse-numbers/SKILL.md +0 -82
  17. package/skills/signalhouse-setup/SKILL.md +0 -121
  18. package/skills/signalhouse-sms/SKILL.md +0 -81
  19. package/skills/signalhouse-webhooks/SKILL.md +0 -148
  20. package/src/SignalHouseSDK.js +0 -201
  21. package/src/domains/Agents.js +0 -987
  22. package/src/domains/Auth.js +0 -225
  23. package/src/domains/Billing.js +0 -265
  24. package/src/domains/Brands.js +0 -566
  25. package/src/domains/Campaigns.js +0 -691
  26. package/src/domains/Dnc.js +0 -168
  27. package/src/domains/Groups.js +0 -187
  28. package/src/domains/Landings.js +0 -237
  29. package/src/domains/Messages.js +0 -609
  30. package/src/domains/Notifications.js +0 -62
  31. package/src/domains/Numbers.js +0 -574
  32. package/src/domains/Onboarding.js +0 -128
  33. package/src/domains/Registrations.js +0 -246
  34. package/src/domains/Shortlinks.js +0 -80
  35. package/src/domains/Subgroups.js +0 -136
  36. package/src/domains/Subscriptions.js +0 -164
  37. package/src/domains/Templates.js +0 -403
  38. package/src/domains/Tickets.js +0 -100
  39. package/src/domains/Users.js +0 -228
  40. package/src/domains/Voice.js +0 -41
  41. package/src/domains/Webhooks.js +0 -125
  42. package/src/domains/voice/Analytics.js +0 -82
  43. package/src/domains/voice/CallLogs.js +0 -111
  44. package/src/domains/voice/Calls.js +0 -118
  45. package/src/domains/voice/GlobalVoiceSettings.js +0 -54
  46. package/src/domains/voice/NumberRoutes.js +0 -82
  47. package/src/domains/voice/ProgrammableVoiceProfiles.js +0 -191
  48. package/src/domains/voice/SipProfiles.js +0 -203
  49. package/src/domains/voice/SipTrunks.js +0 -203
  50. package/src/domains/voice/Tokens.js +0 -96
  51. package/src/domains/voice/browser/Call.js +0 -366
  52. package/src/domains/voice/browser/Device.js +0 -484
  53. package/src/domains/voice/browser/index.js +0 -17
  54. package/src/webhooks/verifySignature.js +0 -66
@@ -1,62 +0,0 @@
1
- /** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
2
- /**
3
- * @template T
4
- * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
5
- */
6
-
7
- export class Notifications {
8
- constructor(client, enableAdmin) {
9
- this.client = client;
10
- this.enableAdmin = enableAdmin;
11
- }
12
-
13
- /**
14
- * Get notifications by id or by groupId with optional filters
15
- * @async
16
- * @roles signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, billing, user
17
- * @param {Object} params
18
- * @param {string} [params.id] - Notification id (one of id/groupId required)
19
- * @param {string} [params.groupId] - Group id to fetch notifications for (one of id/groupId required)
20
- * @param {number} [params.page] - Page number (min 1, default 1)
21
- * @param {number} [params.limit] - Results per page (min 1, max 100, default 10)
22
- * @param {string} [params.status] - Filter by status: "READ" or "UNREAD"
23
- * @param {string|string[]} [params.eventTypes] - Event types to filter by (comma-separated string or array)
24
- * @param {RequestOptions} [params.options] - Additional options for the request
25
- * @returns {Promise<SdkResponse<any>>} The response from the server
26
- */
27
- async getNotifications({ id, groupId, page, limit, status, eventTypes, options = {} }) {
28
- this.client._require({ "id or groupId": id ?? groupId });
29
- const queryString = this.client._getQueryString({ id, groupId, page, limit, status, eventTypes });
30
- return this.client(`/notification${queryString}`, { method: "GET", ...options });
31
- }
32
-
33
- /**
34
- * Update the status of one or more notifications
35
- * @async
36
- * @roles signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, billing, user
37
- * @param {Object} params
38
- * @param {string|string[]} params.ids - Notification id or array of notification ids
39
- * @param {string} params.status - New status: "READ" or "UNREAD"
40
- * @param {RequestOptions} [params.options] - Additional options for the request
41
- * @returns {Promise<SdkResponse<any>>} The response from the server
42
- */
43
- async updateNotificationStatus({ ids, status, options = {} }) {
44
- this.client._require({ ids, status });
45
- return this.client(`/notification/status`, { method: "PUT", body: { ids, status }, ...options });
46
- }
47
-
48
- /**
49
- * Delete a notification by id
50
- * @async
51
- * @roles signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, billing, user
52
- * @param {Object} params
53
- * @param {string} params.id - The notification id to delete
54
- * @param {RequestOptions} [params.options] - Additional options for the request
55
- * @returns {Promise<SdkResponse<any>>} The response from the server
56
- */
57
- async deleteNotification({ id, options = {} }) {
58
- this.client._require({ id });
59
- const safeId = encodeURIComponent(id);
60
- return this.client(`/notification/${safeId}`, { method: "DELETE", ...options });
61
- }
62
- }
@@ -1,574 +0,0 @@
1
- /** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
2
- /**
3
- * @template T
4
- * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
5
- */
6
-
7
- export class Numbers {
8
- constructor(client, multipartClient, enableAdmin) {
9
- this.client = client;
10
- this.multipartClient = multipartClient;
11
- this.enableAdmin = enableAdmin;
12
-
13
- if (enableAdmin) {
14
- this.admin = {
15
- /**
16
- * Update a port-in request's status (signalhouse only). Infobip exposes no porting-status
17
- * API or webhook, so ON_HOLD and its reason are always staff-entered here.
18
- * @async
19
- * @roles signalhouse
20
- * @param {Object} params - The parameters for updating the status
21
- * @param {string} params.portingId - The _id of the port-in request
22
- * @param {string} params.status - The new status (PENDING, IN_PROGRESS, ON_HOLD, REJECTED)
23
- * @param {string} [params.description] - Optional description for the status change
24
- * @param {string} [params.onHoldReason] - Required when status is ON_HOLD (DOCUMENTATION_MISMATCH, ACCOUNT_INFO_INCORRECT, CARRIER_REJECTED, PENDING_CUSTOMER_ACTION, OTHER)
25
- * @param {RequestOptions} [params.options] - Additional options for the request
26
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated port-in request
27
- */
28
- changePortingStatus: async ({ portingId, status, description, onHoldReason, options = {} }) => {
29
- this.client._require({ portingId, status });
30
- const safeId = encodeURIComponent(portingId);
31
- return this.client(`/number/portin/${safeId}/status`, {
32
- method: 'PUT',
33
- body: { status, description, onHoldReason },
34
- ...options,
35
- });
36
- },
37
-
38
- /**
39
- * Approve a port-in request, setting its status to SUCCESS (signalhouse only)
40
- * @async
41
- * @roles signalhouse
42
- * @param {Object} params - The parameters for approving the request
43
- * @param {string} params.portingId - The _id of the port-in request
44
- * @param {RequestOptions} [params.options] - Additional options for the request
45
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated port-in request
46
- */
47
- approvePortRequest: async ({ portingId, options = {} }) => {
48
- this.client._require({ portingId });
49
- const safeId = encodeURIComponent(portingId);
50
- return this.client(`/number/portin/${safeId}/approve`, {
51
- method: 'POST',
52
- ...options,
53
- });
54
- },
55
- /**
56
- * List campaign-bound Short Code acquisition requests for staff.
57
- * @async
58
- * @roles signalhouse
59
- * @param {Object} [params] - Queue filter parameters.
60
- * @param {string} [params.status] - PENDING, FULFILLED, or CANCELLED.
61
- * @param {string} [params.search] - Request or associated identifier search.
62
- * @param {number} [params.page] - One-based page number.
63
- * @param {number} [params.limit] - Page size.
64
- * @param {RequestOptions} [params.options] - Additional options.
65
- * @returns {Promise<SdkResponse<any>>} Paginated acquisition requests.
66
- */
67
- getShortCodeAcquisitionRequests: async ({ status, search, page, limit, options = {} } = {}) => {
68
- const queryString = this.client._getQueryString({ status, search, page, limit });
69
- return this.client(`/number/short-code/requests${queryString}`, { method: 'GET', ...options });
70
- },
71
- };
72
- }
73
- }
74
-
75
- /**
76
- * Get a list of phone numbers with optional filters such as campaignId, brandId, subgroupId, groupId, and pagination parameters
77
- * @async
78
- * @roles api, admin, developer, billing, user
79
- * @param {Object} params - The parameters for filtering the phone numbers
80
- * @param {string} [params.phoneNumber] - Filter by phone number (partial match)
81
- * @param {string} [params.campaignId] - Filter by campaign ID
82
- * @param {string} [params.registrationId] - Filter to numbers provisioned under this registration.
83
- * @param {string} [params.brandId] - Filter by brand ID
84
- * @param {string} [params.subgroupId] - Filter by subgroup ID
85
- * @param {string} [params.groupId] - Filter by group ID
86
- * @param {boolean} [params.currentTollFreeCarrier] - With subgroupId or groupId: when true, return only toll-free numbers that a new toll-free campaign in that group can use (those on the group's current toll-free carrier)
87
- * @param {number} [params.page] - The page number for pagination (default: 1)
88
- * @param {number} [params.limit] - The number of items per page for pagination (default: 20)
89
- * @param {RequestOptions} [params.options] - Additional options for the request
90
- *
91
- * Every record carries a `sentiment` object -- trailing 7-day and 30-day inbound reply sentiment,
92
- * refreshed periodically from analytics rather than computed per request: `{ sevenDay, thirtyDay,
93
- * updatedAt }`, each window being `{ score, label, scoredCount, positive, neutral, negative }`. The
94
- * object is always present and fully populated, so it can be read without a presence check.
95
- * `score` is a volume-weighted average in -100..100 and is null when nothing was scored in the
96
- * window, which is not the same as a score of 0 -- null means nobody replied, 0 means replies
97
- * averaged neutral. `updatedAt` is null until the first rollup writes the record, and it tracks when
98
- * the figures last CHANGED, not when the job last ran.
99
- *
100
- * Every record also carries a `health` object -- trailing 7-day and 30-day delivery/opt-out health from
101
- * the same periodic refresh: `{ sevenDay, thirtyDay, updatedAt }`, each window being `{ score,
102
- * deliveryRate, optOutRate, deliveryScore, optOutScore, messagesSent, messagesDelivered, messagesFailed,
103
- * optOuts }`. `score` is 1.0..10.0 (the mean of the two bucket scores) and is null when nothing was sent
104
- * in the window; the volumes say how much traffic sits behind it. A campaign's figure is scored from the
105
- * campaign's own summed counters, never averaged from its numbers. For a live figure use GET /number/health
106
- * or GET /campaign/health.
107
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the list of phone numbers
108
- */
109
- async getPhoneNumbers({ phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, currentTollFreeCarrier, page, limit, options = {} }) {
110
- const filters = { phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, currentTollFreeCarrier, page, limit };
111
- const queryString = this.client._getQueryString(filters);
112
- return this.client(`/number${queryString}`, { method: 'GET', ...options });
113
- }
114
-
115
- /**
116
- * Get the portal-parity health score (1–10) for an owned phone number over 7-day and 30-day windows
117
- * @async
118
- * @roles api, admin, developer, billing, user
119
- * @param {Object} params - The parameters for reading number health
120
- * @param {string} params.phoneNumber - Owned phone number to score (11 digits, no + prefix)
121
- * @param {RequestOptions} [params.options] - Additional options for the request
122
- * @throws {Error} Throws an error if the phoneNumber parameter is missing
123
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, groupId, sevenDay, thirtyDay }`
124
- */
125
- async getNumberHealth({ phoneNumber, options = {} }) {
126
- this.client._require({ phoneNumber });
127
- const queryString = this.client._getQueryString({ phoneNumber });
128
- return this.client(`/number/health${queryString}`, { method: 'GET', ...options });
129
- }
130
-
131
- /**
132
- * Get a list of available phone numbers for purchase with optional filters
133
- * @async
134
- * @roles api, admin, developer, billing, user
135
- * @param {Object} params - The parameters for filtering the available phone numbers
136
- * @param {boolean} [params.smsEnabled] - Filter for phone numbers that are SMS enabled
137
- * @param {boolean} [params.mmsEnabled] - Filter for phone numbers that are MMS enabled
138
- * @param {boolean} [params.voiceEnabled] - Filter for phone numbers that are voice enabled
139
- * @param {string} [params.country] - Filter by country code (e.g., "US")
140
- * @param {string} [params.state] - Filter by state code (e.g., "CA")
141
- * @param {string} [params.city] - City prefix; requires country US and state.
142
- * @param {string} [params.npa] - Filter by NPA (area code)
143
- * @param {string} [params.nxx] - Filter by NXX (central office code) - the first three digits of the local phone number after the area code
144
- * @param {string} [params.phoneNumber] - Filter by phone number
145
- * @param {number} [params.limit] - The number of items per page for pagination
146
- * @param {number} [params.page] - The page number for pagination
147
- * @param {RequestOptions} [params.options] - Additional options for the request
148
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the list of available phone numbers
149
- */
150
- async getAvailablePhoneNumbers({
151
- smsEnabled,
152
- mmsEnabled,
153
- voiceEnabled,
154
- country,
155
- state,
156
- city,
157
- npa,
158
- nxx,
159
- phoneNumber,
160
- limit,
161
- page,
162
- options = {},
163
- }) {
164
- const filters = { smsEnabled, mmsEnabled, voiceEnabled, country, state, city, npa, nxx, phoneNumber, limit, page };
165
- const queryString = this.client._getQueryString(filters);
166
- return this.client(`/number/available${queryString}`, { method: 'GET', ...options });
167
- }
168
-
169
- /**
170
- * Purchase phone numbers by providing a list of phone numbers and the subgroup ID to assign them to.
171
- *
172
- * Each requested number is queued and processed independently. Per-number success or failure is
173
- * delivered via `NUMBER_PURCHASE_SUCCESSFUL` / `NUMBER_PURCHASE_FAILED` webhooks — not in this response.
174
- * @async
175
- * @roles api, admin, developer, billing, user
176
- * @param {Object} params - The parameters for purchasing phone numbers
177
- * @param {string[]} params.phoneNumbers - The list of phone numbers to purchase
178
- * @param {string} params.subgroupId - The ID of the subgroup to assign the purchased phone numbers to
179
- * @param {string} [params.country='US'] - ISO-2 purchase country; US.
180
- * @param {RequestOptions} [params.options] - Additional options for the request
181
- * @throws {Error} Throws an error if the phoneNumbers or subgroupId parameter is missing
182
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ message }` once the request is queued.
183
- */
184
- async purchasePhoneNumber({ phoneNumbers, subgroupId, country = 'US', options = {} }) {
185
- this.client._require({ phoneNumbers, subgroupId });
186
- return this.client(`/number`, { method: 'POST', body: { phoneNumbers, subgroupId, country }, ...options });
187
- }
188
-
189
- /**
190
- * Purchase one or more Toll-Free numbers via the asynchronous resource-request flow.
191
- *
192
- * Toll-Free numbers are ordered by quantity (not picked individually) and provisioned asynchronously;
193
- * per-number completion is delivered via webhook/polling, not in this response. The returned `orderId`
194
- * can be polled with {@link Numbers#getTollFreeOrderStatus} for the order's outcome.
195
- * @async
196
- * @roles api, admin, developer, billing, user
197
- * @param {Object} params - The parameters for purchasing toll-free numbers
198
- * @param {number} params.quantity - The number of toll-free numbers to purchase (1-10)
199
- * @param {string} params.subgroupId - The subgroup the purchased numbers are assigned to
200
- * @param {string} [params.country='US'] - ISO-2 purchase country; US.
201
- * @param {RequestOptions} [params.options] - Additional options for the request
202
- * @throws {Error} Throws an error if the quantity or subgroupId parameter is missing
203
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ message, orderId }` once the request is queued.
204
- */
205
- async purchaseTollFreeNumbers({ quantity, subgroupId, country = 'US', options = {} }) {
206
- this.client._require({ quantity, subgroupId });
207
- return this.client(`/number/toll-free`, { method: 'POST', body: { quantity, subgroupId, country }, ...options });
208
- }
209
-
210
- /**
211
- * Request a campaign-bound Short Code acquisition or register a customer-owned Registry lease.
212
- * Random and vanity requests remain pending until Signal House staff fulfill them. An external lease creates a pending Short Code number immediately; it
213
- * becomes READY only when its campaign becomes ACTIVE.
214
- * @async
215
- * @roles api, admin, developer, billing, user
216
- * @param {Object} params - Short Code acquisition parameters.
217
- * @param {string} params.subgroupId - The owning subgroup ID.
218
- * @param {string} params.brandId - The owning Short Code brand ID.
219
- * @param {string} params.campaignId - The owning Short Code campaign ID.
220
- * @param {'RANDOM'|'VANITY'|'EXTERNAL_LEASE'} params.requestType - Acquisition path.
221
- * @param {number} [params.leaseTermMonths] - Required 3, 6, or 12-month term for RANDOM/VANITY.
222
- * @param {string} [params.requestedVanityCode] - Required five- or six-digit desired code for VANITY.
223
- * @param {string} [params.actualCode] - Required customer-owned five- or six-digit code for EXTERNAL_LEASE.
224
- * @param {string} [params.orderId] - Required Registry order ID for EXTERNAL_LEASE.
225
- * @param {string|Date} [params.leaseEndDate] - Required future Registry lease end date for EXTERNAL_LEASE. A YYYY-MM-DD value expires at 23:59:59 UTC.
226
- * @param {Blob|File} [params.leaseReceiptFile] - Required PNG, JPEG, or PDF lease receipt for EXTERNAL_LEASE.
227
- * @param {RequestOptions} [params.options] - Additional options for the request.
228
- * @returns {Promise<SdkResponse<any>>} A pending acquisition request or pending external-lease number.
229
- */
230
- async requestShortCodeAcquisition({
231
- subgroupId,
232
- brandId,
233
- campaignId,
234
- requestType,
235
- requestedVanityCode,
236
- leaseTermMonths,
237
- actualCode,
238
- orderId,
239
- leaseEndDate,
240
- leaseReceiptFile,
241
- options = {},
242
- }) {
243
- this.client._require({ subgroupId, brandId, campaignId, requestType });
244
- const formData = new FormData();
245
- formData.append(
246
- 'acquisitionData',
247
- JSON.stringify({ subgroupId, brandId, campaignId, requestType, requestedVanityCode, leaseTermMonths, actualCode, orderId, leaseEndDate }),
248
- );
249
- if (leaseReceiptFile) formData.append('leaseReceipt', leaseReceiptFile);
250
- return this.multipartClient(`/number/short-code`, {
251
- method: 'POST',
252
- body: formData,
253
- ...options,
254
- });
255
- }
256
-
257
- /**
258
- * Read the outcome of a Toll-Free number purchase by the `orderId` returned from
259
- * {@link Numbers#purchaseTollFreeNumbers}. Reports per-number status as ready / provisioning / failed
260
- * counts (plus failure reasons) so a client can poll until the order reaches a terminal state, and
261
- * returns the provisioned phone numbers for the order so a client can act on exactly those numbers.
262
- * `numbers` is empty until each number is provisioned (it fills in as the order completes).
263
- * @async
264
- * @roles api, admin, developer, billing, user
265
- * @param {Object} params - The parameters for reading the order status
266
- * @param {string} params.orderId - The order id returned by `purchaseTollFreeNumbers`
267
- * @param {string} [params.groupId] - Staff and service callers only: the order's group, whose carrier the read follows.
268
- * Their tokens carry no active group; every other caller's order is read by its active group, so a well-formed
269
- * groupId is ignored and a malformed one gets a 400.
270
- * @param {RequestOptions} [params.options] - Additional options for the request
271
- * @throws {Error} Throws an error if the orderId parameter is missing
272
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ orderId, counts: { ready, provisioning, failed }, failures: [{ reason }], numbers: string[] }`.
273
- */
274
- async getTollFreeOrderStatus({ orderId, groupId, options = {} }) {
275
- this.client._require({ orderId });
276
- const safeOrderId = encodeURIComponent(orderId);
277
- const queryString = this.client._getQueryString({ groupId });
278
- return this.client(`/number/toll-free/order/${safeOrderId}${queryString}`, { method: 'GET', ...options });
279
- }
280
-
281
- /**
282
- * Update an existing phone number's details (e.g., setting a friendly name)
283
- * @async
284
- * @roles api, admin, developer, user
285
- * @param {Object} params - The parameters for updating the phone number
286
- * @param {string} params.phoneNumber - The phone number to update
287
- * @param {Object} params.updateData - The data to update for the phone number
288
- * @param {string} [params.updateData.friendlyName] - An optional friendly name for the phone number
289
- * @param {string|null} [params.updateData.primaryInboundWebhookUrl] - Primary inbound voice webhook URL (http/https). When set, inbound calls to this number are driven by the SHML your webhook returns (programmable call control). Pass null or an empty string to clear.
290
- * @param {string|null} [params.updateData.secondaryInboundWebhookUrl] - Secondary inbound voice webhook URL (http/https), used for failover when the primary returns an error. Pass null or an empty string to clear.
291
- * @param {RequestOptions} [params.options] - Additional options for the request
292
- * @throws {Error} Throws an error if the phoneNumber or updateData parameter is missing
293
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated phone number object
294
- */
295
- async updatePhoneNumber({ phoneNumber, updateData, options = {} }) {
296
- this.client._require({ phoneNumber, updateData });
297
-
298
- // Safely encode the phone number for the URL path
299
- const safePhoneNumber = encodeURIComponent(phoneNumber);
300
-
301
- return this.client(`/number/${safePhoneNumber}`, {
302
- method: 'PUT',
303
- body: updateData,
304
- ...options,
305
- });
306
- }
307
-
308
- /**
309
- * Get a phone number's outbound caller name (CNAM) - the name US carriers show for calls from it
310
- * @async
311
- * @roles api, admin, developer, billing, user
312
- * @param {Object} params - The parameters for the request
313
- * @param {string} params.phoneNumber - The phone number (E.164, leading + optional)
314
- * @param {RequestOptions} [params.options] - Additional options for the request
315
- * @throws {Error} Throws an error if the phoneNumber parameter is missing
316
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, cnam, autoApply, eligible, ineligibleReason }`
317
- */
318
- async getCallerName({ phoneNumber, options = {} }) {
319
- this.client._require({ phoneNumber });
320
- const safePhoneNumber = encodeURIComponent(phoneNumber);
321
- return this.client(`/number/${safePhoneNumber}/cnam`, { method: 'GET', ...options });
322
- }
323
-
324
- /**
325
- * Set a phone number's outbound caller name (CNAM). The name may only remove characters from the
326
- * registered name of the number's brand (its campaign's brand, else `brandId`, else the subgroup's
327
- * default caller-ID brand), and must be 1-15 letters, digits, spaces, `-` or `_`.
328
- * @async
329
- * @roles api, admin, developer
330
- * @param {Object} params - The parameters for the request
331
- * @param {string} params.phoneNumber - The phone number (E.164, leading + optional)
332
- * @param {string} params.name - The caller name to show
333
- * @param {string} [params.brandId] - The verified brand the name comes from; only for numbers with no campaign
334
- * @param {RequestOptions} [params.options] - Additional options for the request
335
- * @throws {Error} Throws an error if the phoneNumber or name parameter is missing
336
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, cnam, autoApply, eligible, ineligibleReason }`
337
- */
338
- async setCallerName({ phoneNumber, name, brandId, options = {} }) {
339
- this.client._require({ phoneNumber, name });
340
- const safePhoneNumber = encodeURIComponent(phoneNumber);
341
- const body = brandId ? { name, brandId } : { name };
342
- return this.client(`/number/${safePhoneNumber}/cnam`, { method: 'PUT', body, ...options });
343
- }
344
-
345
- /**
346
- * Remove a phone number's own caller name (CNAM). If its subgroup has caller name auto-apply on, the
347
- * number goes back to the automatic name.
348
- * @async
349
- * @roles api, admin, developer
350
- * @param {Object} params - The parameters for the request
351
- * @param {string} params.phoneNumber - The phone number (E.164, leading + optional)
352
- * @param {RequestOptions} [params.options] - Additional options for the request
353
- * @throws {Error} Throws an error if the phoneNumber parameter is missing
354
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, cnam, autoApply, eligible, ineligibleReason }`
355
- */
356
- async deleteCallerName({ phoneNumber, options = {} }) {
357
- this.client._require({ phoneNumber });
358
- const safePhoneNumber = encodeURIComponent(phoneNumber);
359
- return this.client(`/number/${safePhoneNumber}/cnam`, { method: 'DELETE', ...options });
360
- }
361
-
362
- /**
363
- * Submit a port-in request for one or more phone numbers from another provider
364
- * @async
365
- * @roles api, admin, developer, billing, user
366
- * @param {Object} params - The parameters for the port-in request
367
- * @param {Object} params.numberData - The port-in request data including owner info, address, phone numbers, and signature
368
- * @param {RequestOptions} [params.options] - Additional options for the request
369
- * @throws {Error} Throws an error if the numberData parameter is missing
370
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the created port-in request
371
- */
372
- async portInPhoneNumber({ numberData, options = {} }) {
373
- this.client._require({ numberData });
374
- return this.client(`/number/portin`, { method: 'POST', body: numberData, ...options });
375
- }
376
-
377
- /**
378
- * Get port-in requests with optional filters. Signal House staff can view all requests; regular users see only their group's requests.
379
- * @async
380
- * @roles api, admin, developer, billing, user
381
- * @param {Object} [params] - The parameters for filtering port-in requests
382
- * @param {string} [params.groupId] - Filter by group ID
383
- * @param {string} [params.phoneNumber] - Filter by phone number
384
- * @param {string} [params.status] - Filter by status (PENDING, IN_PROGRESS, ON_HOLD, REJECTED, SUCCESS)
385
- * @param {number} [params.page] - The page number for pagination (default: 1)
386
- * @param {number} [params.limit] - The number of items per page (default: 20)
387
- * @param {boolean} [params.excludeDocuments] - When true, leave signatureUrl and billingUrl out of each request (the inline LOA signature and billing statement). Fetch one request with getPortRequestById to read them.
388
- * @param {RequestOptions} [params.options] - Additional options for the request
389
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the paginated list of port-in requests
390
- */
391
- async getPortRequests({ groupId, phoneNumber, status, page, limit, excludeDocuments, options = {} } = {}) {
392
- const filters = { groupId, phoneNumber, status, page, limit, excludeDocuments };
393
- const queryString = this.client._getQueryString(filters);
394
- return this.client(`/number/portin${queryString}`, { method: 'GET', ...options });
395
- }
396
-
397
- /**
398
- * Get a single port-in request by its ID
399
- * @async
400
- * @roles api, admin, developer, billing, user
401
- * @param {Object} params - The parameters for getting the port request
402
- * @param {string} params.id - The _id of the port-in request
403
- * @param {RequestOptions} [params.options] - Additional options for the request
404
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the port-in request object
405
- */
406
- async getPortRequestById({ id, options = {} }) {
407
- this.client._require({ id });
408
- const safeId = encodeURIComponent(id);
409
- return this.client(`/number/portin/${safeId}`, { method: 'GET', ...options });
410
- }
411
-
412
- /**
413
- * Get porting requests - fetches a single request by portingId, or delegates to getPortRequests for listing
414
- * @async
415
- * @roles api, admin, developer, billing, user
416
- * @param {Object} params - The parameters
417
- * @param {string} [params.portingId] - If provided, fetches a single port request by ID
418
- * @param {number} [params.page] - Page number for pagination (used when listing)
419
- * @param {number} [params.limit] - Items per page (used when listing)
420
- * @param {RequestOptions} [params.options] - Additional options for the request
421
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the port-in request(s)
422
- */
423
- async getPortingRequests({ portingId, page, limit, options = {} } = {}) {
424
- if (portingId) {
425
- return this.getPortRequestById({ id: portingId, options });
426
- }
427
- return this.getPortRequests({ page, limit, options });
428
- }
429
-
430
- /**
431
- * Assign phone numbers to a campaign by providing the campaign ID and a list of phone numbers to assign.
432
- * Numbers that are not found, already RELEASED, currently being released (transient PENDING_RELEASE
433
- * status), already assigned to a different campaign, on a mismatched DCA, or (for a 10DLC campaign
434
- * without a number pool) beyond the remaining 49-number-per-campaign limit are not queued - each is
435
- * reported back individually in `skipped` instead of failing the whole request. A Toll-Free campaign
436
- * whose brand reports `tollFree.maxNumbersPerCampaign` as 1 holds one number: a request that would give
437
- * it a second is refused with a 400 and nothing is queued.
438
- * @async
439
- * @roles api, admin, developer, billing, user
440
- * @param {Object} params - The parameters for assigning phone numbers to a campaign
441
- * @param {string} params.campaignId - The ID of the campaign to assign phone numbers to
442
- * @param {string[]} params.phoneNumbers - The list of phone numbers to assign to the campaign
443
- * @param {RequestOptions} [params.options] - Additional options for the request
444
- * @throws {Error} Throws an error if the campaignId or phoneNumbers parameter is missing, if none of the phone numbers exist in the account, or if the campaign is not found or in a terminal state
445
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ Message, queued, skipped }` - `queued` numbers were sent for assignment; `skipped` numbers were rejected (not found, RELEASED, currently being released, already assigned to a campaign, cross-DCA mismatch, or over the 49-number limit).
446
- */
447
- async assignPhoneNumberToCampaign({ campaignId, phoneNumbers, options = {} }) {
448
- this.client._require({ campaignId, phoneNumbers });
449
- const safeCampaignId = encodeURIComponent(campaignId);
450
- return this.client(`/number/assign/${safeCampaignId}`, { method: 'POST', body: { phoneNumbers }, ...options });
451
- }
452
-
453
- /**
454
- * Unassign phone numbers from a campaign by providing a list of phone numbers to unassign. Note: This operation will unassign the specified phone numbers from any campaign they are currently assigned to.
455
- * @async
456
- * @roles api, admin, developer, billing, user
457
- * @param {Object} params - The parameters for unassigning phone numbers from campaigns
458
- * @param {string[]} params.phoneNumbers - The list of phone numbers to unassign from campaigns
459
- * @param {RequestOptions} [params.options] - Additional options for the request
460
- * @throws {Error} Throws an error if the phoneNumbers parameter is missing
461
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the result of the unassignment operation
462
- */
463
- async unassignPhoneNumbersFromCampaigns({ phoneNumbers, options = {} }) {
464
- this.client._require({ phoneNumbers });
465
- return this.client(`/number/unassign`, { method: 'POST', body: { phoneNumbers }, ...options });
466
- }
467
-
468
- /**
469
- * Delete a list of phone numbers (mark them as RELEASED). The phone numbers will no longer be active or usable but they will still be visible in the system with a status of "RELEASED". A number briefly shows a transient "PENDING_RELEASE" status while the deletion is being processed, before settling to "RELEASED". Note: This operation is irreversible and should be used with caution.
470
- * @async
471
- * @roles api, admin, developer, billing, user
472
- * @param {Object} params - The parameters for deleting phone numbers
473
- * @param {string[]} params.phoneNumbers - The list of phone numbers to delete
474
- * @param {RequestOptions} [params.options] - Additional options for the request
475
- * @throws {Error} Throws an error if the phoneNumbers parameter is missing
476
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the result of the deletion operation
477
- */
478
- async deletePhoneNumbers({ phoneNumbers, options = {} }) {
479
- this.client._require({ phoneNumbers });
480
- return this.client(`/number`, { method: 'DELETE', body: { phoneNumbers }, ...options });
481
- }
482
-
483
- /**
484
- * Deactivate one or more phone numbers. Numbers must be in READY status to be deactivated. Deactivated numbers will not be able to send or receive messages but will remain assigned to their subgroup and campaign.
485
- * @async
486
- * @roles api, admin, developer, billing, user
487
- * @param {Object} params - The parameters for deactivating phone numbers
488
- * @param {string[]} params.phoneNumbers - The list of phone numbers to deactivate
489
- * @param {RequestOptions} [params.options] - Additional options for the request
490
- * @throws {Error} Throws an error if the phoneNumbers parameter is missing
491
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to an array of updated phone number objects
492
- */
493
- async deactivatePhoneNumbers({ phoneNumbers, options = {} }) {
494
- this.client._require({ phoneNumbers });
495
- return this.client(`/number/deactivate`, { method: 'POST', body: { phoneNumbers }, ...options });
496
- }
497
-
498
- /**
499
- * Reactivate one or more previously deactivated phone numbers. Numbers must be in DEACTIVATED status to be reactivated. Reactivated numbers will return to PENDING or IN_PROGRESS status depending on their campaign assignment.
500
- * @async
501
- * @roles api, admin, developer, billing, user
502
- * @param {Object} params - The parameters for reactivating phone numbers
503
- * @param {string[]} params.phoneNumbers - The list of phone numbers to reactivate
504
- * @param {RequestOptions} [params.options] - Additional options for the request
505
- * @throws {Error} Throws an error if the phoneNumbers parameter is missing
506
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to an array of updated phone number objects
507
- */
508
- async reactivatePhoneNumbers({ phoneNumbers, options = {} }) {
509
- this.client._require({ phoneNumbers });
510
- return this.client(`/number/reactivate`, { method: 'POST', body: { phoneNumbers }, ...options });
511
- }
512
-
513
- /**
514
- * Transfer unassigned phone numbers from one subgroup to another.
515
- * @async
516
- * @param {Object} params - The parameters for transferring phone numbers
517
- * @param {string[]} params.phoneNumbers - The list of phone numbers to transfer
518
- * @param {string} params.newSubgroupId - The ID of the new subgroup to transfer the phone numbers to
519
- * @param {RequestOptions} [params.options] - Additional options for the request
520
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to the result of the transfer operation
521
- */
522
- async transferPhoneNumbers({ phoneNumbers, newSubgroupId, options = {} }) {
523
- this.client._require({ phoneNumbers, newSubgroupId });
524
- return this.client(`/number/transfer`, { method: 'POST', body: { phoneNumbers, newSubgroupId }, ...options });
525
- }
526
-
527
- /**
528
- * Search NPA/NXX lookup data with optional filters.
529
- * At least one search parameter is required.
530
- * Country may scope NPA/NXX filters; state and city cannot be combined with them.
531
- * @async
532
- * @roles api, admin, developer, billing, user
533
- * @param {Object} params - The parameters for searching NPA/NXX data
534
- * @param {string} [params.country] - Filter by country code
535
- * @param {string} [params.state] - Filter by state code (2 characters)
536
- * @param {string} [params.city] - Filter by city name (prefix match, case-insensitive; requires country and state)
537
- * @param {string} [params.npa] - Area code filter (1-3 digits; optional country, no state/city)
538
- * @param {string} [params.nxx] - Central office code filter (1-3 digits; optional country, no state/city)
539
- * @param {RequestOptions} [params.options] - Additional options for the request
540
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to matching NPA/NXX records or unique NPA/NXX arrays
541
- */
542
- async searchNpaNxx({ country, state, city, npa, nxx, options = {} }) {
543
- const queryString = this.client._getQueryString({ country, state, city, npa, nxx });
544
- return this.client(`/number/lookup${queryString}`, { method: 'GET', ...options });
545
- }
546
-
547
- /**
548
- * Batch lookup city/state for NPA/NXX pairs
549
- * @async
550
- * @roles api, admin, developer, billing, user
551
- * @param {Object} params - The parameters for the lookup
552
- * @param {Array<{npa: string, nxx: string}>} params.entries - NPA/NXX pairs to look up (max 50)
553
- * @param {RequestOptions} [params.options] - Additional options for the request
554
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to an array of {npa, nxx, city, state} objects
555
- */
556
- async lookupLocations({ entries, options = {} }) {
557
- return this.client('/number/lookup/location', { method: 'POST', body: { entries }, ...options });
558
- }
559
-
560
- /**
561
- * Migrate a phone number (or all numbers in a campaign/group) from v1 to v2
562
- * @async
563
- * @roles api, admin, developer, billing, user, signalhouse_api, signalhouse_admin, signalhouse_user
564
- * @param {Object} params - The parameters for migration
565
- * @param {string} [params.phoneNumber] - The phone number to migrate
566
- * @param {string} [params.campaignId] - Campaign ID to migrate all numbers for
567
- * @param {string} [params.groupId] - Group ID to migrate all numbers for
568
- * @param {RequestOptions} [params.options] - Additional options for the request
569
- * @returns {Promise<SdkResponse<any>>} A promise that resolves to a confirmation with count of queued numbers
570
- */
571
- async migratePhoneNumberToV2({ phoneNumber, campaignId, groupId, options = {} }) {
572
- return this.client(`/number/migrate`, { method: 'POST', body: { phoneNumber, campaignId, groupId }, ...options });
573
- }
574
- }