@signalhousellc/sdk 1.0.68 → 1.0.69

package/README.md

@@ -55,13 +55,3 @@ For full API reference and advanced usage, visit https://api.signalhouse.io
 
 License
 ISC © Signal House
-
-
-### Geographic availability search
-
-The availability path supports optional `city` as a case-insensitive prefix within an explicit `country` (`CA` or `US`) and `state` (province/state code). City must be supplied with both country and state. Example: `getAvailablePhoneNumbers({ country: "CA", state: "QC", city: "Charny", npa: "367", nxx: "883", limit: 10 })`. Canadian province, city, NPA and NXX matches are checked before the result limit; unrelated substring matches are excluded. Availability may change before purchase.
-
-
-Canadian message estimates return per-recipient `phoneNumber`, `rate`, `amount` and `fallback`, plus segment count and total in microdollars. They use cached carrier information without exposing carrier names or making a paid lookup. Rates remain 75,500 for standard carriers and 81,000 for Ice Wireless/Iristel or unresolved carriers; MMS/group MMS use one segment per recipient.
-
-Available-number searches return `{ numbers, numberCount? }`. `numberCount` is omitted when the total is unknown, including Canadian geographic and US city searches; the page length is not a total. These filtered searches have a 20-second discovery deadline and return HTTP 503 when incomplete. Narrow the location/NPA/NXX or retry later. Successful Infobip samples may be cached for 15 seconds across pages; purchase rechecks availability.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@signalhousellc/sdk",
-  "version": "1.0.68",
+  "version": "1.0.69",
   "description": "Signal House SDK for use with the Signal House platform",
   "type": "module",
   "main": "src/SignalHouseSDK.js",
   "exports": {
     ".": "./src/SignalHouseSDK.js",
-    "./voice-browser": "./src/domains/voice/browser/index.js"
+    "./voice-browser": "./src/domains/voice/browser/index.js",
+    "./webhooks": "./src/webhooks/verifySignature.js"
   },
   "files": [
     "src/",

package/skills/VENDORED.json

@@ -1,6 +1,6 @@
 {
   "source": "https://github.com/bonzo-signalhouse/agent-skills.git",
-  "ref": "v0.2.0",
+  "ref": "v0.3.0",
   "skills": [
     "signalhouse-10dlc",
     "signalhouse-advisor",
@@ -10,13 +10,13 @@
     "signalhouse-webhooks"
   ],
   "files": {
-    "signalhouse-10dlc/SKILL.md": "b10ed2f759edcfcc9099c56285341ff0fbc9c131b2fd4b2d47922067128e79c2",
+    "signalhouse-10dlc/SKILL.md": "6a46fddf1572b39849c07855c6ece3d3499c711e5ffa6f466d73ab54182fd49f",
     "signalhouse-10dlc/examples/brightsmile-onboarding.md": "b5c04a551bc918f2563f1d1e59e516cf2e60fa7233490e3312a92dd1d1e9d473",
-    "signalhouse-10dlc/references/tcr-rejection-causes.md": "8347a1656035626e0fc77dca49a0d06800e077ec8a4dc6e7e89208d90e8aeb2f",
-    "signalhouse-advisor/SKILL.md": "9e3542f4b8c56474db4167535b2310432456bf935578a160a255b8a7d84d7738",
-    "signalhouse-numbers/SKILL.md": "47ebcd18cb0bda80ebfefa1165540117c4712691356d602c76ab9e29a69c6626",
-    "signalhouse-setup/SKILL.md": "0e3743d9a6adf8516d0d194c952090af2875605c82d3a397c58e49e0f4d56cde",
-    "signalhouse-sms/SKILL.md": "e40c5a9da90c2ba75a34de8f5048b2cde3f202f6eb44067352dd32fce8988ce5",
-    "signalhouse-webhooks/SKILL.md": "2b47468bcdc581b32b3697fcaab05b1fd16e279e139c915d83ceed1ce1ddd57f"
+    "signalhouse-10dlc/references/tcr-rejection-causes.md": "312d754c55dfdf8e21d085724728ae4b2288d7b485fba1c61c78f94a42780e8c",
+    "signalhouse-advisor/SKILL.md": "5e5070dc4742a1fe0195989471f809170c30fd7d8f63c33e4778215a2a446146",
+    "signalhouse-numbers/SKILL.md": "f996be53809ea2f90e49b32452f162eeff5369056e1f63e422b8fdb46d2896ff",
+    "signalhouse-setup/SKILL.md": "ca87a6d71f3f82614b83ad283971385fc55c13c097b76595b1b85def235373ec",
+    "signalhouse-sms/SKILL.md": "ec7ed8985ad590b0ab5d40c9ddb003eb8cbc566a1309ac5e330f570e0404ec42",
+    "signalhouse-webhooks/SKILL.md": "d16062e9e0a7cdda3c02aee485bd5114659405d00b1d635da1280db0179490a7"
   }
 }

package/skills/signalhouse-10dlc/SKILL.md

@@ -84,17 +84,13 @@ The two with constrained values, which is where callers get stuck:
 | Field | Values |
 |---|---|
 | `entityType` | `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT` |
-| `vertical` | one of 23 industry values: `PROFESSIONAL`, `REAL_ESTATE`, `HEALTHCARE`, `FINANCIAL`, `TECHNOLOGY`, `RETAIL` and so on. Do not guess; read the list from the registration guide. |
+| `vertical` | one of 23 industry values: `PROFESSIONAL`, `REAL_ESTATE`, `HEALTHCARE`, `FINANCIAL`, `TECHNOLOGY`, `RETAIL` and so on. Do not guess; read the list from the Brands reference. |
 
 **`brandRelationship` is not a field you set.** The service overwrites it before validation runs,
 and every 10DLC brand ends up `MEDIUM_ACCOUNT` regardless of what was sent. Whatever a caller
 passes is discarded silently. Do not ask a customer to choose one, and do not report it back as
 something they selected.
 
-> ⚠️ The 10DLC Registration Guide's own required-fields table still lists `brandRelationship` as a
-> required, caller-chosen field. It is wrong on this point; `03-api-reference/02-brands.md` and
-> the service code agree that it is ignored. Tracked as **SHGHL-2946**.
-
 `PUBLIC_PROFIT` additionally requires `stockSymbol`, `stockExchange`, `website` and
 `businessContactEmail`.
 
@@ -166,11 +162,11 @@ Never state a current status, price, or throughput figure from memory. Read it:
 - **Whether a specific send will be allowed:** attempt it and read the error, or check campaign
   state first. There is no separate preflight endpoint.
 
-- **The full field lists, verticals, use cases, status meanings and worked examples:** the
-  internal 10DLC Registration Guide (`documentation/dev-documentation/07-10dlc-registration.md`)
-  and the published help-centre articles *10DLC Messaging Overview*, *10DLC Campaign Website
+- **The full field lists, verticals, use cases, status meanings and worked examples:** the Brands
+  and Campaigns references (https://app2.signalhouse.io/docs/brands,
+  https://app2.signalhouse.io/docs/campaigns) and the published help-centre articles *10DLC Messaging Overview*, *10DLC Campaign Website
   Review* and *10DLC Campaign Approvals*. This skill is a condensed guardrail, not a substitute
-  for them. Where it and the guide disagree, the guide wins and this file is the bug.
+  for them. Where it and the references disagree, the references win and this file is the bug.
 
 The platform enforces every constraint on this page. This skill exists so an agent stops
 *before* a rejected registration or a failed send, not so it can predict the outcome.

package/skills/signalhouse-10dlc/references/tcr-rejection-causes.md

@@ -5,8 +5,7 @@ Loaded on demand, and only needed once something has actually been rejected.
 Every cause below is drawn from a **real Signal House support ticket** or verified against the
 API, with the source noted. Nothing here is general industry knowledge.
 
-> **Review status:** engineer-verified. Still needs the named business reviewer per
-> [CONTRIBUTING.md](../../../CONTRIBUTING.md), since this is compliance-bearing content.
+> **Review status:** engineer-verified against support tickets and the API.
 
 ## How to read a rejection
 
@@ -43,9 +42,10 @@ Two distinct real causes share this code.
 **`Invalid sub-usecases: SOCIAL`.** `SOCIAL` is not a valid sub-use-case under any parent,
 neither `LOW_VOLUME` nor `MIXED`. Valid sub-use-cases for `LOW_VOLUME` are
 `ACCOUNT_NOTIFICATION`, `CUSTOMER_CARE`, `DELIVERY_NOTIFICATION`, `MARKETING`. Signal House's own
-validation now rejects `SOCIAL` as a `subUsecases` value with an immediate 400 before the request
-ever reaches TCR (SHGHL-2943), so this specific 501 should no longer be reachable through the
-API — `SOCIAL` is still a valid top-level `usecase`, just never a sub-use-case.
+validation now rejects `SOCIAL` as a `subUsecases` value with an immediate 400, before the request
+reaches TCR, so this 501 should no longer be reachable through the API. `SOCIAL` is still a valid
+top-level `usecase`, just never a sub-use-case. If an older campaign carries this rejection,
+resubmit with `SOCIAL` removed from `subUsecases`.
 
 **Punctuation in a tag.** A tag of `maria-answers` was rejected for containing a hyphen. The
 campaign content was fine. Fix the tag (`mariaanswers`), then the campaign has to be
@@ -102,10 +102,3 @@ for `PENDING_REVIEW` / `REJECTED` / `TCR_REGISTER_FAILED` when the campaign is *
 at the moment it fails. This is deliberate, because those states are appealable and re-registerable,
 but it means a customer who abandons failed campaigns keeps funds tied up. Deleting the dead
 campaign frees them.
-
-## Open questions for the business reviewer
-
-1. **The full valid sub-use-case set per parent use case.** Four are confirmed for `LOW_VOLUME`
-   from a support ticket (`ACCOUNT_NOTIFICATION`, `CUSTOMER_CARE`, `DELIVERY_NOTIFICATION`,
-   `MARKETING`). The complete mapping should come from TCR's own documentation rather than being
-   inferred from the tickets we happen to have.

package/skills/signalhouse-advisor/SKILL.md

@@ -78,7 +78,7 @@ constraint is nearly always the part that changes the plan.
 
 ## Where to look it up
 
-- **The full setup pipeline in one place:** the internal 10DLC Registration guide
-  (`documentation/dev-documentation/07-10dlc-registration.md`).
-- **A first working call:** the Quickstart (`01-quickstart.md`).
+- **The full setup pipeline:** the Brands and Campaigns references
+  (https://app2.signalhouse.io/docs/brands, https://app2.signalhouse.io/docs/campaigns).
+- **A first working call:** https://app2.signalhouse.io/docs/getting-started.
 - **Current fees and balance:** the billing endpoints, read live, per group.

package/skills/signalhouse-numbers/SKILL.md

@@ -76,8 +76,7 @@ cost".
 ## Where to look it up
 
 - **Search filters, NPA/NXX lookup, friendly names, per-number inbound webhook URLs, and the
-  release semantics:** the internal Number Management Guide
-  (`documentation/dev-documentation/06-number-management.md`).
+  release semantics:** the Numbers reference, https://app2.signalhouse.io/docs/numbers.
 - **Current fees:** `GET /billing/fees/:groupId`.
 - **Current balance before a bulk buy:** the wallet endpoints under `/billing/wallet`.
 - **Whether a number can send:** its campaign's state, not the number's. See `signalhouse-10dlc`.

package/skills/signalhouse-setup/SKILL.md

@@ -4,8 +4,9 @@ description: >-
   Getting a Signal House integration authenticated and wired: login vs service-user tokens, what a
   token is scoped to, SDK initialization, and why webhooks come before the first write.
   TRIGGER when the user is starting a Signal House integration, asks how to authenticate, asks for
-  an API key or token, is choosing a base URL, is installing or initializing the SDK, is getting a
-  401 or 403, or asks why their token stopped working.
+  an API key or token, is choosing a base URL, is installing or initializing the SDK, is connecting
+  Claude, Cursor or another AI client to Signal House (MCP), is getting a 401 or 403, or asks why
+  their token stopped working.
   SKIP for message sending, 10DLC registration, number purchase and webhook event semantics, which
   have their own skills. This one ends at "the first authenticated call succeeds".
 ---
@@ -25,8 +26,8 @@ Authentication guide or the environment rather than quoting a number to a custom
 
 **A service user cannot be bootstrapped from nothing.** `POST /user/serviceuser` needs an existing
 group and a token that is already privileged enough to mint one. The first credential in a new
-integration comes from a human logging in or from Signal House provisioning it, not from an API call
-made with no credential.
+integration comes from a human logging in (including approving an OAuth connection, below) or from
+Signal House provisioning it, not from an API call made with no credential.
 
 **`role: "signalhouse_api"` is not available to customers.** The two roles `POST /user/serviceuser`
 accepts are `api` (customer key, scoped to one `groupId`) and `signalhouse_api` (internal, requires
@@ -62,6 +63,33 @@ on it. See `signalhouse-10dlc`.
    without webhooks discovers outcomes by polling, burns rate limit doing it, and still finds out
    late. See `signalhouse-webhooks`.
 
+## Connecting an AI client (MCP)
+
+Signal House runs a hosted MCP server at `https://mcp.signalhouse.io/mcp`. It holds no credentials
+of its own: every call is forwarded to the API with the caller's own token, so an agent can do
+exactly what that token can do and nothing more.
+
+- **Claude (web, Desktop, mobile): connect with OAuth.** Settings > Connectors > Add custom
+  connector, paste the URL, leave the client ID and secret blank, then log in to Signal House and
+  approve. No API key is copied anywhere. This is the path to recommend to a person.
+- **Clients configured by file or command (Claude Code, Cursor and similar):** send an API key as a
+  bearer header, e.g.
+  `claude mcp add --transport http signalhouse https://mcp.signalhouse.io/mcp --header "Authorization: Bearer <API key>"`.
+  Claude Code can also do the OAuth flow: add it without the header and authenticate from `/mcp`.
+
+What an OAuth connection can and cannot do:
+
+- **It acts as the user who approved it, with that user's full role.** Scopes are not enforced, so
+  do not tell a customer a connection is "read-only" or limited to part of the account.
+- **It cannot mint credentials or manage the login.** Routes under `/user` and `/auth` refuse a
+  connector token with a **403**, so an agent on an OAuth connection cannot create service users or
+  API keys. A 403 there is by design, not a bug to work around; create keys in the portal.
+- **It is revoked by the user**, in the portal under Settings > Security > Connected Applications.
+  After that the client has to reconnect.
+
+For an unattended server integration, the rules above still hold: use a service-user API key, not
+an OAuth connection, which exists for a person working through an AI client.
+
 ## Reading the response
 
 The SDK returns an **envelope**, and most failures arrive inside it rather than as an exception:
@@ -82,10 +110,12 @@ current shape from the API reference rather than assuming it matches a sibling e
 
 ## Where to look it up
 
-- **Auth flows, service users, the full role table, token practice:** the internal Authentication
-  guide (`documentation/dev-documentation/02-authentication.md`).
-- **First working call end to end:** the Quickstart (`01-quickstart.md`).
-- **Envelope shapes, error classes and status codes:** the Error Handling guide (`08-error-handling.md`).
-- **Backoff, batching and pagination:** the Rate Limits guide (`09-rate-limits.md`).
-- **What a role is allowed to do:** the role table in the Authentication guide. Roles are checked
-  server-side, so a plan that assumes more access than the token has fails at the call, not earlier.
+- **Auth flows, service users, the full role table, token practice:** the Authentication reference,
+  https://app2.signalhouse.io/docs/authentication.
+- **The OAuth connection flow:** https://app2.signalhouse.io/docs/oauth.
+- **First working call end to end:** https://app2.signalhouse.io/docs/getting-started.
+- **Envelope shapes, error classes and status codes:** https://app2.signalhouse.io/docs/error-handling.
+- **Backoff, batching and pagination:** https://app2.signalhouse.io/docs/rate-limits.
+- **What a role is allowed to do:** the role table in the Authentication reference. Roles are
+  checked server-side, so a plan that assumes more access than the token has fails at the call, not
+  earlier.

package/skills/signalhouse-sms/SKILL.md

@@ -73,9 +73,9 @@ is a 400, not an unbounded query. The API refuses rather than scanning.
 
 ## Where to look it up
 
-- **Every send parameter, the full status table and delivery receipts:** the internal Sending
-  Messages guide (`documentation/dev-documentation/05-sending-messages.md`).
+- **Every send parameter, message statuses and delivery receipts:** the Messages reference,
+  https://app2.signalhouse.io/docs/messages.
 - **Current per-group fees:** `GET /billing/fees/:groupId`.
-- **Failure codes and what is retryable:** the Error Handling guide (`08-error-handling.md`).
-- **Backoff and batching:** the Rate Limits guide (`09-rate-limits.md`).
+- **Failure codes and what is retryable:** https://app2.signalhouse.io/docs/error-handling.
+- **Backoff and batching:** https://app2.signalhouse.io/docs/rate-limits.
 - **Why a number cannot send yet:** `signalhouse-10dlc`.

package/skills/signalhouse-webhooks/SKILL.md

@@ -12,71 +12,90 @@ description: >-
 
 # Signal House webhooks
 
-## What cannot happen
+## What a receiver can verify
 
-**A receiver cannot verify that a webhook came from Signal House.** Payloads are **not signed**.
-There is no HMAC, no signature header, and no request timestamp. This is verified in the
-backend, not assumed.
+**Deliveries to a webhook endpoint are signed.** Every endpoint created with `POST /webhook` gets a
+signing secret, returned in plaintext **exactly once**, as `signingSecret` in that create response.
+Every later read reports only `hasSigningSecret: true|false`. Store the secret at creation; nothing
+can hand it back, and a lost secret means creating a new endpoint.
 
-The `authType` setting (`NONE`, `BASIC`, `API_KEY`, `OAUTH2`) authenticates *Signal House to the
-receiver's endpoint*. It is the opposite direction from a signature and gives the receiver
-nothing to check. Even with `BASIC` or `API_KEY`, the credential is a bearer secret sent *to*
-the receiver: it proves nothing about payload integrity and any captured request can be replayed.
+A signed delivery carries:
 
-Practical consequences a receiver has to design around:
+| Header | Value |
+|---|---|
+| `X-SignalHouse-Signature` | hex HMAC-SHA256, keyed with the signing secret, over `${timestamp}.${rawBody}` |
+| `X-SignalHouse-Timestamp` | the `timestamp` in that string: Unix time in **milliseconds** |
+| `X-SignalHouse-Delivery-Id` | a UUID for this event to this endpoint, the same on every retry |
+
+A correct verifier:
+
+1. **Uses the raw request body**, byte for byte, before any JSON parsing. Re-serializing a parsed
+   body changes whitespace and key order and the signature stops matching.
+2. **Recomputes the HMAC and compares in constant time.** The signature is bare hex, no prefix.
+3. **Rejects a stale timestamp.** The timestamp is inside the signed string, so a captured request
+   cannot be replayed with a fresh one. Pick a window (five minutes is common) and remember the
+   header is milliseconds, not seconds.
+4. **Rejects an unsigned request to an endpoint that has a secret.** Otherwise a forger simply
+   leaves the headers off.
+
+What is still **not** verifiable:
+
+- **Endpoints created before signing shipped (2026-09-03) are sent unsigned.** They report
+  `hasSigningSecret: false`, and there is no way to add a secret to an existing endpoint. To get
+  signing, create a new endpoint, store its secret, then delete the old one.
+- **Per-number inbound URLs are never signed** (see below).
 
-- **Do not treat an inbound webhook as authenticated.** Anyone who learns the URL can post to it.
-  With `authType: NONE` there is nothing stopping them at all.
-- **Never take a state-changing action on webhook content alone** where the action is
-  irreversible or financial. Treat the webhook as a *hint that something changed*, then read the
-  authoritative state back from the API before acting on it.
-- **Do not put secrets in the webhook URL** as a substitute for verification. It ends up in
-  proxy logs, browser history and support screenshots.
+For anything unsigned, the old rules still apply: do not treat the request as authenticated, and
+never take an irreversible or financial action on webhook content alone. Read the authoritative
+state back from the API first. Do not put secrets in a webhook URL as a substitute for
+verification; URLs end up in proxy logs and support screenshots.
 
-> ⚠️ Tracked as **SHGHL-2944**. Delete this section when signing ships. A workaround left in a
-> skill becomes permanent.
+The `authType` setting (`NONE`, `BASIC`, `API_KEY`, `OAUTH2`) is a different thing: it
+authenticates *Signal House to the receiver's endpoint*. The signature is what proves origin and
+integrity. `authType` is a second layer, not a substitute.
 
 ## Retry behaviour, and when an event is gone
 
-Delivery is a **direct HTTP POST with a 3-second timeout**, retried **3 times, 500 ms apart, with
-no backoff and no jitter**. It is not queued, so there is no queue-level redelivery behind it.
-Verified against the send path, which takes the retry defaults at every call site.
+Delivery is a **direct HTTP POST with a 3-second timeout**, made up to **3 times in total**. The
+waits between attempts back off exponentially with jitter: about 500 ms, then about 1 second
+(each up to 25% longer). It is not queued, so there is no queue-level redelivery behind it. Each
+attempt is signed afresh with a new timestamp and carries the **same** delivery id.
+
+What gets retried:
+
+- **Retried:** no response at all (network error, DNS failure, timeout), any **5xx**, and **429**.
+- **Not retried:** every other **4xx**. A receiver that answers 400, 401, 403 or 404 gets the
+  event once. So return a 4xx only for a request you will never accept (a bad signature, say), and
+  a 5xx or 429 for anything transient.
 
 Two numbers matter, and they are different things:
 
 - **A receiver has 3 seconds to respond.** Exceed it and the attempt is a failure, even if the
   work eventually succeeds on your side.
-- **The whole delivery window is about 10 seconds** worst case, three attempts that can each
-  burn the full timeout, plus 500 ms between them.
-
-- A receiver that is down, restarting, or rate-limited for even a minute **loses the event
-  permanently**. There is no dead-letter queue and no replay endpoint.
-- **4xx responses are retried too.** The HTTP client throws on any non-2xx and the retry
-  predicate accepts everything, so a receiver returning 400 gets the same doomed request three
-  times.
+- **The whole delivery window is about 11 seconds** worst case: three attempts that can each burn
+  the full timeout, plus the two waits.
+
+- A receiver that is down, restarting, or rate-limited for longer than that **loses the push for
+  that event**. There is no dead-letter queue and no replay endpoint.
 - A slow endpoint that exceeds 3 seconds and *then* completes its work has been recorded as a
-  failure and will be sent the **same event up to three times**, with no delivery id to key
-  idempotency on. This is the most likely duplicate scenario in practice.
+  failure and will be sent the **same event again**. Dedupe on `X-SignalHouse-Delivery-Id`.
 
 So a correct receiver:
 
 1. **Responds inside 3 seconds, and does the work afterwards.** Acknowledge, enqueue, process out
    of band. Any processing done before responding is spending a budget you do not control, and
    blowing it converts a successful handler into a duplicate delivery.
-2. **Is idempotent on the event's own identifiers** (message id, campaign id and status),
-   because there is no delivery id to dedupe on.
+2. **Is idempotent on `X-SignalHouse-Delivery-Id`**, which every delivery carries, signed or not,
+   including per-number inbound URLs.
 3. **Reconciles against `GET /notification`.** This is the important one. Every event that would
-   trigger a webhook also writes a **notification record, before endpoints are even looked up and
-   regardless of whether delivery succeeds**. It carries the same `{timestamp, event, identifier,
-   metaData}` shape and is filterable by group, status and event type.
+   trigger a group webhook also writes a **notification record, created before endpoints are even
+   looked up and independent of whether delivery succeeds**. It carries the same `{timestamp,
+   event, identifier, metaData}` shape and is filterable by group, status and event type.
 
    That makes it the durable record and the webhook merely the push. A receiver that must not
    miss anything polls it to catch up after any outage, which is the only reliable recovery,
    given there is no replay endpoint.
 
-> ⚠️ Also tracked as **SHGHL-2944**. If the retry policy changes, these numbers are wrong and
-> this section must be rewritten from the code, not adjusted from memory.
-
 ## Setting one up
 
 Webhooks are created per group, and numbers can additionally carry their own inbound URL.
@@ -90,27 +109,28 @@ Webhooks are created per group, and numbers can additionally carry their own inb
 | `API_KEY` | `key` holds the key; `secret` optional |
 | `OAUTH2` | `secret` is the access token sent as the Authorization value; `key` is required at create but unused in outgoing headers |
 
-`NONE` is the right default only for an endpoint that is already unreachable from the public
-internet. For anything else, pick a real `authType`. It is not verification, but it stops
-casual forgery.
+Verify the signature on every endpoint that has one. On top of that, `NONE` is fine for an
+endpoint that is already unreachable from the public internet; for anything else a real `authType`
+is cheap defense in depth.
 
 **The table above does not cover per-number inbound URLs.** A number can carry
 `primaryInboundWebhookUrl` and `secondaryInboundWebhookUrl`, and inbound messages are posted to
-both. That path sends **no auth headers at all**, whatever `authType` is configured elsewhere,
-it is always unauthenticated. Do not assume configuring auth on a group webhook protects the
-per-number ones; it does not. Treat those URLs as fully public and put nothing behind them that
-matters without an independent check.
+both. That path sends **no auth headers and no signature**, whatever is configured elsewhere: it has
+no endpoint record to hold a secret, so it is always unauthenticated. It does carry
+`X-SignalHouse-Delivery-Id`. Do not assume configuring a group webhook protects the per-number
+ones; it does not. Treat those URLs as fully public and put nothing behind them that matters
+without an independent check. If a number's inbound traffic needs verifying, route it through a
+signed group endpoint instead.
 
 ## Where to look it up
 
-- **Event types and payload shape:** the internal Webhooks Guide
-  (`documentation/dev-documentation/04-webhooks-guide.md`). The event list changes independently
-  of this skill; read it there rather than reciting it here. Note the guide does **not** document
-  the per-number `primaryInboundWebhookUrl` / `secondaryInboundWebhookUrl` fields described above.
+- **Event types, payload shape and the signing scheme:** the Webhooks reference,
+  https://app2.signalhouse.io/docs/webhooks. The event list changes independently of this skill;
+  read it there rather than reciting it here.
 - **Whether an event actually happened:** `GET /notification`
-  (`documentation/dev-documentation/03-api-reference/13-notifications.md`). The notification
-  record is written independently of delivery, so it is the record and the webhook is the push.
-- **Whether a delivery failed:** you largely cannot, from the outside or the inside. Failed group
-  and per-number deliveries are swallowed without a server-side log, so support may have no trace
-  of a delivery you never received. Do not design a process that depends on us being able to
-  confirm one.
+  (https://app2.signalhouse.io/docs/notifications). The notification record is written
+  independently of delivery, so it is the record and the webhook is the push.
+- **Whether a delivery failed:** Signal House logs every failed delivery with the group, the
+  endpoint, the event and the HTTP status your endpoint returned (or none, for a timeout), so
+  support can answer "did you get a 401 from us". There is still no API for a customer to list
+  failed deliveries or replay one, so do not design a process that depends on it.

package/src/SignalHouseSDK.js

@@ -29,6 +29,7 @@ import { Landings } from "./domains/Landings.js";
 import { Messages } from "./domains/Messages.js";
 import { Numbers } from "./domains/Numbers.js";
 import { Onboarding } from "./domains/Onboarding.js";
+import { Dnc } from "./domains/Dnc.js";
 import { Shortlinks } from "./domains/Shortlinks.js";
 import { Subgroups } from "./domains/Subgroups.js";
 import { Subscriptions } from "./domains/Subscriptions.js";
@@ -73,6 +74,7 @@ export class SignalHouseSDK {
 		this.messages = new Messages(client, multipartClient, this.enableAdmin);
 		this.numbers = new Numbers(client, multipartClient, this.enableAdmin);
 		this.onboarding = new Onboarding(client, this.enableAdmin);
+		this.dnc = new Dnc(client, this.enableAdmin);
 		this.shortlinks = new Shortlinks(client, this.enableAdmin);
 		this.subgroups = new Subgroups(client, this.enableAdmin);
 		this.subscriptions = new Subscriptions(client, this.enableAdmin);

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 });
+				},
+			};
+		}
+	}
+}

