@signalhousellc/sdk 1.0.66 → 1.0.68

package/src/domains/Campaigns.js

@@ -1,8 +1,14 @@
+/** @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)
  * @property {string} usecase - The use case for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOCIAL, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW)
- * @property {Array<string>} [subUsecases] - An array of sub-use cases for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOCIAL, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW)
+ * @property {Array<string>} [subUsecases] - An array of sub-use cases for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW — NOT SOCIAL, which TCR rejects as a sub-usecase for every parent usecase even though it is valid as the top-level `usecase`)
  * @property {string} description - A detailed description of the campaign (required, must be between 40 and 4096 characters)
  * @property {boolean} [embeddedLink=true] - Whether the campaign includes an embedded link (optional, defaults to true)
  * @property {boolean} [embeddedPhone=false] - Whether the campaign includes an embedded phone number (optional, defaults to false)
@@ -36,7 +42,7 @@
 /**
  * @typedef {Object} UpdateCampaignData
  * @property {string} [usecase] - The use case for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOCIAL, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW)
- * @property {Array<string>} [subUsecases] - An array of sub-use cases for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOCIAL, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW)
+ * @property {Array<string>} [subUsecases] - An array of sub-use cases for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW — NOT SOCIAL, which TCR rejects as a sub-usecase for every parent usecase even though it is valid as the top-level `usecase`)
  * @property {string} [description] - A detailed description of the campaign (optional, must be between 40 and 4096 characters if provided)
  * @property {boolean} [embeddedLink] - Whether the campaign includes an embedded link (optional)
  * @property {boolean} [embeddedPhone] - Whether the campaign includes an embedded phone number (optional)
@@ -115,7 +121,8 @@
  * @property {string} [doubleOptInMessage] - Required when adultContent is true (20-1024 characters)
  * @property {string} programSummary - Generated-but-editable campaign/program summary (required, 40-2048 characters)
  * @property {string} optInConfirmationMessage - The opt-in confirmation message (required, 20-1024 characters)
- * @property {string} [optInUrl] - Public HTTPS URL for the live opt-in experience. When omitted, Signal House uses the brand's optInLink before capturing its screenshot asynchronously, retrying up to three times.
+ * @property {string} optInUrl - Public HTTPS URL for the live opt-in experience, shown to reviewers as a link (required; private, local, and credentialed URLs are rejected)
+ * @property {string} screenshotUrl - Hosted opt-in proof screenshot URL returned by `uploadOptInImage` (required). Must be a Signal House-hosted opt-in image owned by your group; external URLs are rejected
  */
 
 /**
@@ -129,7 +136,6 @@
  * @property {string} sample1 - Sample message 1 (required, 20-1024 characters)
  * @property {string} sample2 - Sample message 2 (required, 20-1024 characters)
  * @property {string} sample3 - Sample message 3 (required, 20-1024 characters)
- * @property {boolean} [autoRenewal=true] - Whether the campaign should auto-renew (optional, defaults to true)
  * @property {string} [tag] - A tag for the campaign (optional, at most 255 characters)
  * @property {ShortCodeDetails} shortCode - The Short Code campaign details (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 });
@@ -186,16 +192,17 @@ export class Campaigns {
         /**
          * Transition a Short Code campaign's review status (SHGHL-2225). A customer-visible reason is
          * required for both rejection states ("REJECTED" = Signal House Rejected, "DCA_REJECTED" =
-         * Rejected). Fulfillment and carrier submission are separate staff operations.
+         * Rejected). Selecting "PENDING_DCA_APPROVAL" runs the guarded carrier-review transition;
+         * fulfillment remains a separate staff operation.
          * @async
          * @roles signalhouse
          * @param {Object} params - The parameters for the status transition
          * @param {string} params.campaignId - The ID of the campaign to transition
-         * @param {string} params.status - The target status: "PENDING_REVIEW", "REJECTED", "PENDING_CREATION", "DCA_REJECTED", or "ACTIVE". Use submitShortCodeCampaignToCarrier for "PENDING_DCA_APPROVAL".
-         * @param {string} [params.rejectionReason] - Required for "REJECTED"/"DCA_REJECTED" (10-1024 characters)
-         * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+         * @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 {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 });
@@ -213,16 +220,17 @@ export class Campaigns {
          * @param {Object} params - Fulfillment parameters.
          * @param {string} params.campaignId - Campaign identifier.
          * @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, internalNotes, options = {} }) => {
-          this.client._require({ campaignId, actualCode });
+        fulfillShortCodeCampaign: async ({ campaignId, actualCode, leaseEndDate, internalNotes, options = {} }) => {
+          this.client._require({ campaignId, actualCode, leaseEndDate });
           const safeCampaignId = encodeURIComponent(campaignId);
           return this.client(`/campaign/short-code/${safeCampaignId}/fulfill`, {
             method: 'POST',
-            body: { actualCode, internalNotes },
+            body: { actualCode, leaseEndDate, internalNotes },
             ...options,
           });
         },
@@ -232,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 });
@@ -243,6 +251,73 @@ export class Campaigns {
             ...options,
           });
         },
+        /**
+         * 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);
+          return this.client(`/campaign/short-code/${safeCampaignId}/cancellation/complete`, {
+            method: 'POST',
+            body: { requestId, note },
+            ...options,
+          });
+        },
+        /**
+         * 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);
+          return this.client(`/campaign/short-code/${safeCampaignId}/cancellation/dismiss`, {
+            method: 'POST',
+            body: { requestId, note },
+            ...options,
+          });
+        },
+        /**
+         * 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.
+         * @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);
+          return this.client(`/campaign/short-code/${safeCampaignId}/expired-lease/release`, {
+            method: 'POST', body: { note }, ...options,
+          });
+        },
       };
     }
   }
@@ -263,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,
@@ -273,7 +348,15 @@ export class Campaigns {
    * window, which is not the same as a score of 0 -- null means nobody replied, 0 means replies
    * averaged neutral. `updatedAt` is null until the first rollup writes the record, and it tracks when
    * the figures last CHANGED, not when the job last ran.
-   * @returns {Promise<Array|Object>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
+   *
+   * Every record also carries a `health` object -- trailing 7-day and 30-day delivery/opt-out health from
+   * the same periodic refresh: `{ sevenDay, thirtyDay, updatedAt }`, each window being `{ score,
+   * deliveryRate, optOutRate, deliveryScore, optOutScore, messagesSent, messagesDelivered, messagesFailed,
+   * optOuts }`. `score` is 1.0..10.0 (the mean of the two bucket scores) and is null when nothing was sent
+   * 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<SdkResponse<Array|Object>>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
    */
   async getCampaigns({
     id,
@@ -313,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 });
@@ -322,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 });
@@ -343,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 });
@@ -354,16 +456,16 @@ export class Campaigns {
 
   /**
    * Create a new Short Code campaign and submit it for Signal House review (SHGHL-2225). Requires an
-   * approved (VERIFIED) Short Code brand. `campaignData.shortCode.optInUrl` is optional; Signal House
-  * uses the brand's `optInLink` when it is omitted, then captures its screenshot asynchronously, retrying up to three times. Request or register the
-  * campaign's Short Code separately through `numbers.requestShortCodeAcquisition` after creation.
+   * approved (VERIFIED) Short Code brand. Upload the opt-in proof screenshot first with `uploadOptInImage`
+   * and pass the returned URL as `campaignData.shortCode.screenshotUrl` (required). Request or register the
+   * campaign's Short Code separately through `numbers.requestShortCodeAcquisition` after creation.
    * @async
    * @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 });
@@ -379,10 +481,10 @@ export class Campaigns {
    * @roles api, admin, developer, user
    * @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)
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @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 {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 });
@@ -391,17 +493,16 @@ export class Campaigns {
   }
 
   /**
-   * Cancel a Short Code campaign (SHGHL-2225). Customers may cancel only while the campaign is in Signal
-   * House Review or Signal House Rejected status; Signal House staff may cancel from any non-terminal
-   * status. Persists as "EXPIRED" (displayed as "Cancelled"). A real Registry lease (external or an
-   * already-fulfilled Signal House request) is never auto-released — see SHGHL-2228 for offboarding.
+  * Cancel a Short Code campaign. A customer cancellation for an issued Short Code returns
+  * PENDING_DELETE (displayed as Cancellation Pending) until Signal House confirms Registry offboarding.
+  * Unissued RANDOM/VANITY requests, plus staff-confirmed cancellations, return EXPIRED immediately.
    * @async
    * @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 });
@@ -418,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 });
@@ -430,14 +531,14 @@ export class Campaigns {
 
   /**
    * Upload an opt-in proof image to be hosted on-platform, returning a publicly-fetchable URL suitable for a
-   * Toll-Free campaign's optInImageURLs
+   * Toll-Free campaign's optInImageURLs or a Short Code campaign's shortCode.screenshotUrl
    * @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 });
@@ -456,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 });
@@ -474,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 });
@@ -491,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 });
@@ -507,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 });
@@ -523,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 });
@@ -539,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 });