@signalhousellc/sdk 1.5.1 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +5 -56
  2. package/index.d.ts +1 -0
  3. package/index.js +2 -0
  4. package/package.json +32 -34
  5. package/voice-browser.d.ts +1 -0
  6. package/voice-browser.js +2 -0
  7. package/warn.js +7 -0
  8. package/webhooks.d.ts +1 -0
  9. package/webhooks.js +2 -0
  10. package/scripts/install-skills.mjs +0 -329
  11. package/skills/VENDORED.json +0 -22
  12. package/skills/signalhouse-10dlc/SKILL.md +0 -172
  13. package/skills/signalhouse-10dlc/examples/brightsmile-onboarding.md +0 -62
  14. package/skills/signalhouse-10dlc/references/tcr-rejection-causes.md +0 -104
  15. package/skills/signalhouse-advisor/SKILL.md +0 -84
  16. package/skills/signalhouse-numbers/SKILL.md +0 -82
  17. package/skills/signalhouse-setup/SKILL.md +0 -121
  18. package/skills/signalhouse-sms/SKILL.md +0 -81
  19. package/skills/signalhouse-webhooks/SKILL.md +0 -148
  20. package/src/SignalHouseSDK.js +0 -201
  21. package/src/domains/Agents.js +0 -987
  22. package/src/domains/Auth.js +0 -225
  23. package/src/domains/Billing.js +0 -265
  24. package/src/domains/Brands.js +0 -566
  25. package/src/domains/Campaigns.js +0 -691
  26. package/src/domains/Dnc.js +0 -168
  27. package/src/domains/Groups.js +0 -187
  28. package/src/domains/Landings.js +0 -237
  29. package/src/domains/Messages.js +0 -609
  30. package/src/domains/Notifications.js +0 -62
  31. package/src/domains/Numbers.js +0 -574
  32. package/src/domains/Onboarding.js +0 -128
  33. package/src/domains/Registrations.js +0 -246
  34. package/src/domains/Shortlinks.js +0 -80
  35. package/src/domains/Subgroups.js +0 -136
  36. package/src/domains/Subscriptions.js +0 -164
  37. package/src/domains/Templates.js +0 -403
  38. package/src/domains/Tickets.js +0 -100
  39. package/src/domains/Users.js +0 -228
  40. package/src/domains/Voice.js +0 -41
  41. package/src/domains/Webhooks.js +0 -125
  42. package/src/domains/voice/Analytics.js +0 -82
  43. package/src/domains/voice/CallLogs.js +0 -111
  44. package/src/domains/voice/Calls.js +0 -118
  45. package/src/domains/voice/GlobalVoiceSettings.js +0 -54
  46. package/src/domains/voice/NumberRoutes.js +0 -82
  47. package/src/domains/voice/ProgrammableVoiceProfiles.js +0 -191
  48. package/src/domains/voice/SipProfiles.js +0 -203
  49. package/src/domains/voice/SipTrunks.js +0 -203
  50. package/src/domains/voice/Tokens.js +0 -96
  51. package/src/domains/voice/browser/Call.js +0 -366
  52. package/src/domains/voice/browser/Device.js +0 -484
  53. package/src/domains/voice/browser/index.js +0 -17
  54. package/src/webhooks/verifySignature.js +0 -66