package/src/domains/Messages.js

@@ -12,7 +12,8 @@ export class Messages {
 	}
 
 	/**
-	 * Estimate Canadian SMS/MMS retail cost without sending or charging.
+	 * Estimate Canadian SMS/MMS retail cost; no charge or send. Requires a Ready Canadian sender and Canadian or US
+	 * recipients, and is unavailable unless Canada is enabled for the environment.
 	 * @async
 	 * @param {Object} params - Sender, up to 100 recipients, messageBody and request options.
 	 * @returns {Promise<SdkResponse<any>>} - Per-recipient rates and total in microdollars; unknown carriers use the upper fallback.
@@ -38,6 +39,7 @@ export class Messages {
 	 * @param {boolean} [params.matchAny] - When true, the provided campaignId/brandId/phoneNumber filters are OR'd (a message matches ANY of them) instead of the default most-specific-single behavior. subgroupId stays an AND scope. Opt-in/additive.
 	 * @param {string} [params.carrier] - Filter messages by the carrier used for sending
 	 * @param {string|string[]} [params.sentimentLabel] - Filter messages by sentiment bucket. Accepts a single value or an array (e.g. ["positive", "negative"]). Allowed values: positive, neutral, negative. Applied as the sentimentScore range the ±25 label threshold produces, so unscored messages match no bucket and outbound messages (never scored) are excluded.
+	 * @param {string|string[]} [params.errorCode] - Filter FAILED messages by Signal House error code (single value or array). "OUT" is the campaign opt-out, displayed as RECIPIENT_OPTED_OUT. Carrier codes are not filterable here; they live inside successOrFailureReason.
 	 * @param {string|string[]} [params.phoneNumber] - Filter messages by a business number on either side of the message. Accepts a single value or an array; OR'd with campaignId/brandId when matchAny is true
 	 * @param {string} [params.senderPhoneNumber] - Filter messages by the sender's 5-6 digit Short Code or 10+ digit phone number
 	 * @param {string} [params.recipientPhoneNumber] - Filter messages by the recipient's phone number
@@ -69,6 +71,7 @@ export class Messages {
 		matchAny,
 		carrier,
 		sentimentLabel,
+		errorCode,
 		startDate,
 		endDate,
 		sortField,
@@ -78,7 +81,7 @@ export class Messages {
 		dateBounds,
 		options = {},
 	}) {
-		const filters = { id, campaignId, brandId, subgroupId, groupId, phoneNumber, senderPhoneNumber, recipientPhoneNumber, status, direction, messageType, channel, matchAny, carrier, sentimentLabel, startDate, endDate, sortField, sortOrder, page, limit, dateBounds };
+		const filters = { id, campaignId, brandId, subgroupId, groupId, phoneNumber, senderPhoneNumber, recipientPhoneNumber, status, direction, messageType, channel, matchAny, carrier, sentimentLabel, errorCode, startDate, endDate, sortField, sortOrder, page, limit, dateBounds };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message${queryString}`, { method: "GET", ...options });
 	}
@@ -114,7 +117,7 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId] - Filter analytics by the ID of the associated campaign. Accepts a single value, an array, or a comma-separated string.
 	 * @param {string|string[]} [params.phoneNumber] - Filter analytics by the phone number involved in the messages. Accepts a single value, an array, or a comma-separated string.
 	 * @param {string|string[]} [params.carrier] - Filter analytics by the carrier used for sending. Accepts a single value, an array, or a comma-separated string.
-	 * @param {string|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
+	 * @param {string|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P, Standard, IceWireless). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {string} [params.startDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode
 	 * @param {string} [params.endDate] - ISO-8601 date or timestamp; bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode. In "exact" mode day buckets align to the UTC offset this bound carries, so a client that sends its own midnights gets its own calendar dates back
 	 * @param {boolean} [params.matchAny] - When true, the provided campaignId/brandId/phoneNumber filters are OR'd (match ANY) instead of the default most-specific-single behavior. subgroupId stays an AND scope. Opt-in/additive.
@@ -148,7 +151,7 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId] - Filter analytics by the ID of the associated campaign. Accepts a single value, an array, or a comma-separated string.
 	 * @param {string|string[]} [params.phoneNumber] - Filter analytics by the phone number involved in the messages. Accepts a single value, an array, or a comma-separated string.
 	 * @param {string|string[]} [params.carrier] - Filter analytics by the carrier used for sending. Accepts a single value, an array, or a comma-separated string.
-	 * @param {string|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
+	 * @param {string|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P, Standard, IceWireless). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {string} [params.startDate] - ISO-8601 date or timestamp. It is bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode, then floored to the start of its hour at either granularity, because the hourly cube is keyed by hour and a mid-hour start would drop that hour's bucket.
 	 * @param {string} [params.endDate] - ISO-8601 date or timestamp. At day granularity it is bound per dateBounds: a bare date is always that whole UTC day (inclusive); a timestamp is widened to its whole UTC day in "day" mode and bound as the instant it names, in whatever offset it was written, in "exact" mode. In "exact" mode day buckets align to the UTC offset this bound carries, so a client that sends its own midnights gets its own calendar dates back; at hour granularity it is honoured as given.
 	 * @param {(string|string[])} [params.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
@@ -226,7 +229,7 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId]
 	 * @param {string|string[]} [params.phoneNumber]
 	 * @param {string|string[]} [params.carrier]
-	 * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
+	 * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P, Standard, IceWireless); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {string} [params.startDate]
 	 * @param {string} [params.endDate]
 	 * @param {number} [params.page=1]
@@ -256,7 +259,7 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId]
 	 * @param {string|string[]} [params.phoneNumber]
 	 * @param {string|string[]} [params.carrier]
-	 * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
+	 * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P, Standard, IceWireless); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {string} [params.startDate]
 	 * @param {string} [params.endDate]
 	 * @param {number} [params.page=1]
@@ -288,7 +291,7 @@ export class Messages {
 	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, virtualLongCode, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
 	 * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
 	 * @param {RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the DNC analytics data (totals, byDate, byPhoneNumber, byCarrier, byKeyword). byKeyword breaks opt-outs down by the normalized keyword that revoked consent ({ optOutKeyword, total, sms, mms }); opt-outs recorded before keyword capture shipped appear as a single optOutKeyword: null bucket ("not recorded"). The distinct keyword set is open-ended (campaigns register their own keywords beyond the mandatory floor) — render top-N plus Other, never a fixed list.
+	 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the DNC analytics data (totals, byDate, byPhoneNumber, bySenderNumber, byCampaign, bySubgroup, byType, byCarrier, byKeyword). bySenderNumber ({ senderPhoneNumber, total, sms, mms }) attributes each opt-out to the first business number that received it, so it is unchanged by later campaign moves and START replies. byCampaign ({ campaignId, ... }) counts campaign-scoped opt-outs only, by the campaign at the time of the STOP; subgroup-scoped opt-outs (non-US recipients) are never attributed to a campaign and appear under bySubgroup ({ subgroupId, ... }) instead. byType ({ messageType, total }) splits SMS/MMS. byKeyword breaks opt-outs down by the normalized keyword that revoked consent ({ optOutKeyword, total, sms, mms }); opt-outs recorded before keyword capture shipped appear as a single optOutKeyword: null bucket ("not recorded"). The distinct keyword set is open-ended (campaigns register their own keywords beyond the mandatory floor) — render top-N plus Other, never a fixed list.
 	 */
 	async getDncAnalytics({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, dateBounds, options = {} }) {
 		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, dateBounds };
