@signalhousellc/sdk 1.0.67 → 1.0.69

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/Dnc.js

@@ -0,0 +1,168 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
+/**
+ * Do Not Contact domain: the attested "Disable Automated Opt-Out" account setting. Signal House
+ * suppresses sends to recipients who opted out of the sending campaign by default; an account may
+ * disable that only by having an officer read and e-sign the Opt-Out Handling Attestation inside a
+ * Signal House app: the portal (a customer login signs for its own account) or one of our apps running
+ * as signalhouse_api (GHL, Shopify), which signs for the account it names on behalf of the customer user
+ * it authenticated. Every method therefore lives under the admin namespace (present only when the SDK is
+ * created with `enableAdmin: true`), and the API refuses the customer "api" (API key) role on the signing
+ * routes, so attestation can never be performed by a third-party integration.
+ */
+export class Dnc {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+
+		// Hidden Admin namespace INSIDE the domain
+		if (enableAdmin) {
+			this.admin = {
+				/**
+				 * Get the current Opt-Out Handling Attestation text for the session's account with every placeholder
+				 * filled (account values, the session's email and role, blanks in the signature block for what only
+				 * signing supplies), plus the version and template hash a signature must echo back. The app must
+				 * render this text; it never ships its own copy.
+				 * @async
+				 * @roles admin, developer, billing (portal logins); signalhouse_* with groupId
+				 * @param {Object} [params] - Optional parameters
+				 * @param {string} [params.groupId] - Group to render for (apps and staff; customers always get their active group)
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - `{ version, templateSha256, text, checkboxText, groupId, accountName, customerLegalName }`
+				 */
+				getCurrentAttestation: async ({ groupId, options = {} } = {}) => {
+					const queryString = this.client._getQueryString({ groupId });
+					return this.client(`/dnc/attestation/current${queryString}`, { method: "GET", ...options });
+				},
+
+				/**
+				 * Sign the attestation and disable automated opt-out suppression for the account and every subgroup,
+				 * effective within about a minute on every API instance. Two callers: a portal login signs for its own
+				 * account and the signer identity is taken from the session; a Signal House app running as
+				 * signalhouse_api (GHL, Shopify) signs for the `groupId` it names and supplies the identity of the
+				 * customer user it authenticated (`signerEmail`, optional `signerUserId`, `signedVia`, and the end
+				 * user's `signerIpAddress` / `signerUserAgent`, which otherwise default to the app server's). Resolves
+				 * 201 when this call created the record and 200 with the existing record on a repeat or concurrent
+				 * call. A stale version or hash is refused with 409 and `details.code === "ATTESTATION_VERSION_MISMATCH"`;
+				 * an unchecked box or blank field with 400. Human staff roles and customer API-key sessions are refused.
+				 * @async
+				 * @roles admin, developer, billing (portal logins); signalhouse_api (apps, with groupId)
+				 * @param {Object} params
+				 * @param {string} params.version - The version returned by getCurrentAttestation
+				 * @param {string} params.templateSha256 - The template hash returned by getCurrentAttestation
+				 * @param {boolean} params.checkboxAcknowledged - Must be true
+				 * @param {boolean} params.scrolledToEnd - Must be true
+				 * @param {string} params.customerLegalName - Company legal name
+				 * @param {string} params.signerName - Signer's typed full legal name (the electronic signature)
+				 * @param {string} params.signerTitle - Signer's title
+				 * @param {string} [params.groupId] - App callers: the account being attested
+				 * @param {string} [params.signerEmail] - App callers (required): the signer's email as authenticated by the app
+				 * @param {string} [params.signerUserId] - App callers: the app's id for the signer
+				 * @param {string} [params.signedVia] - App callers: the app name, e.g. "ghl" or "shopify"
+				 * @param {string} [params.signerIpAddress] - App callers: the end user's IP address
+				 * @param {string} [params.signerUserAgent] - App callers: the end user's user agent
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if a required parameter is missing
+				 * @returns {Promise<SdkResponse<any>>} - `{ attestation, created }`
+				 */
+				signAttestation: async ({ version, templateSha256, checkboxAcknowledged, scrolledToEnd, customerLegalName, signerName, signerTitle, groupId, signerEmail, signerUserId, signedVia, signerIpAddress, signerUserAgent, options = {} }) => {
+					this.client._require({ version, templateSha256, customerLegalName, signerName, signerTitle });
+					const appFields = Object.fromEntries(Object.entries({ groupId, signerEmail, signerUserId, signedVia, signerIpAddress, signerUserAgent }).filter(([, value]) => value !== undefined));
+					return this.client(`/dnc/attestation`, {
+						method: "POST",
+						body: { version, templateSha256, checkboxAcknowledged, scrolledToEnd, customerLegalName, signerName, signerTitle, ...appFields },
+						...options,
+					});
+				},
+
+				/**
+				 * Revoke the active attestation and re-enable automated opt-out suppression, effective within about a
+				 * minute: a portal login for its own account, or an app (signalhouse_api) for the `groupId` it names.
+				 * The record is retained as "revoked". 404 when nothing is active.
+				 * @async
+				 * @roles admin, developer, billing (portal logins); signalhouse_api (apps, with groupId)
+				 * @param {Object} [params] - Optional parameters
+				 * @param {string} [params.groupId] - App callers: the account
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - `{ attestation }`
+				 */
+				revokeAttestation: async ({ groupId, options = {} } = {}) => {
+					return this.client(`/dnc/attestation/revoke`, { method: "POST", ...(groupId ? { body: { groupId } } : {}), ...options });
+				},
+
+				/**
+				 * Read an account's attestation state: whether automated opt-out is disabled, the active record
+				 * (full stored text included), the full history, and whether the active record predates the
+				 * current template and must be re-signed by `resignDeadline`.
+				 * @async
+				 * @roles admin, developer, billing (portal logins); signalhouse_* with groupId
+				 * @param {Object} [params] - Optional parameters
+				 * @param {string} [params.groupId] - Group to read (apps and staff; customers always get their active group)
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - `{ groupId, automatedOptOutDisabled, currentVersion, currentTemplateSha256, requiresResign, resignDeadline, active, history }`
+				 */
+				getAttestation: async ({ groupId, options = {} } = {}) => {
+					const queryString = this.client._getQueryString({ groupId });
+					return this.client(`/dnc/attestation${queryString}`, { method: "GET", ...options });
+				},
+
+				/**
+				 * List opt-out attestations across every account, newest first, with each group's trailing
+				 * would-have-suppressed counts (7 and 30 days, recorded while attested) and 7-day opt-out count.
+				 * The full attestation text is omitted from list rows. Staff-only.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} [params] - Optional parameters
+				 * @param {("active"|"revoked"|"superseded")} [params.status] - Filter by status
+				 * @param {string} [params.groupId] - Filter by group
+				 * @param {number} [params.page] - Page number (default 1)
+				 * @param {number} [params.limit] - Rows per page (default 50, max 500)
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - `{ rows, totalCount, page, limit }`
+				 */
+				listAttestations: async ({ status, groupId, page, limit, options = {} } = {}) => {
+					const queryString = this.client._getQueryString({ status, groupId, page, limit });
+					return this.client(`/dnc/attestations${queryString}`, { method: "GET", ...options });
+				},
+
+				/**
+				 * Read one attestation with its stored text, hashes, signer identity, IP and user agent, plus
+				 * the group's full attestation history. Staff-only.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params
+				 * @param {string} params.id - The attestation id
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if the id parameter is missing
+				 * @returns {Promise<SdkResponse<any>>} - `{ attestation, history }`
+				 */
+				getAttestationById: async ({ id, options = {} }) => {
+					this.client._require({ id });
+					return this.client(`/dnc/attestations/${encodeURIComponent(id)}`, { method: "GET", ...options });
+				},
+
+				/**
+				 * Revoke an active attestation with a reason and re-enable automated opt-out for the account.
+				 * Emails the signer and account owner. There is no staff path that creates an attestation. Staff-only.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params
+				 * @param {string} params.id - The attestation id
+				 * @param {("carrier_complaint"|"regulator_inquiry"|"legal_request"|"excessive_opt_out_rate"|"customer_request"|"other")} params.reasonCode - Why it is being revoked
+				 * @param {string} params.reason - Free-text reason shown to the customer
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if a required parameter is missing
+				 * @returns {Promise<SdkResponse<any>>} - `{ attestation }` (status "revoked", revokedByType "signalhouse_admin")
+				 */
+				revokeAttestationById: async ({ id, reasonCode, reason, options = {} }) => {
+					this.client._require({ id, reasonCode, reason });
+					return this.client(`/dnc/attestations/${encodeURIComponent(id)}/revoke`, { method: "POST", body: { reasonCode, reason }, ...options });
+				},
+			};
+		}
+	}
+}