@signalhousellc/sdk 1.4.3 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalhousellc/sdk",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "description": "Signal House SDK for use with the Signal House platform",
   "type": "module",
   "main": "src/SignalHouseSDK.js",

package/src/domains/Brands.js

@@ -80,6 +80,29 @@
  * @property {string} [businessWebsite] - The customer's real website, sent to Infobip for brand verification (optional, valid URL, at most 255 characters; distinct from the top-level website / landing URL)
  */
 
+/**
+ * @typedef {Object} BusinessVerificationDetails
+ * @property {string} businessName - The legal business name (required, at most 255 characters)
+ * @property {string} businessType - The business type (required, one of CO_OPERATIVE, CORPORATION, LIMITED_LIABILITY_CORPORATION, NON_PROFIT_CORPORATION, PARTNERSHIP)
+ * @property {string} industry - The business industry (required, one of AGRICULTURE, AUTOMOTIVE, BANKING, CONSTRUCTION, CONSUMER, EDUCATION, ELECTRONICS, ENGINEERING, ENERGY, FAST_MOVING_CONSUMER_GOODS, FINANCIAL, FINTECH, FOOD_AND_BEVERAGE, GOVERNMENT, HEALTHCARE, HOSPITALITY, INSURANCE, JEWELRY, LEGAL, MANUFACTURING, MEDIA, NOT_FOR_PROFIT, OIL_AND_GAS, ONLINE, PROFESSIONAL_SERVICES, RAW_MATERIALS, REAL_ESTATE, RELIGION, RETAIL, TECHNOLOGY, TELECOMMUNICATIONS, TRANSPORTATION, TRAVEL)
+ * @property {string} registrationType - The business registration type (required, one of EIN, CBN, NEQ, PROVINCIAL_NUMBER, CRN, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST_IDNR, CIF, NIF, CNPJ, UID, OTHER)
+ * @property {string} registrationNumber - The business registration number, e.g. the EIN (required, at most 50 characters)
+ * @property {string} website - The business website (required, valid URL, at most 255 characters)
+ * @property {string} street - The business street address (required, at most 255 characters)
+ * @property {string} [street2] - The second line of the street address (optional, at most 255 characters)
+ * @property {string} city - The business city (required, at most 100 characters)
+ * @property {string} state - The business state or province (required, 2-letter code)
+ * @property {string} postalCode - The business postal code (required, at most 10 characters)
+ * @property {string} country - The business country (required, "US" or "CA")
+ * @property {Object} representative - The business's authorized representative (required)
+ * @property {string} representative.firstName - The representative's first name (required, at most 100 characters)
+ * @property {string} representative.lastName - The representative's last name (required, at most 100 characters)
+ * @property {string} representative.email - The representative's email address (required, valid email, at most 100 characters)
+ * @property {string} representative.phone - The representative's phone number (required, E.164 with an optional leading "+" and no spaces, parentheses or hyphens, e.g. "+17025550100")
+ * @property {string} representative.jobTitle - The representative's job title (required, at most 100 characters)
+ * @property {string} representative.jobLevel - The representative's job level (required, one of DIRECTOR, GM, VP, CEO, CFO, GENERAL_COUNSEL, OTHER)
+ */
+
 /**
  * @typedef {Object} CreateTollFreeBrandData
  * @property {string} subgroupId - The ID of the subgroup to create the brand under (required, exactly 8 characters)
@@ -140,6 +163,7 @@ export class Brands {
    * @param {number} [params.limit] - The number of items per page
    * @param {string} [params.status] - The status of the brand to filter by (PENDING_CREATION, PENDING_APPROVAL, UNVERIFIED, VERIFIED, VETTED_VERIFIED, PENDING_DELETE, DELETED)
    * @param {string} [params.registrationType] - Filter by registration type ("TEN_DLC", "TOLL_FREE", or "SHORT_CODE")
+   * @param {boolean} [params.currentTollFreeCarrier] - With subgroupId or groupId: when true, return only toll-free brands that a new toll-free campaign in that group can use (those on the group's current toll-free carrier)
    * @param {string} [params.search] - Staff-only (no id/subgroupId/groupId): case-insensitive substring over brandId, names, EIN, email, group, subgroup and reference ID
    * @param {string} [params.sortBy] - Staff-only: createdAt, brandId, displayName, groupId, subgroupId, status, entityType or country
    * @param {"asc"|"desc"} [params.sortOrder] - Staff-only: sort direction (default asc)
@@ -153,7 +177,7 @@ export class Brands {
    * @param {boolean} [params.excludeDeleted] - Staff-only: hide DELETED brands when no status is given
    * @param {boolean} [params.includeTotal] - Staff-only: with page and limit, return `{ data, total, page, limit, totalPages }` instead of the array
    * @param {RequestOptions} [params.options] - Additional options for the request
-   * @returns {Promise<SdkResponse<Array<{ _id: string, brandId: string|null, status: string, registrationType: string, [key: string]: any }>|{ data: Array<Object>, total: number, page: number, limit: number, totalPages: number }>>} Brand records. For 10DLC brands in PENDING_CREATION (or rejected before carrier assignment), brandId is null — poll by _id until status advances and brandId is assigned. The staff-only list (no id/subgroupId/groupId) returns the `{ data, total, page, limit, totalPages }` envelope only when includeTotal is sent with page and limit.
+   * @returns {Promise<SdkResponse<Array<{ _id: string, brandId: string|null, status: string, registrationType: string, tollFree?: { isBrandReady?: boolean, maxNumbersPerCampaign?: number, maxOptInMethods?: number, requiresPrivacyPolicy?: boolean, requiresTermsAndConditions?: boolean, maxAppealReasonLength?: number, labelsSamples?: boolean, supportsMms?: boolean, usesBusinessVerification?: boolean, [key: string]: any }, [key: string]: any }>|{ data: Array<Object>, total: number, page: number, limit: number, totalPages: number }>>} Brand records. For 10DLC brands in PENDING_CREATION (or rejected before carrier assignment), brandId is null — poll by _id until status advances and brandId is assigned. Toll-free brands carry `tollFree.isBrandReady` (whether the brand can host campaigns), `tollFree.maxNumbersPerCampaign` (the most numbers one of its campaigns can hold), `tollFree.maxOptInMethods` (the most opt-in methods one of its campaigns can declare), `tollFree.requiresPrivacyPolicy` (whether its campaigns need a privacy policy URL), `tollFree.requiresTermsAndConditions` (whether its campaigns need a terms and conditions URL), `tollFree.maxAppealReasonLength` (the longest appeal reason its campaigns may give), `tollFree.labelsSamples` (whether its campaigns' sample messages each start with their use case's name), `tollFree.supportsMms` (whether its numbers can send MMS and group messages) and `tollFree.usesBusinessVerification` (whether it waits on the group's business verification). The staff-only list (no id/subgroupId/groupId) returns the `{ data, total, page, limit, totalPages }` envelope only when includeTotal is sent with page and limit.
    */
   async getBrands({
     id,
@@ -163,6 +187,7 @@ export class Brands {
     limit,
     status,
     registrationType,
+    currentTollFreeCarrier,
     search,
     sortBy,
     sortOrder,
@@ -185,6 +210,7 @@ export class Brands {
       limit,
       status,
       registrationType,
+      currentTollFreeCarrier,
       search,
       sortBy,
       sortOrder,
@@ -248,6 +274,38 @@ export class Brands {
     return this.client(`/brand/toll-free`, { method: 'POST', body: brandData, ...options });
   }
 
+  /**
+   * Get a group's business verification: whether its toll-free brands need one, its status and the submitted details.
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters for getting the business verification
+   * @param {string} params.groupId - The ID of the group whose business verification to get
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the groupId parameter is missing
+   * @returns {Promise<SdkResponse<{ groupId: string, required: boolean, status: string, details: BusinessVerificationDetails|null, submittedAt: string|null, reviewedAt: string|null, rejectionReason: string|null }>>} The group's business verification. `required` says whether the group's new toll-free brands need one; `status` is NOT_STARTED, SUBMITTING, IN_REVIEW, VERIFIED or NEEDS_CHANGES; `rejectionReason` says why it needs changes, or is null. When `required` is true and `status` is NOT_STARTED, submit it before creating the group's first toll-free brand.
+   */
+  async getBusinessVerification({ groupId, options = {} }) {
+    this.client._require({ groupId });
+    return this.client(`/brand/business-verification/${encodeURIComponent(groupId)}`, { method: 'GET', ...options });
+  }
+
+  /**
+   * Submit or update a group's business verification. Allowed when it is not started or needs changes. Review usually
+   * takes 1–2 business days; the group's toll-free brands stay pending until it is verified.
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters for submitting the business verification
+   * @param {string} params.groupId - The ID of the group whose business verification to submit (must be the caller's active group)
+   * @param {BusinessVerificationDetails} params.details - The business verification details (see BusinessVerificationDetails typedef for details)
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the groupId or details parameter is missing
+   * @returns {Promise<SdkResponse<{ groupId: string, required: boolean, status: string, details: BusinessVerificationDetails|null, submittedAt: string|null, reviewedAt: string|null, rejectionReason: string|null }>>} A 202 with the group's business verification, now SUBMITTING (the same shape as getBusinessVerification).
+   */
+  async submitBusinessVerification({ groupId, details, options = {} }) {
+    this.client._require({ groupId, details });
+    return this.client(`/brand/business-verification/${encodeURIComponent(groupId)}`, { method: 'PUT', body: details, ...options });
+  }
+
   /**
    * Create a local Short Code brand for manual Signal House review.
    * @async

package/src/domains/Campaigns.js

@@ -96,7 +96,7 @@
  * @property {TollFreeOptIn} [optIns.keyword] - Keyword opt-in details
  * @property {TollFreeOptIn} [optIns.interactiveVoiceResponse] - IVR opt-in details
  * @property {string} [multiNumberReason] - Internally-stored reason the customer requested more than one Toll-Free number on the campaign (optional, at most 500 characters). Required when more than one phone number is assigned; captured for Signal House review only and never sent to the carrier.
- * @property {string[]} [useCases] - The sender's real use-case picks (optional). `useCase` above carries the single value the carrier accepts (MIXED when there is more than one); these are what a Signal House landing page renders a consent checkbox per. Never forwarded to the carrier.
+ * @property {string[]} [useCases] - The sender's real use-case picks (optional). `useCase` above carries the single value the carrier accepts (MIXED when there is more than one); these are what a Signal House landing page renders a consent checkbox per. Carriers that need specific use cases rather than MIXED take them from here when present; other carriers never receive them.
  * @property {string[]} [channels] - The channels consent covers ("SMS", "MMS", "VOICE") (optional). Never forwarded to the carrier.
  * @property {string} [landingId] - The Signal House landing page whose consent boxes this campaign's call-to-action describes (optional). Must be an ACTIVE page owned by the same brand and group.
  */
@@ -105,11 +105,11 @@
  * @typedef {Object} CreateTollFreeCampaignData
  * @property {string} brandId - The ID of the Toll-Free brand associated with the campaign (required, at least 7 characters)
  * @property {TollFreeCampaignDetails} tollFree - The Toll-Free campaign details (required)
- * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy (optional, at most 2048 characters)
- * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions (optional, at most 2048 characters)
+ * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy (at most 2048 characters). Required when the brand's `tollFree.requiresPrivacyPolicy` is true and the brand has no `privacyPolicyLink` of its own; optional otherwise.
+ * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions (at most 2048 characters). Required when the brand's `tollFree.requiresTermsAndConditions` is true and the brand has no `termsAndConditionsLink` of its own; optional otherwise.
  * @property {string} [tag] - A tag for the campaign (optional, at most 255 characters)
  * @property {boolean} [autoRenewal=true] - Whether the campaign should auto-renew (optional, defaults to true)
- * @property {Array<string>} phoneNumbers - The Toll-Free numbers to assign to the campaign (required, at least 1 and at most 5, each at least 10 digits and digits only). Numbers are locked to the campaign once assigned and cannot be moved or added afterward.
+ * @property {Array<string>} phoneNumbers - The Toll-Free numbers to assign to the campaign (required, 1 up to the brand's tollFree.maxNumbersPerCampaign and at most 5, each at least 10 digits and digits only). The numbers must be on the brand's toll-free carrier, or the campaign is refused. Numbers are locked to the campaign once assigned and cannot be moved or added afterward.
  */
 
 /**

package/src/domains/Messages.js

@@ -108,8 +108,10 @@ export class Messages {
 
 	/**
 	 * Fetch the latest upstream carrier delivery report for a set of messages by ID (SHGHL-1856).
-	 * Useful for reconciling messages stuck in a non-terminal state. SMS and MMS messages are looked up
-	 * against the carrier; other message types are returned with their stored status.
+	 * Useful for reconciling messages stuck in a non-terminal state. Outbound SMS and MMS messages sent from numbers on
+	 * the carrier whose delivery logs we read are looked up there (the logs are kept about 48 hours); every other message,
+	 * including P2P messages and messages sent from numbers on other carriers, is returned with its stored status and
+	 * upstreamReportAvailable false. The request fails with a 500 when the sending numbers can't be read.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for fetching delivery reports

package/src/domains/Numbers.js

@@ -81,6 +81,7 @@ export class Numbers {
    * @param {string} [params.brandId] - Filter by brand ID
    * @param {string} [params.subgroupId] - Filter by subgroup ID
    * @param {string} [params.groupId] - Filter by group ID
+   * @param {boolean} [params.currentTollFreeCarrier] - With subgroupId or groupId: when true, return only toll-free numbers that a new toll-free campaign in that group can use (those on the group's current toll-free carrier)
    * @param {number} [params.page] - The page number for pagination (default: 1)
    * @param {number} [params.limit] - The number of items per page for pagination (default: 20)
    * @param {RequestOptions} [params.options] - Additional options for the request
@@ -103,8 +104,8 @@ export class Numbers {
    * or GET /campaign/health.
    * @returns {Promise<SdkResponse<any>>} A promise that resolves to the list of phone numbers
    */
-  async getPhoneNumbers({ phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, page, limit, options = {} }) {
-    const filters = { phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, page, limit };
+  async getPhoneNumbers({ phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, currentTollFreeCarrier, page, limit, options = {} }) {
+    const filters = { phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, currentTollFreeCarrier, page, limit };
     const queryString = this.client._getQueryString(filters);
     return this.client(`/number${queryString}`, { method: 'GET', ...options });
   }
@@ -261,14 +262,18 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for reading the order status
    * @param {string} params.orderId - The order id returned by `purchaseTollFreeNumbers`
+   * @param {string} [params.groupId] - Staff and service callers only: the order's group, whose carrier the read follows.
+   *   Their tokens carry no active group; every other caller's order is read by its active group, so a well-formed
+   *   groupId is ignored and a malformed one gets a 400.
    * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the orderId parameter is missing
    * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ orderId, counts: { ready, provisioning, failed }, failures: [{ reason }], numbers: string[] }`.
    */
-  async getTollFreeOrderStatus({ orderId, options = {} }) {
+  async getTollFreeOrderStatus({ orderId, groupId, options = {} }) {
     this.client._require({ orderId });
     const safeOrderId = encodeURIComponent(orderId);
-    return this.client(`/number/toll-free/order/${safeOrderId}`, { method: 'GET', ...options });
+    const queryString = this.client._getQueryString({ groupId });
+    return this.client(`/number/toll-free/order/${safeOrderId}${queryString}`, { method: 'GET', ...options });
   }
 
   /**
@@ -298,6 +303,60 @@ export class Numbers {
     });
   }
 
+  /**
+   * Get a phone number's outbound caller name (CNAM) - the name US carriers show for calls from it
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters for the request
+   * @param {string} params.phoneNumber - The phone number (E.164, leading + optional)
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the phoneNumber parameter is missing
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, cnam, autoApply, eligible, ineligibleReason }`
+   */
+  async getCallerName({ phoneNumber, options = {} }) {
+    this.client._require({ phoneNumber });
+    const safePhoneNumber = encodeURIComponent(phoneNumber);
+    return this.client(`/number/${safePhoneNumber}/cnam`, { method: 'GET', ...options });
+  }
+
+  /**
+   * Set a phone number's outbound caller name (CNAM). The name may only remove characters from the
+   * registered name of the number's brand (its campaign's brand, else `brandId`, else the subgroup's
+   * default caller-ID brand), and must be 1-15 letters, digits, spaces, `-` or `_`.
+   * @async
+   * @roles api, admin, developer
+   * @param {Object} params - The parameters for the request
+   * @param {string} params.phoneNumber - The phone number (E.164, leading + optional)
+   * @param {string} params.name - The caller name to show
+   * @param {string} [params.brandId] - The verified brand the name comes from; only for numbers with no campaign
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the phoneNumber or name parameter is missing
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, cnam, autoApply, eligible, ineligibleReason }`
+   */
+  async setCallerName({ phoneNumber, name, brandId, options = {} }) {
+    this.client._require({ phoneNumber, name });
+    const safePhoneNumber = encodeURIComponent(phoneNumber);
+    const body = brandId ? { name, brandId } : { name };
+    return this.client(`/number/${safePhoneNumber}/cnam`, { method: 'PUT', body, ...options });
+  }
+
+  /**
+   * Remove a phone number's own caller name (CNAM). If its subgroup has caller name auto-apply on, the
+   * number goes back to the automatic name.
+   * @async
+   * @roles api, admin, developer
+   * @param {Object} params - The parameters for the request
+   * @param {string} params.phoneNumber - The phone number (E.164, leading + optional)
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the phoneNumber parameter is missing
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, cnam, autoApply, eligible, ineligibleReason }`
+   */
+  async deleteCallerName({ phoneNumber, options = {} }) {
+    this.client._require({ phoneNumber });
+    const safePhoneNumber = encodeURIComponent(phoneNumber);
+    return this.client(`/number/${safePhoneNumber}/cnam`, { method: 'DELETE', ...options });
+  }
+
   /**
    * Submit a port-in request for one or more phone numbers from another provider
    * @async
@@ -371,7 +430,9 @@ export class Numbers {
    * Numbers that are not found, already RELEASED, currently being released (transient PENDING_RELEASE
    * status), already assigned to a different campaign, on a mismatched DCA, or (for a 10DLC campaign
    * without a number pool) beyond the remaining 49-number-per-campaign limit are not queued - each is
-   * reported back individually in `skipped` instead of failing the whole request.
+   * reported back individually in `skipped` instead of failing the whole request. A Toll-Free campaign
+   * whose brand reports `tollFree.maxNumbersPerCampaign` as 1 holds one number: a request that would give
+   * it a second is refused with a 400 and nothing is queued.
    * @async
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for assigning phone numbers to a campaign

package/src/domains/Onboarding.js

@@ -40,6 +40,24 @@ export class Onboarding {
 					return this.client(`/group/onboarding/${safeGroupId}`, { method: "GET", ...options });
 				},
 
+				/**
+				 * Set where a group's new toll-free brands and numbers go (`infobip` or `twilio`). Staff-only. Existing brands,
+				 * numbers and campaigns stay where they are.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params
+				 * @param {string} params.groupId - The group ID whose toll-free provider to set
+				 * @param {string} params.tollFreeProvider - The toll-free provider for the group's new toll-free brands and numbers ("infobip" or "twilio")
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if the groupId or tollFreeProvider parameter is missing
+				 * @returns {Promise<SdkResponse<any>>} - The updated onboarding record
+				 */
+				setTollFreeProvider: async ({ groupId, tollFreeProvider, options = {} }) => {
+					this.client._require({ groupId, tollFreeProvider });
+					const safeGroupId = encodeURIComponent(groupId);
+					return this.client(`/group/onboarding/${safeGroupId}/toll-free-provider`, { method: "PUT", body: { tollFreeProvider }, ...options });
+				},
+
 				/**
 				 * Add an internal comment/note to a group's admin Pricing editor. Staff-only.
 				 * @async

package/src/domains/Subgroups.js

@@ -40,6 +40,8 @@
  * @property {string} [status] - The status of the subgroup (e.g., "active", "inactive")
  * @property {string} [carrierIdFamily] - Optional agency-managed carrier ID selection ("Default", "ATT", "TMobile", "Verizon", "USCellular", "GoogleVoice", "ClearSky", "Interop"). Setting this field requires signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, or billing role.
  * @property {string|null} [carrierIdRegion] - Optional ClearSky region ("PRClaro", "GuamDocomo", "GuamGTA", "GuamITE") or null; only valid when carrierIdFamily is "ClearSky". Setting this field requires signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, or billing role.
+ * @property {boolean} [cnamAutoApply] - Turn caller name (CNAM) auto-apply on or off: eligible numbers get their brand's registered name as the name shown on outbound calls. Requires signalhouse_api, signalhouse_admin, signalhouse_user, api, admin or developer role.
+ * @property {string|null} [cnamBrandId] - Default caller-ID brand for numbers with no campaign (e.g. voice-only). Must be a verified brand in this subgroup; required when turning auto-apply on in a subgroup with more than one verified brand.
  */
 
 export class Subgroups {

package/src/domains/Webhooks.js

@@ -43,6 +43,10 @@ export class Webhooks {
 	 * `verifyWebhookSignature` from `@signalhousellc/sdk/webhooks` (Node only). `webhookData.authType` is one of
 	 * `NONE` (default), `BASIC`, `API_KEY`, `OAUTH2` or `HMAC`; `HMAC` (SHGHL-3595) sends no credentials, so the
 	 * receiver authenticates by the signature alone, and must be sent without `credentials` or `apiHeaderPrefix`.
+	 * `webhookData.eventSettings` (SHGHL-3884) holds per-event options keyed by event name:
+	 * `NUMBER_HEALTH_BELOW_THRESHOLD` and `CAMPAIGN_HEALTH_BELOW_THRESHOLD` each take `{ threshold }`, the 7-day
+	 * health score (1.5–10, in 0.5 steps) below which the event fires; a subscribed health event without one is
+	 * stored with the default, 6.
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for creating a webhook
@@ -62,7 +66,9 @@ export class Webhooks {
 	 * to change the endpoint's own credentials in place: credentials are required when switching to an auth
 	 * type that needs them, and omitted credentials keep the stored ones. Switching to `NONE` or `HMAC` clears
 	 * the stored credentials; `HMAC` is rejected for an endpoint with no signing secret (call
-	 * `rotateWebhookSecret` first). Like every read of a webhook, the
+	 * `rotateWebhookSecret` first). `updateData.eventSettings` changes per-event options by event name
+	 * (`{ NUMBER_HEALTH_BELOW_THRESHOLD: { threshold } }`, `{ CAMPAIGN_HEALTH_BELOW_THRESHOLD: { threshold } }`,
+	 * 1.5–10 in 0.5 steps); events you omit keep their stored settings. Like every read of a webhook, the
 	 * response carries `hasSigningSecret` and `hasCredentials` (booleans), never a secret or credential.
 	 * @async
 	 * @roles api, admin, developer