@signalhousellc/sdk 1.0.51 → 1.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalhousellc/sdk",
-  "version": "1.0.51",
+  "version": "1.0.52",
   "description": "Signal House SDK for use with the Signal House platform",
   "type": "module",
   "main": "src/SignalHouseSDK.js",

package/src/domains/Brands.js

@@ -53,6 +53,42 @@
  * @property {string} [altBusinessIdType] - The type of the alternative business identifier ("NONE", "DUNS", "LEI", "GIIN")
  * @property {string} [brandRelationship] - Not in use - reserved for future use
  * @property {string} [businessContactEmail] - The email address of the business contact for the brand (required if entityType is PUBLIC_PROFIT or NON_PROFIT)
+ * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free brand. Optional sub-fields: legalEntityType, businessRegistrationType, taxId, countryCode, supportPhone, taxIdIssuingCountry, businessDBA. (Toll-Free brands sync to Infobip; only DCA_PENDING/DCA_ACTIVE brands are editable and subgroupId is immutable.)
+ */
+
+/**
+ * @typedef {Object} TollFreeBrandDetails
+ * @property {string} businessRegistrationType - 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)
+ * @property {string} legalEntityType - The legal entity type (required, one of PRIVATE_COMPANY, PUBLIC_COMPANY, NON_PROFIT, GOVERNMENT, SOLE_PROPRIETOR)
+ * @property {string} taxId - The business tax identifier (required, at most 50 characters)
+ * @property {string} countryCode - The business country code (required, 2-letter ISO code)
+ * @property {string} supportPhone - The customer-support phone number (required, at most 20 characters)
+ * @property {string} [taxIdIssuingCountry] - The country that issued the tax ID (optional, 2-letter ISO code)
+ * @property {string} [businessDBA] - The business "doing business as" name (optional, at most 255 characters)
+ */
+
+/**
+ * @typedef {Object} CreateTollFreeBrandData
+ * @property {string} subgroupId - The ID of the subgroup to create the brand under (required, exactly 8 characters)
+ * @property {string} displayName - The display name for the brand (required, at most 255 characters)
+ * @property {string} companyName - The company name for the brand (required, at most 255 characters)
+ * @property {string} street - The street address of the primary contact for the brand (required, at most 255 characters)
+ * @property {string} city - The city of the primary contact for the brand (required, at most 100 characters)
+ * @property {string} state - The state of the primary contact for the brand (required, at most 20 characters; must be a valid 2-letter US state code when country is "US")
+ * @property {string} postalCode - The postal code of the primary contact for the brand (required, at most 10 characters)
+ * @property {string} email - The email address of the primary contact for the brand (required, valid email, at most 100 characters)
+ * @property {string} firstName - The first name of the primary contact for the brand (required, at most 100 characters)
+ * @property {string} lastName - The last name of the primary contact for the brand (required, at most 100 characters)
+ * @property {string} website - The website URL for the brand (required, valid URL, at most 255 characters)
+ * @property {TollFreeBrandDetails} tollFree - The Toll-Free brand details (required)
+ * @property {string} [referenceId] - A unique reference for the brand (optional, at most 50 characters)
+ * @property {Array<string>} [tag] - An array of tags to associate with the brand (optional)
+ * @property {boolean} [mock] - Whether to create the brand in the mock environment (for testing purposes only)
+ * @property {string} [optInLink] - A URL linking to the opt-in flow for the brand (optional, valid URL, at most 255 characters)
+ * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy for the brand (optional, valid URL, at most 255 characters)
+ * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions for the brand (optional, valid URL, at most 255 characters)
+ * @property {string} [landingId] - The ID of the landing page associated with the brand (optional)
+ * @property {string} [country] - The country code of the primary contact for the brand (optional, 2-letter code; when "US", state must be a valid 2-letter US state code)
  */
 
 export class Brands {
@@ -73,11 +109,12 @@ export class Brands {
 	 * @param {number} [params.page] - The page number for pagination
 	 * @param {number} [params.limit] - The number of items per page
 	 * @param {string} [params.status] - The status of the brand to filter by (PENDING_CREATION, PENDING_APPROVAL, UNVERIFIED, VERIFIED, VETTED_VERIFIED, PENDING_DELETE, DELETED)
+	 * @param {string} [params.registrationType] - Filter by registration type ("TEN_DLC" or "TOLL_FREE")
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Array>} The response from the server
 	 */
-	async getBrands({ id, subgroupId, groupId, page, limit, status, options = {} }) {
-		const filters = { id, subgroupId, groupId, page, limit, status };
+	async getBrands({ id, subgroupId, groupId, page, limit, status, registrationType, options = {} }) {
+		const filters = { id, subgroupId, groupId, page, limit, status, registrationType };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/brand${queryString}`, { method: "GET", ...options });
 	}
@@ -113,6 +150,21 @@ export class Brands {
 		return this.client(`/brand`, { method: "POST", body: brandData, ...options });
 	}
 
+	/**
+	 * Create a new Toll-Free (TFN) brand
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for creating the toll-free brand
+	 * @param {CreateTollFreeBrandData} params.brandData - The data for the toll-free brand to be created (see CreateTollFreeBrandData typedef for details; TFN-specific fields live under brandData.tollFree, and registrationType is forced server-side by the route)
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the brandData parameter is missing
+	 * @returns {Promise<Object>} The response from the server
+	 */
+	async createTollFreeBrand({ brandData, options = {} }) {
+		this.client._require({ brandData });
+		return this.client(`/brand/toll-free`, { method: "POST", body: brandData, ...options });
+	}
+
 	/**
 	 * Transfer one or more brands to a different subgroup
 	 * @async

package/src/domains/Campaigns.js

@@ -64,6 +64,41 @@
  * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy for the campaign (optional, must be at most 2048 characters if provided)
  * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions for the campaign (optional, must be at most 2048 characters if provided)
  * @property {string} [embeddedLinkSample] - A sample of the embedded link used in the campaign (optional, must be at most 255 characters if provided)
+ * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free campaign. Mirrors the CreateTollFreeCampaignData `tollFree` object with every field optional (useCase, messageVolume, programSummary (≤500), exampleMessage, customerCareEmail, optInImageURLs, optIns, additionalInformation (≤500)). Phone numbers cannot be changed via update — Toll-Free numbers are locked to their campaign.
+ */
+
+/**
+ * @typedef {Object} TollFreeOptIn
+ * @property {string} [callToAction] - The opt-in call-to-action text for this channel (optional, at most 2048 characters)
+ * @property {string} [url] - The opt-in web URL (web channel only, optional, at most 2048 characters)
+ * @property {Array<string>} [keywords] - The opt-in keywords (keyword channel only, optional)
+ */
+
+/**
+ * @typedef {Object} TollFreeCampaignDetails
+ * @property {string} useCase - The Toll-Free use case (required, e.g. TWO_FA, GENERAL_MARKETING, HEALTHCARE, MIXED — one of the Toll-Free use-case values)
+ * @property {string} messageVolume - The estimated monthly message volume tier (required, one of TEN, HUNDRED, THOUSAND, TEN_THOUSAND, HUNDRED_THOUSAND, TWO_HUNDRED_FIFTY_THOUSAND, FIVE_HUNDRED_THOUSAND, SEVEN_HUNDRED_FIFTY_THOUSAND, ONE_MILLION, FIVE_MILLION, TEN_MILLION_PLUS)
+ * @property {string} programSummary - A summary of the messaging program (required, at most 500 characters)
+ * @property {string} exampleMessage - An example message (required, at most 4096 characters; stored verbatim, no STOP/HELP appended by the server)
+ * @property {string} customerCareEmail - A customer-care contact email (required, valid email)
+ * @property {Array<string>} optInImageURLs - URLs to opt-in proof images (required, at least one, each at most 2048 characters)
+ * @property {Object} [optIns] - Opt-in method details. Each channel is optional.
+ * @property {TollFreeOptIn} [optIns.verbal] - Verbal opt-in details
+ * @property {TollFreeOptIn} [optIns.web] - Online (web) opt-in details
+ * @property {TollFreeOptIn} [optIns.keyword] - Keyword opt-in details
+ * @property {TollFreeOptIn} [optIns.interactiveVoiceResponse] - IVR opt-in details
+ * @property {string} [additionalInformation] - Free-text justification sent upstream to the carrier (optional, at most 500 characters). Required when more than one phone number is assigned to the campaign.
+ */
+
+/**
+ * @typedef {Object} CreateTollFreeCampaignData
+ * @property {string} brandId - The ID of the Toll-Free brand associated with the campaign (required, at least 7 characters)
+ * @property {TollFreeCampaignDetails} tollFree - The Toll-Free campaign details (required)
+ * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy (optional, at most 2048 characters)
+ * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions (optional, at most 2048 characters)
+ * @property {string} [tag] - A tag for the campaign (optional, at most 255 characters)
+ * @property {boolean} [autoRenewal=true] - Whether the campaign should auto-renew (optional, defaults to true)
+ * @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.
  */
 
 export class Campaigns {
@@ -133,11 +168,12 @@ export class Campaigns {
 	 * @param {string} [params.search] - Search term to filter campaigns by campaignId or brandId
 	 * @param {string} [params.sortBy] - Field to sort by (e.g. "createdAt", "campaignId", "brandId", "groupId", "subgroupId", "usecase", "status")
 	 * @param {string} [params.sortOrder] - Sort direction ("asc" or "desc")
+	 * @param {string} [params.registrationType] - Filter by registration type ("TEN_DLC" or "TOLL_FREE")
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Array|Object>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
 	 */
-	async getCampaigns({ id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder, options = {} }) {
-		const filters = { id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder };
+	async getCampaigns({ id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder, registrationType, options = {} }) {
+		const filters = { id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder, registrationType };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/campaign${queryString}`, { method: "GET", ...options });
 	}
@@ -157,6 +193,21 @@ export class Campaigns {
 		return this.client(`/campaign`, { method: "POST", body: campaignData, ...options });
 	}
 
+	/**
+	 * Create a new Toll-Free (TFN) campaign and submit it for Signal House review
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for creating the toll-free campaign
+	 * @param {CreateTollFreeCampaignData} params.campaignData - The data for the toll-free campaign to be created (see CreateTollFreeCampaignData typedef for details)
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the campaignData parameter is missing
+	 * @returns {Promise<Object>} The response from the server
+	 */
+	async createTollFreeCampaign({ campaignData, options = {} }) {
+		this.client._require({ campaignData });
+		return this.client(`/campaign/toll-free`, { method: "POST", body: campaignData, ...options });
+	}
+
 	/**
 	 * Update an existing campaign
 	 * @async

package/src/domains/Numbers.js

@@ -111,6 +111,25 @@ export class Numbers {
 		return this.client(`/number`, { method: "POST", body: { phoneNumbers, subgroupId }, ...options });
 	}
 
+	/**
+	 * Purchase one or more Toll-Free numbers via the asynchronous resource-request flow.
+	 *
+	 * Toll-Free numbers are ordered by quantity (not picked individually) and provisioned asynchronously;
+	 * per-number completion is delivered via webhook/polling, not in this response.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for purchasing toll-free numbers
+	 * @param {number} params.quantity - The number of toll-free numbers to purchase (1-10)
+	 * @param {string} params.subgroupId - The subgroup the purchased numbers are assigned to
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the quantity or subgroupId parameter is missing
+	 * @returns {Promise<Object>} A promise that resolves to `{ message }` once the request is queued.
+	 */
+	async purchaseTollFreeNumbers({ quantity, subgroupId, options = {} }) {
+		this.client._require({ quantity, subgroupId });
+		return this.client(`/number/toll-free`, { method: "POST", body: { quantity, subgroupId }, ...options });
+	}
+
 	/**
 	 * Update an existing phone number's details (e.g., setting a friendly name)
 	 * @async