@@ -1,168 +0,0 @@
1
- /** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
2
- /**
3
- * @template T
4
- * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
5
- */
6
-
7
- /**
8
- * Do Not Contact domain: the attested "Disable Automated Opt-Out" account setting. Signal House
9
- * suppresses sends to recipients who opted out of the sending campaign by default; an account may
10
- * disable that only by having an officer read and e-sign the Opt-Out Handling Attestation inside a
11
- * Signal House app: the portal (a customer login signs for its own account) or one of our apps running
12
- * as signalhouse_api (GHL, Shopify), which signs for the account it names on behalf of the customer user
13
- * it authenticated. Every method therefore lives under the admin namespace (present only when the SDK is
14
- * created with `enableAdmin: true`), and the API refuses the customer "api" (API key) role on the signing
15
- * routes, so attestation can never be performed by a third-party integration.
16
- */
17
- export class Dnc {
18
- constructor(client, enableAdmin) {
19
- this.client = client;
20
- this.enableAdmin = enableAdmin;
21
-
22
- // Hidden Admin namespace INSIDE the domain
23
- if (enableAdmin) {
24
- this.admin = {
25
- /**
26
- * Get the current Opt-Out Handling Attestation text for the session's account with every placeholder
27
- * filled (account values, the session's email and role, blanks in the signature block for what only
28
- * signing supplies), plus the version and template hash a signature must echo back. The app must
29
- * render this text; it never ships its own copy.
30
- * @async
31
- * @roles admin, developer, billing (portal logins); signalhouse_* with groupId
32
- * @param {Object} [params] - Optional parameters
33
- * @param {string} [params.groupId] - Group to render for (apps and staff; customers always get their active group)
34
- * @param {RequestOptions} [params.options] - Additional options for the request
35
- * @returns {Promise<SdkResponse<any>>} - `{ version, templateSha256, text, checkboxText, groupId, accountName, customerLegalName }`
36
- */
37
- getCurrentAttestation: async ({ groupId, options = {} } = {}) => {
38
- const queryString = this.client._getQueryString({ groupId });
39
- return this.client(`/dnc/attestation/current${queryString}`, { method: "GET", ...options });
40
- },
41
-
42
- /**
43
- * Sign the attestation and disable automated opt-out suppression for the account and every subgroup,
44
- * effective within about a minute on every API instance. Two callers: a portal login signs for its own
45
- * account and the signer identity is taken from the session; a Signal House app running as
46
- * signalhouse_api (GHL, Shopify) signs for the `groupId` it names and supplies the identity of the
47
- * customer user it authenticated (`signerEmail`, optional `signerUserId`, `signedVia`, and the end
48
- * user's `signerIpAddress` / `signerUserAgent`, which otherwise default to the app server's). Resolves
49
- * 201 when this call created the record and 200 with the existing record on a repeat or concurrent
50
- * call. A stale version or hash is refused with 409 and `details.code === "ATTESTATION_VERSION_MISMATCH"`;
51
- * an unchecked box or blank field with 400. Human staff roles and customer API-key sessions are refused.
52
- * @async
53
- * @roles admin, developer, billing (portal logins); signalhouse_api (apps, with groupId)
54
- * @param {Object} params
55
- * @param {string} params.version - The version returned by getCurrentAttestation
56
- * @param {string} params.templateSha256 - The template hash returned by getCurrentAttestation
57
- * @param {boolean} params.checkboxAcknowledged - Must be true
58
- * @param {boolean} params.scrolledToEnd - Must be true
59
- * @param {string} params.customerLegalName - Company legal name
60
- * @param {string} params.signerName - Signer's typed full legal name (the electronic signature)
61
- * @param {string} params.signerTitle - Signer's title
62
- * @param {string} [params.groupId] - App callers: the account being attested
63
- * @param {string} [params.signerEmail] - App callers (required): the signer's email as authenticated by the app
64
- * @param {string} [params.signerUserId] - App callers: the app's id for the signer
65
- * @param {string} [params.signedVia] - App callers: the app name, e.g. "ghl" or "shopify"
66
- * @param {string} [params.signerIpAddress] - App callers: the end user's IP address
67
- * @param {string} [params.signerUserAgent] - App callers: the end user's user agent
68
- * @param {RequestOptions} [params.options] - Additional options for the request
69
- * @throws {Error} Throws an error if a required parameter is missing
70
- * @returns {Promise<SdkResponse<any>>} - `{ attestation, created }`
71
- */
72
- signAttestation: async ({ version, templateSha256, checkboxAcknowledged, scrolledToEnd, customerLegalName, signerName, signerTitle, groupId, signerEmail, signerUserId, signedVia, signerIpAddress, signerUserAgent, options = {} }) => {
73
- this.client._require({ version, templateSha256, customerLegalName, signerName, signerTitle });
74
- const appFields = Object.fromEntries(Object.entries({ groupId, signerEmail, signerUserId, signedVia, signerIpAddress, signerUserAgent }).filter(([, value]) => value !== undefined));
75
- return this.client(`/dnc/attestation`, {
76
- method: "POST",
77
- body: { version, templateSha256, checkboxAcknowledged, scrolledToEnd, customerLegalName, signerName, signerTitle, ...appFields },
78
- ...options,
79
- });
80
- },
81
-
82
- /**
83
- * Revoke the active attestation and re-enable automated opt-out suppression, effective within about a
84
- * minute: a portal login for its own account, or an app (signalhouse_api) for the `groupId` it names.
85
- * The record is retained as "revoked". 404 when nothing is active.
86
- * @async
87
- * @roles admin, developer, billing (portal logins); signalhouse_api (apps, with groupId)
88
- * @param {Object} [params] - Optional parameters
89
- * @param {string} [params.groupId] - App callers: the account
90
- * @param {RequestOptions} [params.options] - Additional options for the request
91
- * @returns {Promise<SdkResponse<any>>} - `{ attestation }`
92
- */
93
- revokeAttestation: async ({ groupId, options = {} } = {}) => {
94
- return this.client(`/dnc/attestation/revoke`, { method: "POST", ...(groupId ? { body: { groupId } } : {}), ...options });
95
- },
96
-
97
- /**
98
- * Read an account's attestation state: whether automated opt-out is disabled, the active record
99
- * (full stored text included), the full history, and whether the active record predates the
100
- * current template and must be re-signed by `resignDeadline`.
101
- * @async
102
- * @roles admin, developer, billing (portal logins); signalhouse_* with groupId
103
- * @param {Object} [params] - Optional parameters
104
- * @param {string} [params.groupId] - Group to read (apps and staff; customers always get their active group)
105
- * @param {RequestOptions} [params.options] - Additional options for the request
106
- * @returns {Promise<SdkResponse<any>>} - `{ groupId, automatedOptOutDisabled, currentVersion, currentTemplateSha256, requiresResign, resignDeadline, active, history }`
107
- */
108
- getAttestation: async ({ groupId, options = {} } = {}) => {
109
- const queryString = this.client._getQueryString({ groupId });
110
- return this.client(`/dnc/attestation${queryString}`, { method: "GET", ...options });
111
- },
112
-
113
- /**
114
- * List opt-out attestations across every account, newest first, with each group's trailing
115
- * would-have-suppressed counts (7 and 30 days, recorded while attested) and 7-day opt-out count.
116
- * The full attestation text is omitted from list rows. Staff-only.
117
- * @async
118
- * @roles signalhouse
119
- * @param {Object} [params] - Optional parameters
120
- * @param {("active"|"revoked"|"superseded")} [params.status] - Filter by status
121
- * @param {string} [params.groupId] - Filter by group
122
- * @param {number} [params.page] - Page number (default 1)
123
- * @param {number} [params.limit] - Rows per page (default 50, max 500)
124
- * @param {RequestOptions} [params.options] - Additional options for the request
125
- * @returns {Promise<SdkResponse<any>>} - `{ rows, totalCount, page, limit }`
126
- */
127
- listAttestations: async ({ status, groupId, page, limit, options = {} } = {}) => {
128
- const queryString = this.client._getQueryString({ status, groupId, page, limit });
129
- return this.client(`/dnc/attestations${queryString}`, { method: "GET", ...options });
130
- },
131
-
132
- /**
133
- * Read one attestation with its stored text, hashes, signer identity, IP and user agent, plus
134
- * the group's full attestation history. Staff-only.
135
- * @async
136
- * @roles signalhouse
137
- * @param {Object} params
138
- * @param {string} params.id - The attestation id
139
- * @param {RequestOptions} [params.options] - Additional options for the request
140
- * @throws {Error} Throws an error if the id parameter is missing
141
- * @returns {Promise<SdkResponse<any>>} - `{ attestation, history }`
142
- */
143
- getAttestationById: async ({ id, options = {} }) => {
144
- this.client._require({ id });
145
- return this.client(`/dnc/attestations/${encodeURIComponent(id)}`, { method: "GET", ...options });
146
- },
147
-
148
- /**
149
- * Revoke an active attestation with a reason and re-enable automated opt-out for the account.
150
- * Emails the signer and account owner. There is no staff path that creates an attestation. Staff-only.
151
- * @async
152
- * @roles signalhouse
153
- * @param {Object} params
154
- * @param {string} params.id - The attestation id
155
- * @param {("carrier_complaint"|"regulator_inquiry"|"legal_request"|"excessive_opt_out_rate"|"customer_request"|"other")} params.reasonCode - Why it is being revoked
156
- * @param {string} params.reason - Free-text reason shown to the customer
157
- * @param {RequestOptions} [params.options] - Additional options for the request
158
- * @throws {Error} Throws an error if a required parameter is missing
159
- * @returns {Promise<SdkResponse<any>>} - `{ attestation }` (status "revoked", revokedByType "signalhouse_admin")
160
- */
161
- revokeAttestationById: async ({ id, reasonCode, reason, options = {} }) => {
162
- this.client._require({ id, reasonCode, reason });
163
- return this.client(`/dnc/attestations/${encodeURIComponent(id)}/revoke`, { method: "POST", body: { reasonCode, reason }, ...options });
164
- },
165
- };
166
- }
167
- }
168
- }
@@ -1,187 +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 Groups {
8
- constructor(client, enableAdmin) {
9
- this.client = client;
10
- this.enableAdmin = enableAdmin;
11
-
12
- // Hidden Admin namespace INSIDE the domain
13
- if (enableAdmin) {
14
- this.admin = {
15
- /**
16
- * Get resource counts grouped by group ID. Only signalhouse_admin can query all groups;
17
- * every other allowed role is restricted to its JWT group scope.
18
- * @async
19
- * @roles signalhouse, api, admin, developer, billing, user
20
- * @param {Object} [params] - Optional group-count filters and pagination.
21
- * @param {string} [params.groupId] - Restrict results to a group.
22
- * @param {number} [params.limit] - Maximum rows to return.
23
- * @param {number} [params.offset] - Rows to skip; requires limit.
24
- * @param {RequestOptions} [params.options] - Additional options for the request.
25
- * @returns {Promise<SdkResponse<any>>} - Group-level resource count rows.
26
- */
27
- getGroupCounts: async ({ groupId, limit, offset, options = {} } = {}) => {
28
- const queryString = this.client._getQueryString({ groupId, limit, offset });
29
- return this.client(`/group/counts${queryString}`, { method: "GET", ...options });
30
- },
31
-
32
- /**
33
- * Get a list of all groups with optional pagination parameters
34
- * @async
35
- * @roles signalhouse
36
- * @param {Object} params - The parameters for getting groups
37
- * @param {number} [params.page] - The page number for pagination
38
- * @param {number} [params.limit] - The number of items per page
39
- * @param {RequestOptions} [params.options] - Additional options for the request
40
- * @returns {Promise<SdkResponse<any>>} - The list of groups returned from the server
41
- */
42
- getGroups: async ({ page, limit, options = {} }) => {
43
- const filters = { page, limit };
44
- const queryString = this.client._getQueryString(filters);
45
- return this.client(`/group${queryString}`, { method: "GET", ...options });
46
- },
47
-
48
- /**
49
- * Create a new group with the specified group data
50
- * @async
51
- * @roles signalhouse
52
- * @param {Object} params - The parameters for creating a new group
53
- * @param {Object} params.groupData - The data for the new group, including required fields such as groupName. Optionally accepts `psPartnerKey` and `ownerEmail` to credit a referring partner.
54
- * @param {RequestOptions} [params.options] - Additional options for the request
55
- * @throws {Error} Throws an error if the groupData parameter is missing or if required fields within groupData are missing
56
- * @returns {Promise<SdkResponse<any>>} - The created group object returned from the server
57
- */
58
- createGroup: async ({ groupData, options = {} }) => {
59
- this.client._require({ groupData: groupData });
60
- return this.client(`/group`, { method: "POST", body: groupData, ...options });
61
- },
62
-
63
- /**
64
- * Record a GHL-app or Shopify-app install's registration for the per-surface
65
- * customer-lifecycle webhook system. Call this right after admin.createGroup when
66
- * provisioning a group outside the Portal's self-registration flow (which records
67
- * itself automatically) — without it, the group never fires a registration webhook and
68
- * is never eligible for the "registered but no brand submitted" staleness webhook.
69
- * Internal-only: not documented in the public API reference (deliberate exception, see
70
- * CLAUDE.md's API Change Propagation Rules — mirrors the /oauth exception).
71
- * @async
72
- * @roles signalhouse_api, signalhouse_admin
73
- * @param {Object} params - The parameters for recording a registration
74
- * @param {string} params.groupId - The just-provisioned group's ID
75
- * @param {string} params.registrationSource - Which surface provisioned this group ("ghl" or "shopify")
76
- * @param {string} [params.firstName] - The account owner's first name
77
- * @param {string} [params.fullName] - The account owner's full name
78
- * @param {string} [params.email] - The account owner's email
79
- * @param {string} [params.phone] - The account owner's phone number
80
- * @param {string} [params.estimatedVolume] - Estimated monthly message volume
81
- * @param {RequestOptions} [params.options] - Additional options for the request
82
- * @throws {Error} Throws an error if the groupId or registrationSource parameter is missing
83
- * @returns {Promise<SdkResponse<any>>} - `{ success: true }`
84
- */
85
- recordLifecycleRegistration: async ({ groupId, registrationSource, firstName, fullName, email, phone, estimatedVolume, options = {} }) => {
86
- this.client._require({ groupId, registrationSource });
87
- return this.client(`/group/lifecycle/registration`, {
88
- method: "POST",
89
- body: { groupId, registrationSource, firstName, fullName, email, phone, estimatedVolume },
90
- ...options,
91
- });
92
- },
93
-
94
- /**
95
- * Delete a group with the specified group ID
96
- * @async
97
- * @roles signalhouse
98
- * @param {Object} params - The parameters for deleting a group
99
- * @param {string} params.groupId - The ID of the group to delete
100
- * @param {RequestOptions} [params.options] - Additional options for the request
101
- * @throws {Error} Throws an error if the groupId parameter is missing
102
- * @returns {Promise<SdkResponse<any>>} - The deleted group object returned from the server
103
- */
104
- deleteGroup: async ({ groupId, options = {} }) => {
105
- this.client._require({ groupId });
106
- const safeGroupId = encodeURIComponent(groupId);
107
- return this.client(`/group/${safeGroupId}`, { method: "DELETE", ...options });
108
- },
109
-
110
- /**
111
- * Set a group's KYC complianceStatus (SHGHL-2740). Only flips the field — it does not
112
- * trigger any lockout side effects (halted sends, revoked API keys, etc.) for "rejected".
113
- * @async
114
- * @roles signalhouse
115
- * @param {Object} params - The parameters for updating a group's compliance status
116
- * @param {string} params.groupId - The ID of the group to update
117
- * @param {string} params.complianceStatus - One of "unverified", "pending", "verified", "rejected"
118
- * @param {RequestOptions} [params.options] - Additional options for the request
119
- * @throws {Error} Throws an error if the groupId or complianceStatus parameter is missing
120
- * @returns {Promise<SdkResponse<any>>} - The updated group object returned from the server
121
- */
122
- updateComplianceStatus: async ({ groupId, complianceStatus, options = {} }) => {
123
- this.client._require({ groupId, complianceStatus });
124
- const safeGroupId = encodeURIComponent(groupId);
125
- return this.client(`/group/${safeGroupId}/compliance-status`, { method: "PUT", body: { complianceStatus }, ...options });
126
- },
127
-
128
- /**
129
- * Link an external tenant (GHL/Shopify) to a V2 group (server-to-server). Exchanges a
130
- * single-use link token for a canonical group, adopting an empty portal group, repointing
131
- * to an existing group, or flagging for manual review.
132
- * @async
133
- * @roles signalhouse
134
- * @param {Object} params - The parameters for linking an external account
135
- * @param {string} params.linkToken - The single-use external-link token minted by the portal user
136
- * @param {string} params.externalSystem - The external system ("ghl" or "shopify")
137
- * @param {string} params.externalId - The external tenant identifier
138
- * @param {string} [params.existingGroupId] - An existing V2 group ID to repoint to, if any
139
- * @param {RequestOptions} [params.options] - Additional options for the request
140
- * @throws {Error} Throws an error if linkToken, externalSystem, or externalId is missing
141
- * @returns {Promise<SdkResponse<any>>} - The link outcome ({ status, canonicalGroupId, ... })
142
- */
143
- linkExternal: async ({ linkToken, externalSystem, externalId, existingGroupId, options = {} }) => {
144
- this.client._require({ linkToken, externalSystem, externalId });
145
- return this.client(`/group/link-external`, {
146
- method: "POST",
147
- body: { linkToken, externalSystem, externalId, ...(existingGroupId ? { existingGroupId } : {}) },
148
- ...options,
149
- });
150
- },
151
- };
152
- }
153
- }
154
-
155
- /**
156
- * Get details of a group by its ID
157
- * @async
158
- * @roles api, admin, developer, billing, user
159
- * @param {Object} params - The parameters for getting a group
160
- * @param {string} params.id - The ID of the group to retrieve
161
- * @param {RequestOptions} [params.options] - Additional options for the request
162
- * @returns {Promise<SdkResponse<any>>} - The group object returned from the server
163
- */
164
- async getGroup({ id, options = {} }) {
165
- const filters = { id };
166
- const queryString = this.client._getQueryString(filters);
167
- return this.client(`/group${queryString}`, { method: "GET", ...options });
168
- }
169
-
170
- /**
171
- * Update a group with the specified group data
172
- * @async
173
- * @roles api, admin, developer, billing
174
- * @param {Object} params - The parameters for updating a group
175
- * @param {string} params.id - The ID of the group to update
176
- * @param {Object} params.groupData - The data for the group, including required fields such as groupName.
177
- * Optional CNP fields: cspId (string|null), defaultCnpSubgroupId (string|null)
178
- * @param {RequestOptions} [params.options] - Additional options for the request
179
- * @throws {Error} Throws an error if the id or groupData parameter is missing
180
- * @returns {Promise<SdkResponse<any>>} - The updated group object returned from the server
181
- */
182
- async updateGroup({ id, groupData, options = {} }) {
183
- this.client._require({ id, groupData: groupData });
184
- const safeId = encodeURIComponent(id);
185
- return this.client(`/group/${safeId}`, { method: "PUT", body: groupData, ...options });
186
- }
187
- }
@@ -1,237 +0,0 @@
1
- /** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
2
- /**
3
- * @template T
4
- * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
5
- */
6
-
7
- /**
8
- * @typedef {Object} TollFreeConsentBox
9
- * @property {string} useCase - The use case the checkbox covers
10
- * @property {string} channel - The channel the checkbox covers ("SMS" or "MMS")
11
- * @property {string} text - The wording rendered beside the checkbox
12
- */
13
-
14
- /**
15
- * @typedef {Object} TollFreeLandingData
16
- * @property {string[]} useCases - The campaign's real use cases; one consent box is rendered per use case per channel
17
- * @property {string[]} channels - The channels consent covers ("SMS", "MMS", "VOICE")
18
- * @property {string} consentDisclosure - The shared disclosure rendered once above the consent boxes (max 1024 characters)
19
- * @property {TollFreeConsentBox[]} consentBoxes - The consent boxes the page renders (max 16; each text max 512 characters)
20
- */
21
-
22
- /**
23
- * @typedef {Object} CreateLandingData
24
- * @property {string} brandId - The ID of the brand to associate with the landing page
25
- * @property {string} description - A description of the landing page
26
- * @property {string} primaryBackgroundColor - The primary background color for the landing page (e.g., "#FFFFFF")
27
- * @property {string} secondaryBackgroundColor - The secondary background color for the landing page (e.g., "#F0F0F0")
28
- * @property {string} primaryTextColor - The primary text color for the landing page (e.g., "#000000")
29
- * @property {string} secondaryTextColor - The secondary text color for the landing page (e.g., "#333333")
30
- * @property {Buffer} logo - A logo image file for the landing page, provided as a Buffer
31
- * @property {string} [registrationType] - Which page type to build: "TEN_DLC" (default) or "TOLL_FREE"
32
- * @property {TollFreeLandingData} [tollFree] - Toll-Free consent content; required when registrationType is "TOLL_FREE"
33
- * @property {boolean} [useBrandTemplate] - Toll-Free only. Build the page from the brand's landing page template,
34
- * taking its colors, logo and webhook URL from there. When set, no logo file is required. `description` is
35
- * still sent by the caller, since the About paragraph names the services this campaign's use cases cover.
36
- */
37
-
38
- /**
39
- * @typedef {Object} UpdateLandingData
40
- * @property {string} [description] - A description of the landing page
41
- * @property {string} [primaryBackgroundColor] - The primary background color for the landing page (e.g., "#FFFFFF")
42
- * @property {string} [secondaryBackgroundColor] - The secondary background color for the landing page (e.g., "#F0F0F0")
43
- * @property {string} [primaryTextColor] - The primary text color for the landing page (e.g., "#000000")
44
- * @property {string} [secondaryTextColor] - The secondary text color for the landing page (e.g., "#333333")
45
- * @property {Buffer} [logo] - A logo image file for the landing page, provided as a Buffer
46
- * @property {string} [registrationType] - Which page type to build: "TEN_DLC" or "TOLL_FREE"
47
- * @property {TollFreeLandingData} [tollFree] - Replaces the whole Toll-Free consent subdocument when set
48
- * @property {boolean} [useBrandTemplate] - Toll-Free only. Re-copy the brand's landing page template into this
49
- * page, so a corrected logo or color reaches a page that already exists instead of creating a second one.
50
- */
51
-
52
- /**
53
- * @typedef {Object} LandingTemplateData
54
- * @property {string} userDescription - The customer's own sentence about their business. Not the finished About
55
- * paragraph: the services clause is added per campaign when a page is generated
56
- * @property {string} [primaryBackgroundColor] - The primary background color (e.g., "#FFFFFF")
57
- * @property {string} [secondaryBackgroundColor] - The secondary background color (e.g., "#F0F0F0")
58
- * @property {string} [primaryTextColor] - The primary text color (e.g., "#000000")
59
- * @property {string} [secondaryTextColor] - The secondary text color (e.g., "#333333")
60
- * @property {string} [webhookUrl] - Where generated pages post opt-in submissions
61
- */
62
-
63
- export class Landings {
64
- constructor(client, multipartClient, enableAdmin) {
65
- this.client = client;
66
- this.multipartClient = multipartClient;
67
- this.enableAdmin = enableAdmin;
68
- }
69
-
70
- /**
71
- * Get details of a landing page by its ID
72
- * @async
73
- * @roles api, admin, developer, billing, user
74
- * @param {Object} params - The parameters for getting a landing page
75
- * @param {string} params.landingId - The ID of the landing page to retrieve
76
- * @param {RequestOptions} [params.options] - Additional options for the request
77
- * @throws {Error} Throws an error if the landingId parameter is missing
78
- * @returns {Promise<SdkResponse<any>>} - The landing page object returned from the server
79
- */
80
- async getLandings({ landingId, options = {} }) {
81
- this.client._require({ landingId });
82
- const safeLandingId = encodeURIComponent(landingId);
83
- return this.client(`/landing/${safeLandingId}`, { method: "GET", ...options });
84
- }
85
-
86
- /**
87
- * Get a public (published) landing page by its ID. This endpoint is public and does not require authentication.
88
- * @async
89
- * @param {Object} params - The parameters for getting a public landing page
90
- * @param {string} params.landingId - The ID of the public landing page to retrieve
91
- * @param {RequestOptions} [params.options] - Additional options for the request
92
- * @throws {Error} Throws an error if the landingId parameter is missing
93
- * @returns {Promise<SdkResponse<any>>} - The public landing page object returned from the server
94
- */
95
- async getPublicLanding({ landingId, options = {} }) {
96
- this.client._require({ landingId });
97
- const safeLandingId = encodeURIComponent(landingId);
98
- return this.client(`/landing/public/${safeLandingId}`, { method: "GET", ...options });
99
- }
100
-
101
- /**
102
- * Create a new landing page with the specified landing data and logo file
103
- * @async
104
- * @roles api, admin, developer, billing, user
105
- * @param {Object} params - The parameters for creating a new landing page (see CreateLandingData typedef for details)
106
- * @param {CreateLandingData} params.landingData - The data for the new landing page, including required fields such as brandId and description
107
- * @param {Blob|File} params.file - A logo image file for the landing page, provided as a Blob/File
108
- * @param {RequestOptions} [params.options] - Additional options for the request
109
- * @returns {Promise<SdkResponse<any>>} - The newly created landing page object returned from the server
110
- */
111
- async createLanding({ landingData, file, options = {} }) {
112
- const formData = new FormData();
113
-
114
- if (file) {
115
- formData.append("file", file);
116
- }
117
-
118
- Object.entries(landingData).forEach(([key, value]) => {
119
- if (value !== undefined) {
120
- formData.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
121
- }
122
- });
123
-
124
- return this.multipartClient(`/landing`, { method: "POST", body: formData, ...options });
125
- }
126
-
127
- /**
128
- * Update an existing landing page with the specified landing data and logo file
129
- * @async
130
- * @roles api, admin, developer, billing, user
131
- * @param {Object} params - The parameters for updating a landing page (see UpdateLandingData typedef for details)
132
- * @param {string} params.landingId - The ID of the landing page to update
133
- * @param {UpdateLandingData} params.landingData - The data for the landing page, including required fields such as brandId and description
134
- * @param {Blob|File} params.file - A logo image file for the landing page, provided as a Blob/File
135
- * @param {RequestOptions} [params.options] - Additional options for the request
136
- * @throws {Error} Throws an error if the landingId parameter is missing
137
- * @returns {Promise<SdkResponse<any>>} - The updated landing page object returned from the server
138
- */
139
- async updateLanding({ landingId, landingData, file, options = {} }) {
140
- this.client._require({ landingId });
141
- const safeLandingId = encodeURIComponent(landingId);
142
- const formData = new FormData();
143
-
144
- if (file) {
145
- formData.append("file", file);
146
- }
147
-
148
- Object.entries(landingData).forEach(([key, value]) => {
149
- if (value !== undefined) {
150
- formData.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
151
- }
152
- });
153
-
154
- return this.multipartClient(`/landing/${safeLandingId}`, { method: "PUT", body: formData, ...options });
155
- }
156
-
157
- /**
158
- * Get a landing page by its associated brand ID
159
- * @async
160
- * @roles api, admin, developer, billing, user
161
- * @param {Object} params - The parameters for getting a landing page by brand
162
- * @param {string} params.brandId - The brand ID to look up the landing page for
163
- * @param {RequestOptions} [params.options] - Additional options for the request
164
- * @throws {Error} Throws an error if the brandId parameter is missing
165
- * @returns {Promise<SdkResponse<any>>} - The landing page object returned from the server
166
- */
167
- async getLandingByBrandId({ brandId, options = {} }) {
168
- this.client._require({ brandId });
169
- const safeBrandId = encodeURIComponent(brandId);
170
- return this.client(`/landing/brand/${safeBrandId}`, { method: "GET", ...options });
171
- }
172
-
173
- /**
174
- * Get a brand's Toll-Free landing page template — the reusable look every page the brand generates
175
- * snapshots. Returns an empty array when the brand has no template.
176
- * @async
177
- * @roles api, admin, developer, billing, user
178
- * @param {Object} params - The parameters for getting a landing page template
179
- * @param {string} params.brandId - The brand ID to look up the template for
180
- * @param {RequestOptions} [params.options] - Additional options for the request
181
- * @throws {Error} Throws an error if the brandId parameter is missing
182
- * @returns {Promise<SdkResponse<any>>} - The template returned from the server
183
- */
184
- async getLandingTemplate({ brandId, options = {} }) {
185
- this.client._require({ brandId });
186
- const safeBrandId = encodeURIComponent(brandId);
187
- return this.client(`/landing/template/${safeBrandId}`, { method: "GET", ...options });
188
- }
189
-
190
- /**
191
- * Create or replace a brand's Toll-Free landing page template. Editing a template never alters a page
192
- * that already exists, so a URL already given to a carrier keeps rendering what was declared.
193
- * @async
194
- * @roles api, admin, developer, billing, user
195
- * @param {Object} params - The parameters for saving a landing page template
196
- * @param {string} params.brandId - The brand the template belongs to
197
- * @param {LandingTemplateData} params.templateData - The template fields (see LandingTemplateData typedef)
198
- * @param {Blob|File} [params.file] - A logo image file, provided as a Blob/File. Required the first time only;
199
- * omit it on a later save to keep the stored logo
200
- * @param {RequestOptions} [params.options] - Additional options for the request
201
- * @throws {Error} Throws an error if the brandId parameter is missing
202
- * @returns {Promise<SdkResponse<any>>} - The saved template returned from the server
203
- */
204
- async upsertLandingTemplate({ brandId, templateData, file, options = {} }) {
205
- this.client._require({ brandId });
206
- const safeBrandId = encodeURIComponent(brandId);
207
- const formData = new FormData();
208
-
209
- if (file) {
210
- formData.append("file", file);
211
- }
212
-
213
- Object.entries(templateData).forEach(([key, value]) => {
214
- if (value !== undefined) {
215
- formData.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
216
- }
217
- });
218
-
219
- return this.multipartClient(`/landing/template/${safeBrandId}`, { method: "PUT", body: formData, ...options });
220
- }
221
-
222
- /**
223
- * Delete a landing page by its ID
224
- * @async
225
- * @roles api, admin, developer, billing, user
226
- * @param {Object} params - The parameters for deleting a landing page
227
- * @param {string} params.landingId - The ID of the landing page to delete
228
- * @param {RequestOptions} [params.options] - Additional options for the request
229
- * @throws {Error} Throws an error if the landingId parameter is missing
230
- * @returns {Promise<SdkResponse<any>>} - The response from the server after deleting the landing page
231
- */
232
- async deleteLanding({ landingId, options = {} }) {
233
- this.client._require({ landingId });
234
- const safeLandingId = encodeURIComponent(landingId);
235
- return this.client(`/landing/${safeLandingId}`, { method: "DELETE", ...options });
236
- }
237
- }