@signalhousellc/sdk 1.5.0 → 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.5.0",
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
@@ -103,6 +103,16 @@
103
103
  * @property {string} representative.jobLevel - The representative's job level (required, one of DIRECTOR, GM, VP, CEO, CFO, GENERAL_COUNSEL, OTHER)
104
104
  */
105
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
+
106
116
  /**
107
117
  * @typedef {Object} CreateTollFreeBrandData
108
118
  * @property {string} subgroupId - The ID of the subgroup to create the brand under (required, exactly 8 characters)
@@ -177,7 +187,7 @@ export class Brands {
177
187
  * @param {boolean} [params.excludeDeleted] - Staff-only: hide DELETED brands when no status is given
178
188
  * @param {boolean} [params.includeTotal] - Staff-only: with page and limit, return `{ data, total, page, limit, totalPages }` instead of the array
179
189
  * @param {RequestOptions} [params.options] - Additional options for the request
180
- * @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 group's business verification). 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.
181
191
  */
182
192
  async getBrands({
183
193
  id,
@@ -276,34 +286,82 @@ export class Brands {
276
286
 
277
287
  /**
278
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.
279
291
  * @async
280
292
  * @roles api, admin, developer, billing, user
281
293
  * @param {Object} params - The parameters for getting the business verification
282
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
283
296
  * @param {RequestOptions} [params.options] - Additional options for the request
284
297
  * @throws {Error} Throws an error if the groupId parameter is missing
285
- * @returns {Promise<SdkResponse<{ groupId: string, required: boolean, status: string, details: BusinessVerificationDetails|null, submittedAt: string|null, reviewedAt: string|null, rejectionReason: string|null }>>} The group's business verification. `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 group's first toll-free brand.
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.
286
299
  */
287
- async getBusinessVerification({ groupId, options = {} }) {
300
+ async getBusinessVerification({ groupId, subgroupId, options = {} }) {
288
301
  this.client._require({ groupId });
289
- return this.client(`/brand/business-verification/${encodeURIComponent(groupId)}`, { method: 'GET', ...options });
302
+ const queryString = this.client._getQueryString({ subgroupId });
303
+ return this.client(`/brand/business-verification/${encodeURIComponent(groupId)}${queryString}`, { method: 'GET', ...options });
290
304
  }
291
305
 
292
306
  /**
293
- * Submit or update a group's business verification. Allowed when it is not started or needs changes. Review usually
294
- * takes 1–2 business days; the group's toll-free brands stay pending until it is verified.
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.
295
310
  * @async
296
311
  * @roles api, admin, developer, billing, user
297
312
  * @param {Object} params - The parameters for submitting the business verification
298
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
299
315
  * @param {BusinessVerificationDetails} params.details - The business verification details (see BusinessVerificationDetails typedef for details)
300
316
  * @param {RequestOptions} [params.options] - Additional options for the request
301
317
  * @throws {Error} Throws an error if the groupId or details parameter is missing
302
- * @returns {Promise<SdkResponse<{ groupId: string, required: boolean, status: string, details: BusinessVerificationDetails|null, submittedAt: string|null, reviewedAt: string|null, rejectionReason: string|null }>>} A 202 with the group's business verification, now SUBMITTING (the same shape as getBusinessVerification).
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.
303
319
  */
304
- async submitBusinessVerification({ groupId, details, options = {} }) {
320
+ async submitBusinessVerification({ groupId, subgroupId, details, options = {} }) {
305
321
  this.client._require({ groupId, details });
306
- return this.client(`/brand/business-verification/${encodeURIComponent(groupId)}`, { method: 'PUT', body: details, ...options });
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
+ });
307
365
  }
308
366
 
309
367
  /**
@@ -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
  },
@@ -379,7 +381,7 @@ export class Numbers {
379
381
  * @param {Object} [params] - The parameters for filtering port-in requests
380
382
  * @param {string} [params.groupId] - Filter by group ID
381
383
  * @param {string} [params.phoneNumber] - Filter by phone number
382
- * @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)
383
385
  * @param {number} [params.page] - The page number for pagination (default: 1)
384
386
  * @param {number} [params.limit] - The number of items per page (default: 20)
385
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.
@@ -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
  }