@@ -316,7 +319,7 @@ export class Messages {
 	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, virtualLongCode, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
 	 * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
 	 * @param {RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the paginated DNC records. Each record carries optOutKeyword — the normalized keyword that revoked consent (e.g. "stop", "opt out"; a repeat opt-out records the most recent word), null for opt-outs recorded before keyword capture shipped — and carrierFamily, the resolved carrier family of the recipient number (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile), copied from the inbound message that triggered the opt-out.
+	 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the paginated DNC records. Each record carries senderPhoneNumber — the first business number that received the opt-out (set once, never changed by a later STOP or a campaign move; the same value as phoneNumber) — optOutKeyword — the normalized keyword that revoked consent (e.g. "stop", "opt out"; a repeat opt-out records the most recent word), null for opt-outs recorded before keyword capture shipped — and carrierFamily, the resolved carrier family of the recipient number (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, Standard, IceWireless), copied from the inbound message that triggered the opt-out. campaignId is null on subgroup-scoped records (non-US recipients).
 	 */
 	async getDncRecords({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, sortField, sortOrder, channel, dateBounds, options = {} }) {
 		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, sortField, sortOrder, channel, dateBounds };

package/src/domains/Numbers.js

@@ -134,7 +134,7 @@ export class Numbers {
    * @param {boolean} [params.voiceEnabled] - Filter for phone numbers that are voice enabled
    * @param {string} [params.country] - Filter by country code (e.g., "US")
    * @param {string} [params.state] - Filter by state code (e.g., "CA")
-   * @param {string} [params.city] - City prefix; requires country US/CA and state/province.
+   * @param {string} [params.city] - City prefix; requires country US and state.
    * @param {string} [params.npa] - Filter by NPA (area code)
    * @param {string} [params.nxx] - Filter by NXX (central office code) - the first three digits of the local phone number after the area code
    * @param {string} [params.phoneNumber] - Filter by phone number
@@ -172,7 +172,7 @@ export class Numbers {
    * @param {Object} params - The parameters for purchasing phone numbers
    * @param {string[]} params.phoneNumbers - The list of phone numbers to purchase
    * @param {string} params.subgroupId - The ID of the subgroup to assign the purchased phone numbers to
-   * @param {'US'|'CA'} [params.country='US'] - ISO-2 purchase country. Toll-Free always uses the shared registry.
+   * @param {string} [params.country='US'] - ISO-2 purchase country; US.
    * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the phoneNumbers or subgroupId parameter is missing
    * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ message }` once the request is queued.
@@ -193,7 +193,7 @@ export class Numbers {
    * @param {Object} params - The parameters for purchasing toll-free numbers
    * @param {number} params.quantity - The number of toll-free numbers to purchase (1-10)
    * @param {string} params.subgroupId - The subgroup the purchased numbers are assigned to
-   * @param {'US'|'CA'} [params.country='US'] - ISO-2 purchase country. Toll-Free always uses the shared registry.
+   * @param {string} [params.country='US'] - ISO-2 purchase country; US.
    * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the quantity or subgroupId parameter is missing
    * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ message, orderId }` once the request is queued.

package/src/domains/Users.js

@@ -26,9 +26,11 @@
 
 /**
  * @typedef {Object} CreateServiceUserData
- * @property {string} groupId - The ID of the group to which the service user belongs (required)
+ * @property {string} groupId - The ID of the group to which the service user belongs (required for customer API keys)
  * @property {string} name - The name of the service user (required)
- * @property {string} role - The role of the service user (admin, developer, billing, user) (required)
+ * @property {string} role - The role of the service user: "api" for a customer API key (required)
+ * @property {string[]} [allowedIps] - Only accept this API key from these IPv4/IPv6 addresses or CIDR ranges (max 100). Omit or pass [] for no IP restriction. Customer API keys only.
+ * @property {string[]} [allowedCountries] - Only accept this API key from these countries, as ISO 3166-1 alpha-2 codes such as "US" (max 250). Omit or pass [] for no country restriction. Customer API keys only.
  */
 
 /**
@@ -47,6 +49,8 @@
  * @property {string} [country] - The country of the user's address (optional)
  * @property {string} [postalCode] - The postal code of the user's address (optional)
  * @property {string} [status] - The status of the user (e.g., "active", "inactive")
+ * @property {string[]} [allowedIps] - Customer API keys only: replace the key's allowed IPv4/IPv6 addresses or CIDR ranges ([] removes the restriction). Requires an interactive admin or developer session; an API key cannot change its own restrictions.
+ * @property {string[]} [allowedCountries] - Customer API keys only: replace the key's allowed ISO 3166-1 alpha-2 country codes ([] removes the restriction). Requires an interactive admin or developer session.
  */
 
 export class Users {

package/src/domains/Webhooks.js

@@ -37,8 +37,10 @@ export class Webhooks {
 	 * plaintext HMAC-SHA256 secret used to sign every delivery to this endpoint, sent as the
 	 * `X-SignalHouse-Signature` header alongside `X-SignalHouse-Timestamp` (the signed string is
 	 * `${timestamp}.${rawRequestBody}`) and `X-SignalHouse-Delivery-Id` (stable across retries of the
-	 * same event, for receiver-side dedup). Store this secret now: it is never returned again by any
-	 * read (SHGHL-2944).
+	 * same event, for receiver-side dedup), plus `X-SignalHouse-Signature-V1` (`t=<ms>,v1=<hex>[,v1=<hex>]`,
+	 * every currently valid signature). Store this secret now: it is never returned again by any read
+	 * (SHGHL-2944). If it's lost, call `rotateWebhookSecret`. Verify deliveries with
+	 * `verifyWebhookSignature` from `@signalhousellc/sdk/webhooks` (Node only).
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for creating a webhook
@@ -53,9 +55,11 @@ export class Webhooks {
 	}
 
 	/**
-	 * Update an existing webhook with the specified data. Like every other read of a webhook, the
-	 * response carries `hasSigningSecret` (boolean), never the signing secret itself — see
-	 * `createWebhook` (SHGHL-2944).
+	 * Update an existing webhook with the specified data. `updateData` may include `name`, `url`,
+	 * `subscribedEvents` and (SHGHL-3486) `authType`, `apiHeaderPrefix` and `credentials` (`{ key, secret? }`)
+	 * 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. Like every read of a webhook, the
+	 * response carries `hasSigningSecret` and `hasCredentials` (booleans), never a secret or credential.
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for updating a webhook
@@ -71,6 +75,28 @@ export class Webhooks {
 		return this.client(`/webhook/${safeId}`, { method: "PUT", body: updateData, ...options });
 	}
 
+	/**
+	 * Rotate a webhook's signing secret, or give a webhook created before signing existed its first one
+	 * (SHGHL-3486). The response includes the new plaintext `signingSecret`, returned this one time only.
+	 * The replaced secret keeps working for `graceSeconds` (default 86400, max 604800, 0 = stop now):
+	 * during that window each delivery's `X-SignalHouse-Signature-V1` header carries a signature for both,
+	 * and `previousSecretExpiresAt` in the response says when the old one stops. Not available to OAuth
+	 * connector tokens.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for rotating the secret
+	 * @param {string} params.id - The ID of the webhook
+	 * @param {number} [params.graceSeconds] - How long the replaced secret stays valid
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the id parameter is missing
+	 * @returns {Promise<SdkResponse<any>>} The webhook, including the new plaintext `signingSecret` (this one time only)
+	 */
+	async rotateWebhookSecret({ id, graceSeconds, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/webhook/${safeId}/rotate-secret`, { method: "POST", body: graceSeconds === undefined ? {} : { graceSeconds }, ...options });
+	}
+
 	/**
 	 * Delete a webhook by its ID (mark as inactive)
 	 * @async

package/src/webhooks/verifySignature.js

@@ -0,0 +1,66 @@
+import crypto from "node:crypto";
+
+// Node-only helpers for receiving Signal House webhooks (SHGHL-3486). Kept out of the main entry point,
+// which also runs in browsers, because it depends on node:crypto. Import from "@signalhousellc/sdk/webhooks".
+
+const DEFAULT_TOLERANCE_MS = 5 * 60 * 1000;
+
+/**
+ * Verify that a webhook delivery came from Signal House and is recent.
+ *
+ * Checks `X-SignalHouse-Signature-V1` (`t=<ms>,v1=<hex>[,v1=<hex>]`, which carries every currently valid
+ * signature during a secret rotation) when present, otherwise the original `X-SignalHouse-Signature` +
+ * `X-SignalHouse-Timestamp` pair. Each signature is a hex HMAC-SHA256 of `${timestamp}.${rawBody}`. Comparisons
+ * are constant-time.
+ *
+ * @param {Object} params
+ * @param {string|Buffer} params.rawBody - The exact request body as received, before any JSON parsing.
+ * @param {Object} params.headers - Request headers (any casing; e.g. Express `req.headers`).
+ * @param {string} [params.secret] - Your endpoint's signing secret.
+ * @param {string[]} [params.secrets] - Several secrets to accept, e.g. old and new while you roll over.
+ * @param {number} [params.toleranceMs=300000] - Reject deliveries whose timestamp is further than this from now.
+ * @param {number} [params.now=Date.now()] - Current time in ms (for tests).
+ * @returns {{valid: boolean, reason?: string}} - `valid` true when a signature matches within the time window;
+ *   otherwise `reason` is one of `no_secret`, `no_signature`, `bad_timestamp`, `stale_timestamp`, `bad_signature`.
+ */
+export function verifyWebhookSignature({ rawBody, headers, secret, secrets, toleranceMs = DEFAULT_TOLERANCE_MS, now = Date.now() }) {
+	const candidates = (secrets ?? (secret ? [secret] : [])).filter(Boolean);
+	if (candidates.length === 0) return { valid: false, reason: "no_secret" };
+
+	const header = (name) => {
+		if (!headers) return undefined;
+		const match = Object.keys(headers).find((key) => key.toLowerCase() === name);
+		const value = match === undefined ? undefined : headers[match];
+		return Array.isArray(value) ? value[0] : value;
+	};
+
+	let timestamp;
+	let signatures = [];
+	const v1 = header("x-signalhouse-signature-v1");
+	if (v1) {
+		const parts = String(v1).split(",").map((part) => part.trim());
+		timestamp = parts.find((part) => part.startsWith("t="))?.slice(2);
+		signatures = parts.filter((part) => part.startsWith("v1=")).map((part) => part.slice(3)).filter(Boolean);
+	}
+	// No usable V1 (absent, or mangled by an intermediary): fall back to the original header pair
+	if (signatures.length === 0) {
+		timestamp = header("x-signalhouse-timestamp");
+		const legacy = header("x-signalhouse-signature");
+		signatures = legacy ? [String(legacy)] : [];
+	}
+	if (signatures.length === 0) return { valid: false, reason: "no_signature" };
+
+	const sentAt = Number(timestamp);
+	if (!timestamp || !Number.isFinite(sentAt)) return { valid: false, reason: "bad_timestamp" };
+	if (Math.abs(now - sentAt) > toleranceMs) return { valid: false, reason: "stale_timestamp" };
+
+	const body = Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : String(rawBody ?? "");
+	for (const candidate of candidates) {
+		const expected = Buffer.from(crypto.createHmac("sha256", candidate).update(`${timestamp}.${body}`).digest("hex"), "utf8");
+		for (const signature of signatures) {
+			const given = Buffer.from(signature, "utf8");
+			if (given.length === expected.length && crypto.timingSafeEqual(given, expected)) return { valid: true };
+		}
+	}
+	return { valid: false, reason: "bad_signature" };
+}