@signalhousellc/sdk 1.0.67 → 1.0.68

package/src/domains/Campaigns.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} CreateCampaignData
  * @property {string} brandId - The ID of the brand associated with the campaign (required)
@@ -148,9 +154,9 @@ export class Campaigns {
          * @roles signalhouse
          * @param {Object} params - The parameters for approving the campaign
          * @param {string} params.campaignId - The ID of the campaign to approve
-         * @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 campaignId parameter is missing
-         * @returns {Promise<Object>} The response from the server
+         * @returns {Promise<SdkResponse<any>>} The response from the server
          */
         approveCampaign: async ({ campaignId, options = {} }) => {
           this.client._require({ campaignId });
@@ -163,9 +169,9 @@ export class Campaigns {
          * @roles signalhouse
          * @param {Object} params - The parameters for rejecting the campaign
          * @param {string} params.campaignId - The ID of the campaign to reject
-         * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request (body should include { rejectionReason })
+         * @param {RequestOptions} [params.options] - Additional options for the request (body should include { rejectionReason })
          * @throws {Error} Throws an error if the campaignId parameter is missing
-         * @returns {Promise<Object>} The response from the server
+         * @returns {Promise<SdkResponse<any>>} The response from the server
          */
         rejectCampaign: async ({ campaignId, options = {} }) => {
           this.client._require({ campaignId });
@@ -177,8 +183,8 @@ export class Campaigns {
          * @async
          * @roles signalhouse
          * @param {Object} params - The parameters for retrieving CNP campaigns
-         * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-         * @returns {Promise<Array>} The response from the server
+         * @param {RequestOptions} [params.options] - Additional options for the request
+         * @returns {Promise<SdkResponse<Array>>} The response from the server
          */
         getCNPCampaigns: async ({ options = {} } = {}) => {
           return this.client(`/campaign/cnp`, { method: 'GET', ...options });
@@ -194,9 +200,9 @@ export class Campaigns {
          * @param {string} params.campaignId - The ID of the campaign to transition
          * @param {string} params.status - The target status: "PENDING_REVIEW", "REJECTED", "PENDING_DCA_APPROVAL", "DCA_REJECTED", or "ACTIVE". "PENDING_DCA_APPROVAL" requires a Signal House-approved Short Code brand, issued code, and captured opt-in proof.
          * @param {string} [params.rejectionReason] - Required, nonblank reason for "REJECTED"/"DCA_REJECTED" (max 1024 characters)
-         * @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 campaignId or status parameter is missing
-         * @returns {Promise<Object>} The updated campaign
+         * @returns {Promise<SdkResponse<any>>} The updated campaign
          */
         updateShortCodeCampaignStatus: async ({ campaignId, status, rejectionReason, options = {} }) => {
           this.client._require({ campaignId, status });
@@ -216,8 +222,8 @@ export class Campaigns {
          * @param {string} params.actualCode - Issued five- or six-digit Short Code.
          * @param {string} params.leaseEndDate - Fixed future lease end date. A YYYY-MM-DD value expires at 23:59:59 UTC; timestamps retain their supplied time.
          * @param {string} [params.internalNotes] - Staff-only fulfillment notes.
-         * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options.
-         * @returns {Promise<Object>} The updated campaign.
+         * @param {RequestOptions} [params.options] - Additional options.
+         * @returns {Promise<SdkResponse<any>>} The updated campaign.
          */
         fulfillShortCodeCampaign: async ({ campaignId, actualCode, leaseEndDate, internalNotes, options = {} }) => {
           this.client._require({ campaignId, actualCode, leaseEndDate });
@@ -234,8 +240,8 @@ export class Campaigns {
          * @roles signalhouse
          * @param {Object} params - Submission parameters.
          * @param {string} params.campaignId - Campaign identifier.
-         * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options.
-         * @returns {Promise<Object>} The updated campaign.
+         * @param {RequestOptions} [params.options] - Additional options.
+         * @returns {Promise<SdkResponse<any>>} The updated campaign.
          */
         submitShortCodeCampaignToCarrier: async ({ campaignId, options = {} }) => {
           this.client._require({ campaignId });
@@ -245,7 +251,16 @@ export class Campaigns {
             ...options,
           });
         },
-        /** Confirm Registry offboarding and complete a pending Short Code cancellation. */
+        /**
+         * Confirm Registry offboarding and complete a pending Short Code cancellation.
+         * @async
+         * @param {Object} params - Request parameters.
+         * @param {string} params.campaignId - Campaign identifier.
+         * @param {string} params.requestId - The pending cancellation request to complete.
+         * @param {string} [params.note] - Operator note recorded with the completion.
+         * @param {RequestOptions} [params.options] - Additional options.
+         * @returns {Promise<SdkResponse<any>>} The updated campaign.
+         */
         completeShortCodeCancellation: async ({ campaignId, requestId, note, options = {} }) => {
           this.client._require({ campaignId, requestId });
           const safeCampaignId = encodeURIComponent(campaignId);
@@ -255,7 +270,16 @@ export class Campaigns {
             ...options,
           });
         },
-        /** Dismiss a pending Short Code cancellation and restore its prior lifecycle state. */
+        /**
+         * Dismiss a pending Short Code cancellation and restore its prior lifecycle state.
+         * @async
+         * @param {Object} params - Request parameters.
+         * @param {string} params.campaignId - Campaign identifier.
+         * @param {string} params.requestId - The pending cancellation request to dismiss.
+         * @param {string} [params.note] - Operator note recorded with the dismissal.
+         * @param {RequestOptions} [params.options] - Additional options.
+         * @returns {Promise<SdkResponse<any>>} The updated campaign.
+         */
         dismissShortCodeCancellation: async ({ campaignId, requestId, note, options = {} }) => {
           this.client._require({ campaignId, requestId });
           const safeCampaignId = encodeURIComponent(campaignId);
@@ -265,12 +289,28 @@ export class Campaigns {
             ...options,
           });
         },
-        /** Read expired Short Code leases awaiting manual Registry offboarding. */
+        /**
+         * Read expired Short Code leases awaiting manual Registry offboarding.
+         * @async
+         * @param {Object} [params] - Request parameters.
+         * @param {number} [params.page] - Page number for pagination.
+         * @param {number} [params.limit] - Results per page.
+         * @param {RequestOptions} [params.options] - Additional options.
+         * @returns {Promise<SdkResponse<any>>} The expired leases page.
+         */
         getExpiredShortCodeLeases: async ({ page, limit, options = {} } = {}) => {
           const query = this.client._getQueryString({ page, limit });
           return this.client(`/campaign/short-code/expired-leases${query}`, { method: 'GET', ...options });
         },
-        /** Confirm Registry offboarding and mark an expired Short Code released. */
+        /**
+         * Confirm Registry offboarding and mark an expired Short Code released.
+         * @async
+         * @param {Object} params - Request parameters.
+         * @param {string} params.campaignId - Campaign identifier.
+         * @param {string} [params.note] - Operator note recorded with the release.
+         * @param {RequestOptions} [params.options] - Additional options.
+         * @returns {Promise<SdkResponse<any>>} The updated campaign.
+         */
         releaseExpiredShortCodeLease: async ({ campaignId, note, options = {} }) => {
           this.client._require({ campaignId });
           const safeCampaignId = encodeURIComponent(campaignId);
@@ -298,7 +338,7 @@ export class Campaigns {
    * @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", "TOLL_FREE", or "SHORT_CODE")
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {RequestOptions} [params.options] - Additional options for the request
    *
    * Every record carries a `sentiment` object -- trailing 7-day and 30-day inbound reply sentiment,
    * refreshed periodically from analytics rather than computed per request: `{ sevenDay, thirtyDay,
@@ -316,7 +356,7 @@ export class Campaigns {
    * in the window; the volumes say how much traffic sits behind it. A campaign's figure is scored from the
    * campaign's own summed counters, never averaged from its numbers. For a live figure use GET /number/health
    * or GET /campaign/health.
-   * @returns {Promise<Array|Object>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
+   * @returns {Promise<SdkResponse<Array|Object>>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
    */
   async getCampaigns({
     id,
@@ -356,8 +396,8 @@ export class Campaigns {
    * @param {Object} params - Parameters for reading campaign health
    * @param {string} params.campaignId - Campaign identifier
    * @param {boolean} [params.includeNumbers=false] - When true, include per-number health entries
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional request options
-   * @returns {Promise<Object>} A promise that resolves to `{ campaignId, sevenDay, thirtyDay, numbers? }`
+   * @param {RequestOptions} [params.options] - Additional request options
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ campaignId, sevenDay, thirtyDay, numbers? }`
    */
   async getCampaignHealth({ campaignId, includeNumbers = false, options = {} }) {
     this.client._require({ campaignId });
@@ -365,15 +405,34 @@ export class Campaigns {
     return this.client(`/campaign/health${queryString}`, { method: 'GET', ...options });
   }
 
+  /**
+   * Get the carrier throughput ceilings a campaign is currently sending under: the AT&T per-minute limit
+   * (per campaign, held 10% under the published ceiling) and the T-Mobile daily cap (per brand), each with
+   * its current tier and the next rung on the ladder, plus today's T-Mobile usage. Resolved from the same
+   * brand status / brand score rules the send path enforces with.
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - Parameters for reading campaign throughput limits
+   * @param {string} params.campaignId - Campaign identifier
+   * @param {RequestOptions} [params.options] - Additional request options
+   * @throws {Error} Throws an error if the campaignId parameter is missing
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ campaignId, brandId, usecase, brand: { status, brandScore, entityType }, att: { tier, scope, unit, sms: { limit }, mms: { limit }, marginPercent, nextTier }, tmobile: { tier, scope, unit, dailyLimit, thresholds, nextTier, usedToday: { date, segments, resetsAt } | null } }`. A null tier/limit means the carrier ladder does not apply (unverified brand, GOVERNMENT entity, PUBLIC_SAFETY_RESTRICTED usecase); a null nextTier means the top rung or a usecase-capped (LOW_VOLUME) campaign.
+   */
+  async getCampaignThroughputLimits({ campaignId, options = {} }) {
+    this.client._require({ campaignId });
+    const queryString = this.client._getQueryString({ campaignId });
+    return this.client(`/campaign/throughput-limits${queryString}`, { method: 'GET', ...options });
+  }
+
   /**
    * Create a new campaign
    * @async
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for creating the campaign (see CreateCampaignData typedef for details)
    * @param {CreateCampaignData} params.campaignData - The data for the campaign to be created (see CreateCampaignData typedef for details)
-   * @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 campaignData parameter is missing or if required fields in campaignData are missing
-   * @returns {Promise<Object>} The response from the server
+   * @returns {Promise<SdkResponse<any>>} The response from the server
    */
   async createCampaign({ campaignData, options = {} }) {
     this.client._require({ campaignData: campaignData });
@@ -386,9 +445,9 @@ export class Campaigns {
    * @roles api, admin, developer, 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
+   * @param {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
+   * @returns {Promise<SdkResponse<any>>} The response from the server
    */
   async createTollFreeCampaign({ campaignData, options = {} }) {
     this.client._require({ campaignData });
@@ -404,9 +463,9 @@ export class Campaigns {
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for creating the Short Code campaign
    * @param {CreateShortCodeCampaignData} params.campaignData - The Short Code campaign data (see CreateShortCodeCampaignData typedef for details)
-   * @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 campaignData parameter is missing
-   * @returns {Promise<Object>} The response from the server
+   * @returns {Promise<SdkResponse<any>>} The response from the server
    */
   async createShortCodeCampaign({ campaignData, options = {} }) {
     this.client._require({ campaignData });
@@ -423,9 +482,9 @@ export class Campaigns {
    * @param {Object} params - The parameters for updating the Short Code campaign
    * @param {string} params.campaignId - The ID of the campaign to update
    * @param {Object} params.updateData - The fields to update (top-level campaign fields plus an optional `shortCode` object of editable Short Code fields; pass a new `uploadOptInImage` URL as `shortCode.screenshotUrl` to replace the opt-in proof)
-   * @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 campaignId parameter is missing
-   * @returns {Promise<Object>} The updated campaign
+   * @returns {Promise<SdkResponse<any>>} The updated campaign
    */
   async updateShortCodeCampaign({ campaignId, updateData, options = {} }) {
     this.client._require({ campaignId });
@@ -441,9 +500,9 @@ export class Campaigns {
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for cancelling the campaign
    * @param {string} params.campaignId - The ID of the campaign to cancel
-   * @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 campaignId parameter is missing
-   * @returns {Promise<Object>} The cancelled campaign
+   * @returns {Promise<SdkResponse<any>>} The cancelled campaign
    */
   async cancelShortCodeCampaign({ campaignId, options = {} }) {
     this.client._require({ campaignId });
@@ -460,9 +519,9 @@ export class Campaigns {
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for downloading the artifact
    * @param {string} params.artifactId - The receipt identifier from `numberSource.externalLease.receiptArtifactId`
-   * @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 artifactId parameter is missing
-   * @returns {Promise<Object>} The response from the server (raw file bytes as `data` when a binary responseType is used)
+   * @returns {Promise<SdkResponse<any>>} The response from the server (raw file bytes as `data` when a binary responseType is used)
    */
   async readCampaignArtifact({ artifactId, options = {} }) {
     this.client._require({ artifactId });
@@ -476,10 +535,10 @@ export class Campaigns {
    * @async
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for uploading the opt-in image
-   * @param {Buffer|Blob|File} params.file - The image file to upload, provided as a Buffer/Blob/File
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {Blob|File} params.file - The image file to upload, provided as a Blob/File
+   * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the file parameter is missing
-   * @returns {Promise<Object>} The response from the server containing the hosted image's id and URL
+   * @returns {Promise<SdkResponse<any>>} The response from the server containing the hosted image's id and URL
    */
   async uploadOptInImage({ file, options = {} }) {
     this.client._require({ file });
@@ -498,9 +557,9 @@ export class Campaigns {
    * @param {string} [params.landingId] - The specific page to capture. Required for Toll-Free brands, which have
    *   one page per campaign — omitted, the request is refused rather than guessing which page to shoot. A 10DLC
    *   brand has a single page, so it may be omitted there
-   * @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 response from the server containing the hosted image's id and URL
+   * @returns {Promise<SdkResponse<any>>} The response from the server containing the hosted image's id and URL
    */
   async captureOptInImageFromLanding({ brandId, landingId, options = {} }) {
     this.client._require({ brandId });
@@ -516,9 +575,9 @@ export class Campaigns {
    * @param {Object} params - The parameters for updating the campaign (see UpdateCampaignData typedef for details)
    * @param {string} params.campaignId - The ID of the campaign to update
    * @param {UpdateCampaignData} params.campaignData - The data for the campaign to be updated (see UpdateCampaignData typedef for details)
-   * @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 campaignId parameter is missing or if required fields in campaignData are missing
-   * @returns {Promise<Object>} The response from the server
+   * @returns {Promise<SdkResponse<any>>} The response from the server
    */
   async updateCampaign({ campaignId, campaignData, options = {} }) {
     this.client._require({ campaignId: campaignId });
@@ -533,9 +592,9 @@ export class Campaigns {
    * @param {Object} params - The parameters for adding the comment
    * @param {string} params.campaignId - The ID of the campaign
    * @param {string} params.comment - The comment/note text
-   * @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 campaignId or comment parameter is missing
-   * @returns {Promise<Object>} The updated campaign object
+   * @returns {Promise<SdkResponse<any>>} The updated campaign object
    */
   async addCampaignComment({ campaignId, comment, options = {} }) {
     this.client._require({ campaignId, comment });
@@ -549,9 +608,9 @@ export class Campaigns {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for deleting the campaign
    * @param {string} params.campaignId - The ID of the campaign 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 campaignId parameter is missing
-   * @returns {Promise<Object>} The response from the server
+   * @returns {Promise<SdkResponse<any>>} The response from the server
    */
   async deleteCampaign({ campaignId, options = {} }) {
     this.client._require({ campaignId: campaignId });
@@ -565,9 +624,9 @@ export class Campaigns {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for appealing the campaign rejection
    * @param {string} params.campaignId - The ID of the campaign to appeal
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request (body should include { reason })
+   * @param {RequestOptions} [params.options] - Additional options for the request (body should include { reason })
    * @throws {Error} Throws an error if the campaignId parameter is missing
-   * @returns {Promise<Object>} The response from the server
+   * @returns {Promise<SdkResponse<any>>} The response from the server
    */
   async appealDcaRejection({ campaignId, options = {} }) {
     this.client._require({ campaignId: campaignId });
@@ -581,9 +640,9 @@ export class Campaigns {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for nudging the campaign
    * @param {string} params.campaignId - The ID of the campaign to nudge
-   * @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 campaignId parameter is missing
-   * @returns {Promise<Object>} The response from the server
+   * @returns {Promise<SdkResponse<any>>} The response from the server
    */
   async nudgeDcaForCampaign({ campaignId, options = {} }) {
     this.client._require({ campaignId: campaignId });

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);