@signalhousellc/sdk 1.0.67 → 1.0.69

package/src/domains/Groups.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 export class Groups {
 	constructor(client, enableAdmin) {
 		this.client = client;
@@ -15,8 +21,8 @@ export class Groups {
 				 * @param {string} [params.groupId] - Restrict results to a group.
 				 * @param {number} [params.limit] - Maximum rows to return.
 				 * @param {number} [params.offset] - Rows to skip; requires limit.
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-				 * @returns {Promise<Object>} - Group-level resource count rows.
+				 * @param {RequestOptions} [params.options] - Additional options for the request.
+				 * @returns {Promise<SdkResponse<any>>} - Group-level resource count rows.
 				 */
 				getGroupCounts: async ({ groupId, limit, offset, options = {} } = {}) => {
 					const queryString = this.client._getQueryString({ groupId, limit, offset });
@@ -30,8 +36,8 @@ export class Groups {
 				 * @param {Object} params - The parameters for getting groups
 				 * @param {number} [params.page] - The page number for pagination
 				 * @param {number} [params.limit] - The number of items per page
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - The list of groups returned from the server
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - The list of groups returned from the server
 				 */
 				getGroups: async ({ page, limit, options = {} }) => {
 					const filters = { page, limit };
@@ -45,24 +51,55 @@ export class Groups {
 				 * @roles signalhouse
 				 * @param {Object} params - The parameters for creating a new group
 				 * @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.
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @param {RequestOptions} [params.options] - Additional options for the request
 				 * @throws {Error} Throws an error if the groupData parameter is missing or if required fields within groupData are missing
-				 * @returns {Promise<Object>} - The created group object returned from the server
+				 * @returns {Promise<SdkResponse<any>>} - The created group object returned from the server
 				 */
 				createGroup: async ({ groupData, options = {} }) => {
 					this.client._require({ groupData: groupData });
 					return this.client(`/group`, { method: "POST", body: groupData, ...options });
 				},
 
+				/**
+				 * Record a GHL-app or Shopify-app install's registration for the per-surface
+				 * customer-lifecycle webhook system. Call this right after admin.createGroup when
+				 * provisioning a group outside the Portal's self-registration flow (which records
+				 * itself automatically) — without it, the group never fires a registration webhook and
+				 * is never eligible for the "registered but no brand submitted" staleness webhook.
+				 * Internal-only: not documented in the public API reference (deliberate exception, see
+				 * CLAUDE.md's API Change Propagation Rules — mirrors the /oauth exception).
+				 * @async
+				 * @roles signalhouse_api, signalhouse_admin
+				 * @param {Object} params - The parameters for recording a registration
+				 * @param {string} params.groupId - The just-provisioned group's ID
+				 * @param {string} params.registrationSource - Which surface provisioned this group ("ghl" or "shopify")
+				 * @param {string} [params.firstName] - The account owner's first name
+				 * @param {string} [params.fullName] - The account owner's full name
+				 * @param {string} [params.email] - The account owner's email
+				 * @param {string} [params.phone] - The account owner's phone number
+				 * @param {string} [params.estimatedVolume] - Estimated monthly message volume
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if the groupId or registrationSource parameter is missing
+				 * @returns {Promise<SdkResponse<any>>} - `{ success: true }`
+				 */
+				recordLifecycleRegistration: async ({ groupId, registrationSource, firstName, fullName, email, phone, estimatedVolume, options = {} }) => {
+					this.client._require({ groupId, registrationSource });
+					return this.client(`/group/lifecycle/registration`, {
+						method: "POST",
+						body: { groupId, registrationSource, firstName, fullName, email, phone, estimatedVolume },
+						...options,
+					});
+				},
+
 				/**
 				 * Delete a group with the specified group ID
 				 * @async
 				 * @roles signalhouse
 				 * @param {Object} params - The parameters for deleting a group
 				 * @param {string} params.groupId - The ID of the group to delete
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @param {RequestOptions} [params.options] - Additional options for the request
 				 * @throws {Error} Throws an error if the groupId parameter is missing
-				 * @returns {Promise<Object>} - The deleted group object returned from the server
+				 * @returns {Promise<SdkResponse<any>>} - The deleted group object returned from the server
 				 */
 				deleteGroup: async ({ groupId, options = {} }) => {
 					this.client._require({ groupId });
@@ -78,9 +115,9 @@ export class Groups {
 				 * @param {Object} params - The parameters for updating a group's compliance status
 				 * @param {string} params.groupId - The ID of the group to update
 				 * @param {string} params.complianceStatus - One of "unverified", "pending", "verified", "rejected"
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @param {RequestOptions} [params.options] - Additional options for the request
 				 * @throws {Error} Throws an error if the groupId or complianceStatus parameter is missing
-				 * @returns {Promise<Object>} - The updated group object returned from the server
+				 * @returns {Promise<SdkResponse<any>>} - The updated group object returned from the server
 				 */
 				updateComplianceStatus: async ({ groupId, complianceStatus, options = {} }) => {
 					this.client._require({ groupId, complianceStatus });
@@ -99,9 +136,9 @@ export class Groups {
 				 * @param {string} params.externalSystem - The external system ("ghl" or "shopify")
 				 * @param {string} params.externalId - The external tenant identifier
 				 * @param {string} [params.existingGroupId] - An existing V2 group ID to repoint to, if any
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @param {RequestOptions} [params.options] - Additional options for the request
 				 * @throws {Error} Throws an error if linkToken, externalSystem, or externalId is missing
-				 * @returns {Promise<Object>} - The link outcome ({ status, canonicalGroupId, ... })
+				 * @returns {Promise<SdkResponse<any>>} - The link outcome ({ status, canonicalGroupId, ... })
 				 */
 				linkExternal: async ({ linkToken, externalSystem, externalId, existingGroupId, options = {} }) => {
 					this.client._require({ linkToken, externalSystem, externalId });
@@ -121,8 +158,8 @@ export class Groups {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for getting a group
 	 * @param {string} params.id - The ID of the group to retrieve
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - The group object returned from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} - The group object returned from the server
 	 */
 	async getGroup({ id, options = {} }) {
 		const filters = { id };
@@ -138,9 +175,9 @@ export class Groups {
 	 * @param {string} params.id - The ID of the group to update
 	 * @param {Object} params.groupData - The data for the group, including required fields such as groupName.
 	 *   Optional CNP fields: cspId (string|null), defaultCnpSubgroupId (string|null)
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the id or groupData parameter is missing
-	 * @returns {Promise<Object>} - The updated group object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The updated group object returned from the server
 	 */
 	async updateGroup({ id, groupData, options = {} }) {
 		this.client._require({ id, groupData: groupData });

package/src/domains/Landings.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} TollFreeConsentBox
  * @property {string} useCase - The use case the checkbox covers
@@ -67,9 +73,9 @@ export class Landings {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for getting a landing page
 	 * @param {string} params.landingId - The ID of the landing page to retrieve
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the landingId parameter is missing
-	 * @returns {Promise<Object>} - The landing page object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The landing page object returned from the server
 	 */
 	async getLandings({ landingId, options = {} }) {
 		this.client._require({ landingId });
@@ -82,9 +88,9 @@ export class Landings {
 	 * @async
 	 * @param {Object} params - The parameters for getting a public landing page
 	 * @param {string} params.landingId - The ID of the public landing page to retrieve
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the landingId parameter is missing
-	 * @returns {Promise<Object>} - The public landing page object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The public landing page object returned from the server
 	 */
 	async getPublicLanding({ landingId, options = {} }) {
 		this.client._require({ landingId });
@@ -98,9 +104,9 @@ export class Landings {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for creating a new landing page (see CreateLandingData typedef for details)
 	 * @param {CreateLandingData} params.landingData - The data for the new landing page, including required fields such as brandId and description
-	 * @param {Buffer} params.file - A logo image file for the landing page, provided as a Buffer
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - The newly created landing page object returned from the server
+	 * @param {Blob|File} params.file - A logo image file for the landing page, provided as a Blob/File
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} - The newly created landing page object returned from the server
 	 */
 	async createLanding({ landingData, file, options = {} }) {
 		const formData = new FormData();
@@ -111,7 +117,7 @@ export class Landings {
 
 		Object.entries(landingData).forEach(([key, value]) => {
 			if (value !== undefined) {
-				formData.append(key, typeof value === "object" ? JSON.stringify(value) : value);
+				formData.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
 			}
 		});
 
@@ -125,10 +131,10 @@ export class Landings {
 	 * @param {Object} params - The parameters for updating a landing page (see UpdateLandingData typedef for details)
 	 * @param {string} params.landingId - The ID of the landing page to update
 	 * @param {UpdateLandingData} params.landingData - The data for the landing page, including required fields such as brandId and description
-	 * @param {Buffer} params.file - A logo image file for the landing page, provided as a Buffer
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {Blob|File} params.file - A logo image file for the landing page, provided as a Blob/File
+	 * @param {RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the landingId parameter is missing
-	 * @returns {Promise<Object>} - The updated landing page object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The updated landing page object returned from the server
 	 */
 	async updateLanding({ landingId, landingData, file, options = {} }) {
 		this.client._require({ landingId });
@@ -141,32 +147,22 @@ export class Landings {
 
 		Object.entries(landingData).forEach(([key, value]) => {
 			if (value !== undefined) {
-				formData.append(key, typeof value === "object" ? JSON.stringify(value) : value);
+				formData.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
 			}
 		});
 
 		return this.multipartClient(`/landing/${safeLandingId}`, { method: "PUT", body: formData, ...options });
 	}
 
-	/**
-	 * Delete a landing page by its ID
-	 * @async
-	 * @roles api, admin, developer, billing, user
-	 * @param {Object} params - The parameters for deleting a landing page
-	 * @param {string} params.landingId - The ID of the landing page to delete
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @throws {Error} Throws an error if the landingId parameter is missing
-	 * @returns {Promise<Object>} - The response from the server after deleting the landing page
-	 */
 	/**
 	 * Get a landing page by its associated brand ID
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for getting a landing page by brand
 	 * @param {string} params.brandId - The brand ID to look up the landing page for
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the brandId parameter is missing
-	 * @returns {Promise<Object>} - The landing page object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The landing page object returned from the server
 	 */
 	async getLandingByBrandId({ brandId, options = {} }) {
 		this.client._require({ brandId });
@@ -181,9 +177,9 @@ export class Landings {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for getting a landing page template
 	 * @param {string} params.brandId - The brand ID to look up the template for
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the brandId parameter is missing
-	 * @returns {Promise<Object>} - The template returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The template returned from the server
 	 */
 	async getLandingTemplate({ brandId, options = {} }) {
 		this.client._require({ brandId });
@@ -199,11 +195,11 @@ export class Landings {
 	 * @param {Object} params - The parameters for saving a landing page template
 	 * @param {string} params.brandId - The brand the template belongs to
 	 * @param {LandingTemplateData} params.templateData - The template fields (see LandingTemplateData typedef)
-	 * @param {Buffer} [params.file] - A logo image file, provided as a Buffer. Required the first time only;
+	 * @param {Blob|File} [params.file] - A logo image file, provided as a Blob/File. Required the first time only;
 	 *   omit it on a later save to keep the stored logo
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the brandId parameter is missing
-	 * @returns {Promise<Object>} - The saved template returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The saved template returned from the server
 	 */
 	async upsertLandingTemplate({ brandId, templateData, file, options = {} }) {
 		this.client._require({ brandId });
@@ -216,13 +212,23 @@ export class Landings {
 
 		Object.entries(templateData).forEach(([key, value]) => {
 			if (value !== undefined) {
-				formData.append(key, typeof value === "object" ? JSON.stringify(value) : value);
+				formData.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
 			}
 		});
 
 		return this.multipartClient(`/landing/template/${safeBrandId}`, { method: "PUT", body: formData, ...options });
 	}
 
+	/**
+	 * Delete a landing page by its ID
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for deleting a landing page
+	 * @param {string} params.landingId - The ID of the landing page to delete
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the landingId parameter is missing
+	 * @returns {Promise<SdkResponse<any>>} - The response from the server after deleting the landing page
+	 */
 	async deleteLanding({ landingId, options = {} }) {
 		this.client._require({ landingId });
 		const safeLandingId = encodeURIComponent(landingId);