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