@signalhousellc/sdk 1.4.3 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@signalhousellc/sdk",
3
- "version": "1.4.3",
3
+ "version": "1.5.1",
4
4
  "description": "Signal House SDK for use with the Signal House platform",
5
5
  "type": "module",
6
6
  "main": "src/SignalHouseSDK.js",
@@ -247,7 +247,8 @@ export class Billing {
247
247
  }
248
248
 
249
249
  /**
250
- * Get the fee schedule for a specific group
250
+ * Get the fee schedule for a specific group.
251
+ * When the group is on a custom volume-tiered plan, the response also includes volumePricing: tiers, the current period's dates, count and minimum, ramp, and current rate (rates in microdollars per segment).
251
252
  * @async
252
253
  * @roles api, admin, developer, billing, user
253
254
  * @param {Object} params - The parameters for getting the fees
@@ -80,6 +80,39 @@
80
80
  * @property {string} [businessWebsite] - The customer's real website, sent to Infobip for brand verification (optional, valid URL, at most 255 characters; distinct from the top-level website / landing URL)
81
81
  */
82
82
 
83
+ /**
84
+ * @typedef {Object} BusinessVerificationDetails
85
+ * @property {string} businessName - The legal business name (required, at most 255 characters)
86
+ * @property {string} businessType - The business type (required, one of CO_OPERATIVE, CORPORATION, LIMITED_LIABILITY_CORPORATION, NON_PROFIT_CORPORATION, PARTNERSHIP)
87
+ * @property {string} industry - The business industry (required, one of AGRICULTURE, AUTOMOTIVE, BANKING, CONSTRUCTION, CONSUMER, EDUCATION, ELECTRONICS, ENGINEERING, ENERGY, FAST_MOVING_CONSUMER_GOODS, FINANCIAL, FINTECH, FOOD_AND_BEVERAGE, GOVERNMENT, HEALTHCARE, HOSPITALITY, INSURANCE, JEWELRY, LEGAL, MANUFACTURING, MEDIA, NOT_FOR_PROFIT, OIL_AND_GAS, ONLINE, PROFESSIONAL_SERVICES, RAW_MATERIALS, REAL_ESTATE, RELIGION, RETAIL, TECHNOLOGY, TELECOMMUNICATIONS, TRANSPORTATION, TRAVEL)
88
+ * @property {string} registrationType - The business registration type (required, one of EIN, CBN, NEQ, PROVINCIAL_NUMBER, CRN, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST_IDNR, CIF, NIF, CNPJ, UID, OTHER)
89
+ * @property {string} registrationNumber - The business registration number, e.g. the EIN (required, at most 50 characters)
90
+ * @property {string} website - The business website (required, valid URL, at most 255 characters)
91
+ * @property {string} street - The business street address (required, at most 255 characters)
92
+ * @property {string} [street2] - The second line of the street address (optional, at most 255 characters)
93
+ * @property {string} city - The business city (required, at most 100 characters)
94
+ * @property {string} state - The business state or province (required, 2-letter code)
95
+ * @property {string} postalCode - The business postal code (required, at most 10 characters)
96
+ * @property {string} country - The business country (required, "US" or "CA")
97
+ * @property {Object} representative - The business's authorized representative (required)
98
+ * @property {string} representative.firstName - The representative's first name (required, at most 100 characters)
99
+ * @property {string} representative.lastName - The representative's last name (required, at most 100 characters)
100
+ * @property {string} representative.email - The representative's email address (required, valid email, at most 100 characters)
101
+ * @property {string} representative.phone - The representative's phone number (required, E.164 with an optional leading "+" and no spaces, parentheses or hyphens, e.g. "+17025550100")
102
+ * @property {string} representative.jobTitle - The representative's job title (required, at most 100 characters)
103
+ * @property {string} representative.jobLevel - The representative's job level (required, one of DIRECTOR, GM, VP, CEO, CFO, GENERAL_COUNSEL, OTHER)
104
+ */
105
+
106
+ /**
107
+ * @typedef {Object} TollFreeIsvAccount
108
+ * @property {string} groupId - The group the account is registered to
109
+ * @property {string} accountSid - The SID of the group's own top-level account at the toll-free provider
110
+ * @property {string} apiKeySid - The SID of the API key Signal House uses in that account (its secret is never returned)
111
+ * @property {string} primaryProfileSid - The SID of the account's approved primary business profile, found when the account was registered
112
+ * @property {string} createdAt - When the account was first registered (ISO date)
113
+ * @property {string} updatedAt - When the account or its API key was last saved (ISO date)
114
+ */
115
+
83
116
  /**
84
117
  * @typedef {Object} CreateTollFreeBrandData
85
118
  * @property {string} subgroupId - The ID of the subgroup to create the brand under (required, exactly 8 characters)
@@ -140,6 +173,7 @@ export class Brands {
140
173
  * @param {number} [params.limit] - The number of items per page
141
174
  * @param {string} [params.status] - The status of the brand to filter by (PENDING_CREATION, PENDING_APPROVAL, UNVERIFIED, VERIFIED, VETTED_VERIFIED, PENDING_DELETE, DELETED)
142
175
  * @param {string} [params.registrationType] - Filter by registration type ("TEN_DLC", "TOLL_FREE", or "SHORT_CODE")
176
+ * @param {boolean} [params.currentTollFreeCarrier] - With subgroupId or groupId: when true, return only toll-free brands that a new toll-free campaign in that group can use (those on the group's current toll-free carrier)
143
177
  * @param {string} [params.search] - Staff-only (no id/subgroupId/groupId): case-insensitive substring over brandId, names, EIN, email, group, subgroup and reference ID
144
178
  * @param {string} [params.sortBy] - Staff-only: createdAt, brandId, displayName, groupId, subgroupId, status, entityType or country
145
179
  * @param {"asc"|"desc"} [params.sortOrder] - Staff-only: sort direction (default asc)
@@ -153,7 +187,7 @@ export class Brands {
153
187
  * @param {boolean} [params.excludeDeleted] - Staff-only: hide DELETED brands when no status is given
154
188
  * @param {boolean} [params.includeTotal] - Staff-only: with page and limit, return `{ data, total, page, limit, totalPages }` instead of the array
155
189
  * @param {RequestOptions} [params.options] - Additional options for the request
156
- * @returns {Promise<SdkResponse<Array<{ _id: string, brandId: string|null, status: string, registrationType: string, [key: string]: any }>|{ data: Array<Object>, total: number, page: number, limit: number, totalPages: number }>>} Brand records. For 10DLC brands in PENDING_CREATION (or rejected before carrier assignment), brandId is null — poll by _id until status advances and brandId is assigned. The staff-only list (no id/subgroupId/groupId) returns the `{ data, total, page, limit, totalPages }` envelope only when includeTotal is sent with page and limit.
190
+ * @returns {Promise<SdkResponse<Array<{ _id: string, brandId: string|null, status: string, registrationType: string, tollFree?: { isBrandReady?: boolean, maxNumbersPerCampaign?: number, maxOptInMethods?: number, requiresPrivacyPolicy?: boolean, requiresTermsAndConditions?: boolean, maxAppealReasonLength?: number, labelsSamples?: boolean, supportsMms?: boolean, usesBusinessVerification?: boolean, [key: string]: any }, [key: string]: any }>|{ data: Array<Object>, total: number, page: number, limit: number, totalPages: number }>>} Brand records. For 10DLC brands in PENDING_CREATION (or rejected before carrier assignment), brandId is null — poll by _id until status advances and brandId is assigned. Toll-free brands carry `tollFree.isBrandReady` (whether the brand can host campaigns), `tollFree.maxNumbersPerCampaign` (the most numbers one of its campaigns can hold), `tollFree.maxOptInMethods` (the most opt-in methods one of its campaigns can declare), `tollFree.requiresPrivacyPolicy` (whether its campaigns need a privacy policy URL), `tollFree.requiresTermsAndConditions` (whether its campaigns need a terms and conditions URL), `tollFree.maxAppealReasonLength` (the longest appeal reason its campaigns may give), `tollFree.labelsSamples` (whether its campaigns' sample messages each start with their use case's name), `tollFree.supportsMms` (whether its numbers can send MMS and group messages) and `tollFree.usesBusinessVerification` (whether it waits on the business verification that applies to its subgroup). The staff-only list (no id/subgroupId/groupId) returns the `{ data, total, page, limit, totalPages }` envelope only when includeTotal is sent with page and limit.
157
191
  */
158
192
  async getBrands({
159
193
  id,
@@ -163,6 +197,7 @@ export class Brands {
163
197
  limit,
164
198
  status,
165
199
  registrationType,
200
+ currentTollFreeCarrier,
166
201
  search,
167
202
  sortBy,
168
203
  sortOrder,
@@ -185,6 +220,7 @@ export class Brands {
185
220
  limit,
186
221
  status,
187
222
  registrationType,
223
+ currentTollFreeCarrier,
188
224
  search,
189
225
  sortBy,
190
226
  sortOrder,
@@ -248,6 +284,86 @@ export class Brands {
248
284
  return this.client(`/brand/toll-free`, { method: 'POST', body: brandData, ...options });
249
285
  }
250
286
 
287
+ /**
288
+ * Get a group's business verification: whether its toll-free brands need one, its status and the submitted details.
289
+ * Some groups verify each subgroup's business separately: a platform whose subgroups are separate businesses, set up by
290
+ * Signal House. For those groups pass the subgroup whose business verification to get.
291
+ * @async
292
+ * @roles api, admin, developer, billing, user
293
+ * @param {Object} params - The parameters for getting the business verification
294
+ * @param {string} params.groupId - The ID of the group whose business verification to get
295
+ * @param {string} [params.subgroupId] - The subgroup whose business verification to get, sent as a query parameter only when given. Required for a group that verifies each subgroup's business separately; for any other group it must be one of the group's subgroups and is otherwise ignored
296
+ * @param {RequestOptions} [params.options] - Additional options for the request
297
+ * @throws {Error} Throws an error if the groupId parameter is missing
298
+ * @returns {Promise<SdkResponse<{ groupId: string, subgroupId?: string, required: boolean, status: string, details: BusinessVerificationDetails|null, submittedAt: string|null, reviewedAt: string|null, rejectionReason: string|null }>>} The business verification. `subgroupId` is present only when it belongs to one subgroup: the subgroup whose business it describes. `required` says whether the group's new toll-free brands need one; `status` is NOT_STARTED, SUBMITTING, IN_REVIEW, VERIFIED or NEEDS_CHANGES; `rejectionReason` says why it needs changes, or is null. When `required` is true and `status` is NOT_STARTED, submit it before creating the first toll-free brand it covers. The API returns 400 when the group verifies each subgroup's business separately and no subgroupId is given, and 404 when the subgroup is not in the group.
299
+ */
300
+ async getBusinessVerification({ groupId, subgroupId, options = {} }) {
301
+ this.client._require({ groupId });
302
+ const queryString = this.client._getQueryString({ subgroupId });
303
+ return this.client(`/brand/business-verification/${encodeURIComponent(groupId)}${queryString}`, { method: 'GET', ...options });
304
+ }
305
+
306
+ /**
307
+ * Submit or update a group's business verification, or one subgroup's in a group that verifies each subgroup's business
308
+ * separately. Allowed when it is not started or needs changes. Review usually takes 1–2 business days; the toll-free
309
+ * brands it covers stay pending until it is verified.
310
+ * @async
311
+ * @roles api, admin, developer, billing, user
312
+ * @param {Object} params - The parameters for submitting the business verification
313
+ * @param {string} params.groupId - The ID of the group whose business verification to submit (must be the caller's active group)
314
+ * @param {string} [params.subgroupId] - The subgroup whose business verification to submit, sent as a query parameter only when given. Required for a group that verifies each subgroup's business separately; for any other group it must be one of the group's subgroups and is otherwise ignored. The subgroup must be active
315
+ * @param {BusinessVerificationDetails} params.details - The business verification details (see BusinessVerificationDetails typedef for details)
316
+ * @param {RequestOptions} [params.options] - Additional options for the request
317
+ * @throws {Error} Throws an error if the groupId or details parameter is missing
318
+ * @returns {Promise<SdkResponse<{ groupId: string, subgroupId?: string, required: boolean, status: string, details: BusinessVerificationDetails|null, submittedAt: string|null, reviewedAt: string|null, rejectionReason: string|null }>>} A 202 with the business verification, now SUBMITTING (the same shape as getBusinessVerification, with `subgroupId` only when it belongs to one subgroup). The API returns 400 when the group verifies each subgroup's business separately and no subgroupId is given, or when the subgroup is inactive, and 404 when the subgroup is not in the group.
319
+ */
320
+ async submitBusinessVerification({ groupId, subgroupId, details, options = {} }) {
321
+ this.client._require({ groupId, details });
322
+ const queryString = this.client._getQueryString({ subgroupId });
323
+ return this.client(`/brand/business-verification/${encodeURIComponent(groupId)}${queryString}`, { method: 'PUT', body: details, ...options });
324
+ }
325
+
326
+ /**
327
+ * Get a group's toll-free ISV account: the group's own top-level account at the toll-free provider, used when its
328
+ * subgroups are separate businesses. Each subgroup gets an account and a business verification of its own under it.
329
+ * Staff only.
330
+ * @async
331
+ * @roles signalhouse_api, signalhouse_admin, signalhouse_user
332
+ * @param {Object} params - The parameters for getting the toll-free ISV account
333
+ * @param {string} params.groupId - The ID of the group whose toll-free ISV account to get
334
+ * @param {RequestOptions} [params.options] - Additional options for the request
335
+ * @throws {Error} Throws an error if the groupId parameter is missing
336
+ * @returns {Promise<SdkResponse<TollFreeIsvAccount|null>>} The group's toll-free ISV account, or null when it has none. The API key secret is never returned. The API returns 404 when the group does not exist or is not active.
337
+ */
338
+ async getTollFreeIsvAccount({ groupId, options = {} }) {
339
+ this.client._require({ groupId });
340
+ return this.client(`/brand/toll-free-isv-account/${encodeURIComponent(groupId)}`, { method: 'GET', ...options });
341
+ }
342
+
343
+ /**
344
+ * Register a group's toll-free ISV account, or replace the API key of the account it already has. Staff only. The
345
+ * toll-free provider checks the account and key before they are stored. Register it before the group has any toll-free
346
+ * records at the provider; after that, only the API key of the same account can be replaced.
347
+ * @async
348
+ * @roles signalhouse_admin
349
+ * @param {Object} params - The parameters for setting the toll-free ISV account
350
+ * @param {string} params.groupId - The ID of the group whose toll-free ISV account to set
351
+ * @param {string} params.accountSid - The SID of the group's own top-level account at the toll-free provider (AC followed by 32 lowercase hexadecimal characters)
352
+ * @param {string} params.apiKeySid - The SID of a Main API key in that account, which can create subaccounts (SK followed by 32 lowercase hexadecimal characters)
353
+ * @param {string} params.apiKeySecret - The API key's secret (1 to 128 characters), stored encrypted and never returned
354
+ * @param {RequestOptions} [params.options] - Additional options for the request
355
+ * @throws {Error} Throws an error if the groupId, accountSid, apiKeySid or apiKeySecret parameter is missing
356
+ * @returns {Promise<SdkResponse<TollFreeIsvAccount>>} The stored toll-free ISV account, without the API key secret. The API returns 400 when the provider refuses the account or its key, and 404 when the group does not exist or is not active.
357
+ */
358
+ async setTollFreeIsvAccount({ groupId, accountSid, apiKeySid, apiKeySecret, options = {} }) {
359
+ this.client._require({ groupId, accountSid, apiKeySid, apiKeySecret });
360
+ return this.client(`/brand/toll-free-isv-account/${encodeURIComponent(groupId)}`, {
361
+ method: 'PUT',
362
+ body: { accountSid, apiKeySid, apiKeySecret },
363
+ ...options,
364
+ });
365
+ }
366
+
251
367
  /**
252
368
  * Create a local Short Code brand for manual Signal House review.
253
369
  * @async
@@ -96,7 +96,7 @@
96
96
  * @property {TollFreeOptIn} [optIns.keyword] - Keyword opt-in details
97
97
  * @property {TollFreeOptIn} [optIns.interactiveVoiceResponse] - IVR opt-in details
98
98
  * @property {string} [multiNumberReason] - Internally-stored reason the customer requested more than one Toll-Free number on the campaign (optional, at most 500 characters). Required when more than one phone number is assigned; captured for Signal House review only and never sent to the carrier.
99
- * @property {string[]} [useCases] - The sender's real use-case picks (optional). `useCase` above carries the single value the carrier accepts (MIXED when there is more than one); these are what a Signal House landing page renders a consent checkbox per. Never forwarded to the carrier.
99
+ * @property {string[]} [useCases] - The sender's real use-case picks (optional). `useCase` above carries the single value the carrier accepts (MIXED when there is more than one); these are what a Signal House landing page renders a consent checkbox per. Carriers that need specific use cases rather than MIXED take them from here when present; other carriers never receive them.
100
100
  * @property {string[]} [channels] - The channels consent covers ("SMS", "MMS", "VOICE") (optional). Never forwarded to the carrier.
101
101
  * @property {string} [landingId] - The Signal House landing page whose consent boxes this campaign's call-to-action describes (optional). Must be an ACTIVE page owned by the same brand and group.
102
102
  */
@@ -105,11 +105,11 @@
105
105
  * @typedef {Object} CreateTollFreeCampaignData
106
106
  * @property {string} brandId - The ID of the Toll-Free brand associated with the campaign (required, at least 7 characters)
107
107
  * @property {TollFreeCampaignDetails} tollFree - The Toll-Free campaign details (required)
108
- * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy (optional, at most 2048 characters)
109
- * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions (optional, at most 2048 characters)
108
+ * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy (at most 2048 characters). Required when the brand's `tollFree.requiresPrivacyPolicy` is true and the brand has no `privacyPolicyLink` of its own; optional otherwise.
109
+ * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions (at most 2048 characters). Required when the brand's `tollFree.requiresTermsAndConditions` is true and the brand has no `termsAndConditionsLink` of its own; optional otherwise.
110
110
  * @property {string} [tag] - A tag for the campaign (optional, at most 255 characters)
111
111
  * @property {boolean} [autoRenewal=true] - Whether the campaign should auto-renew (optional, defaults to true)
112
- * @property {Array<string>} phoneNumbers - The Toll-Free numbers to assign to the campaign (required, at least 1 and at most 5, each at least 10 digits and digits only). Numbers are locked to the campaign once assigned and cannot be moved or added afterward.
112
+ * @property {Array<string>} phoneNumbers - The Toll-Free numbers to assign to the campaign (required, 1 up to the brand's tollFree.maxNumbersPerCampaign and at most 5, each at least 10 digits and digits only). The numbers must be on the brand's toll-free carrier, or the campaign is refused. Numbers are locked to the campaign once assigned and cannot be moved or added afterward.
113
113
  */
114
114
 
115
115
  /**
@@ -108,8 +108,10 @@ export class Messages {
108
108
 
109
109
  /**
110
110
  * Fetch the latest upstream carrier delivery report for a set of messages by ID (SHGHL-1856).
111
- * Useful for reconciling messages stuck in a non-terminal state. SMS and MMS messages are looked up
112
- * against the carrier; other message types are returned with their stored status.
111
+ * Useful for reconciling messages stuck in a non-terminal state. Outbound SMS and MMS messages sent from numbers on
112
+ * the carrier whose delivery logs we read are looked up there (the logs are kept about 48 hours); every other message,
113
+ * including P2P messages and messages sent from numbers on other carriers, is returned with its stored status and
114
+ * upstreamReportAvailable false. The request fails with a 500 when the sending numbers can't be read.
113
115
  * @async
114
116
  * @roles api, admin, developer, billing, user
115
117
  * @param {Object} params - The parameters for fetching delivery reports
@@ -13,22 +13,24 @@ export class Numbers {
13
13
  if (enableAdmin) {
14
14
  this.admin = {
15
15
  /**
16
- * Update a port-in request's status (signalhouse only)
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.
17
18
  * @async
18
19
  * @roles signalhouse
19
20
  * @param {Object} params - The parameters for updating the status
20
21
  * @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.status - The new status (PENDING, IN_PROGRESS, ON_HOLD, REJECTED)
22
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)
23
25
  * @param {RequestOptions} [params.options] - Additional options for the request
24
26
  * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated port-in request
25
27
  */
26
- changePortingStatus: async ({ portingId, status, description, options = {} }) => {
28
+ changePortingStatus: async ({ portingId, status, description, onHoldReason, options = {} }) => {
27
29
  this.client._require({ portingId, status });
28
30
  const safeId = encodeURIComponent(portingId);
29
31
  return this.client(`/number/portin/${safeId}/status`, {
30
32
  method: 'PUT',
31
- body: { status, description },
33
+ body: { status, description, onHoldReason },
32
34
  ...options,
33
35
  });
34
36
  },
@@ -81,6 +83,7 @@ export class Numbers {
81
83
  * @param {string} [params.brandId] - Filter by brand ID
82
84
  * @param {string} [params.subgroupId] - Filter by subgroup ID
83
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)
84
87
  * @param {number} [params.page] - The page number for pagination (default: 1)
85
88
  * @param {number} [params.limit] - The number of items per page for pagination (default: 20)
86
89
  * @param {RequestOptions} [params.options] - Additional options for the request
@@ -103,8 +106,8 @@ export class Numbers {
103
106
  * or GET /campaign/health.
104
107
  * @returns {Promise<SdkResponse<any>>} A promise that resolves to the list of phone numbers
105
108
  */
106
- async getPhoneNumbers({ phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, page, limit, options = {} }) {
107
- const filters = { phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, page, limit };
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 };
108
111
  const queryString = this.client._getQueryString(filters);
109
112
  return this.client(`/number${queryString}`, { method: 'GET', ...options });
110
113
  }
@@ -261,14 +264,18 @@ export class Numbers {
261
264
  * @roles api, admin, developer, billing, user
262
265
  * @param {Object} params - The parameters for reading the order status
263
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.
264
270
  * @param {RequestOptions} [params.options] - Additional options for the request
265
271
  * @throws {Error} Throws an error if the orderId parameter is missing
266
272
  * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ orderId, counts: { ready, provisioning, failed }, failures: [{ reason }], numbers: string[] }`.
267
273
  */
268
- async getTollFreeOrderStatus({ orderId, options = {} }) {
274
+ async getTollFreeOrderStatus({ orderId, groupId, options = {} }) {
269
275
  this.client._require({ orderId });
270
276
  const safeOrderId = encodeURIComponent(orderId);
271
- return this.client(`/number/toll-free/order/${safeOrderId}`, { method: 'GET', ...options });
277
+ const queryString = this.client._getQueryString({ groupId });
278
+ return this.client(`/number/toll-free/order/${safeOrderId}${queryString}`, { method: 'GET', ...options });
272
279
  }
273
280
 
274
281
  /**
@@ -298,6 +305,60 @@ export class Numbers {
298
305
  });
299
306
  }
300
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
+
301
362
  /**
302
363
  * Submit a port-in request for one or more phone numbers from another provider
303
364
  * @async
@@ -320,7 +381,7 @@ export class Numbers {
320
381
  * @param {Object} [params] - The parameters for filtering port-in requests
321
382
  * @param {string} [params.groupId] - Filter by group ID
322
383
  * @param {string} [params.phoneNumber] - Filter by phone number
323
- * @param {string} [params.status] - Filter by status (PENDING, IN_PROGRESS, COMPLETED, REJECTED, CANCELLED)
384
+ * @param {string} [params.status] - Filter by status (PENDING, IN_PROGRESS, ON_HOLD, REJECTED, SUCCESS)
324
385
  * @param {number} [params.page] - The page number for pagination (default: 1)
325
386
  * @param {number} [params.limit] - The number of items per page (default: 20)
326
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.
@@ -371,7 +432,9 @@ export class Numbers {
371
432
  * Numbers that are not found, already RELEASED, currently being released (transient PENDING_RELEASE
372
433
  * status), already assigned to a different campaign, on a mismatched DCA, or (for a 10DLC campaign
373
434
  * without a number pool) beyond the remaining 49-number-per-campaign limit are not queued - each is
374
- * reported back individually in `skipped` instead of failing the whole request.
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.
375
438
  * @async
376
439
  * @roles api, admin, developer, billing, user
377
440
  * @param {Object} params - The parameters for assigning phone numbers to a campaign
@@ -40,6 +40,24 @@ export class Onboarding {
40
40
  return this.client(`/group/onboarding/${safeGroupId}`, { method: "GET", ...options });
41
41
  },
42
42
 
43
+ /**
44
+ * Set where a group's new toll-free brands and numbers go (`infobip` or `twilio`). Staff-only. Existing brands,
45
+ * numbers and campaigns stay where they are.
46
+ * @async
47
+ * @roles signalhouse
48
+ * @param {Object} params
49
+ * @param {string} params.groupId - The group ID whose toll-free provider to set
50
+ * @param {string} params.tollFreeProvider - The toll-free provider for the group's new toll-free brands and numbers ("infobip" or "twilio")
51
+ * @param {RequestOptions} [params.options] - Additional options for the request
52
+ * @throws {Error} Throws an error if the groupId or tollFreeProvider parameter is missing
53
+ * @returns {Promise<SdkResponse<any>>} - The updated onboarding record
54
+ */
55
+ setTollFreeProvider: async ({ groupId, tollFreeProvider, options = {} }) => {
56
+ this.client._require({ groupId, tollFreeProvider });
57
+ const safeGroupId = encodeURIComponent(groupId);
58
+ return this.client(`/group/onboarding/${safeGroupId}/toll-free-provider`, { method: "PUT", body: { tollFreeProvider }, ...options });
59
+ },
60
+
43
61
  /**
44
62
  * Add an internal comment/note to a group's admin Pricing editor. Staff-only.
45
63
  * @async
@@ -40,6 +40,8 @@
40
40
  * @property {string} [status] - The status of the subgroup (e.g., "active", "inactive")
41
41
  * @property {string} [carrierIdFamily] - Optional agency-managed carrier ID selection ("Default", "ATT", "TMobile", "Verizon", "USCellular", "GoogleVoice", "ClearSky", "Interop"). Setting this field requires signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, or billing role.
42
42
  * @property {string|null} [carrierIdRegion] - Optional ClearSky region ("PRClaro", "GuamDocomo", "GuamGTA", "GuamITE") or null; only valid when carrierIdFamily is "ClearSky". Setting this field requires signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, or billing role.
43
+ * @property {boolean} [cnamAutoApply] - Turn caller name (CNAM) auto-apply on or off: eligible numbers get their brand's registered name as the name shown on outbound calls. Requires signalhouse_api, signalhouse_admin, signalhouse_user, api, admin or developer role.
44
+ * @property {string|null} [cnamBrandId] - Default caller-ID brand for numbers with no campaign (e.g. voice-only). Must be a verified brand in this subgroup; required when turning auto-apply on in a subgroup with more than one verified brand.
43
45
  */
44
46
 
45
47
  export class Subgroups {
@@ -75,12 +75,13 @@ export class Subscriptions {
75
75
  },
76
76
 
77
77
  /**
78
- * Create a custom subscription for a group with the provided subscription data
78
+ * Create a custom subscription for a group with the provided subscription data.
79
+ * Optional volumeTiers, rampDays, and monthlyMinimumSmsSegments enable graduated SMS rates and a monthly minimum that ramps up linearly over rampDays.
79
80
  * @async
80
81
  * @roles signalhouse
81
82
  * @param {Object} params - The parameters for creating a custom subscription
82
83
  * @param {string} params.groupId - The ID of the group to create the custom subscription for
83
- * @param {Object} params.subscriptionData - The data for the custom subscription, including required fields such as subscriptionName and monthlyFee
84
+ * @param {Object} params.subscriptionData - The data for the custom subscription, including required fields such as name and monthlyFee
84
85
  * @param {RequestOptions} [params.options] - Additional options for the request
85
86
  * @throws {Error} Throws an error if the groupId or subscriptionData parameter is missing or if required fields within subscriptionData are missing
86
87
  * @returns {Promise<SdkResponse<any>>} - The created custom subscription object returned from the server
@@ -90,6 +91,23 @@ export class Subscriptions {
90
91
  const safeGroupId = encodeURIComponent(groupId);
91
92
  return this.client(`/subscription/user/custom/${safeGroupId}`, { method: "POST", body: subscriptionData, ...options });
92
93
  },
94
+
95
+ /**
96
+ * Update volume tiers, ramp, and monthly minimum on an active custom subscription
97
+ * @async
98
+ * @roles signalhouse
99
+ * @param {Object} params - The parameters for updating the custom subscription
100
+ * @param {string} params.groupId - The ID of the group whose custom subscription to update
101
+ * @param {Object} params.updateData - Fields to change (name, description, monthlyFee, volumeTiers, monthlyMinimumSmsSegments, rampDays)
102
+ * @param {RequestOptions} [params.options] - Additional options for the request
103
+ * @throws {Error} Throws an error if the groupId or updateData parameter is missing
104
+ * @returns {Promise<SdkResponse<any>>} - The updated custom subscription object returned from the server
105
+ */
106
+ updateCustomSubscription: async ({ groupId, updateData, options = {} }) => {
107
+ this.client._require({ groupId, updateData });
108
+ const safeGroupId = encodeURIComponent(groupId);
109
+ return this.client(`/subscription/user/custom/${safeGroupId}`, { method: "PUT", body: updateData, ...options });
110
+ },
93
111
  };
94
112
  }
95
113
  }
@@ -43,6 +43,10 @@ export class Webhooks {
43
43
  * `verifyWebhookSignature` from `@signalhousellc/sdk/webhooks` (Node only). `webhookData.authType` is one of
44
44
  * `NONE` (default), `BASIC`, `API_KEY`, `OAUTH2` or `HMAC`; `HMAC` (SHGHL-3595) sends no credentials, so the
45
45
  * receiver authenticates by the signature alone, and must be sent without `credentials` or `apiHeaderPrefix`.
46
+ * `webhookData.eventSettings` (SHGHL-3884) holds per-event options keyed by event name:
47
+ * `NUMBER_HEALTH_BELOW_THRESHOLD` and `CAMPAIGN_HEALTH_BELOW_THRESHOLD` each take `{ threshold }`, the 7-day
48
+ * health score (1.5–10, in 0.5 steps) below which the event fires; a subscribed health event without one is
49
+ * stored with the default, 6.
46
50
  * @async
47
51
  * @roles api, admin, developer
48
52
  * @param {Object} params - The parameters for creating a webhook
@@ -62,7 +66,9 @@ export class Webhooks {
62
66
  * to change the endpoint's own credentials in place: credentials are required when switching to an auth
63
67
  * type that needs them, and omitted credentials keep the stored ones. Switching to `NONE` or `HMAC` clears
64
68
  * the stored credentials; `HMAC` is rejected for an endpoint with no signing secret (call
65
- * `rotateWebhookSecret` first). Like every read of a webhook, the
69
+ * `rotateWebhookSecret` first). `updateData.eventSettings` changes per-event options by event name
70
+ * (`{ NUMBER_HEALTH_BELOW_THRESHOLD: { threshold } }`, `{ CAMPAIGN_HEALTH_BELOW_THRESHOLD: { threshold } }`,
71
+ * 1.5–10 in 0.5 steps); events you omit keep their stored settings. Like every read of a webhook, the
66
72
  * response carries `hasSigningSecret` and `hasCredentials` (booleans), never a secret or credential.
67
73
  * @async
68
74
  * @roles api, admin, developer