@signalhousellc/sdk 1.0.67 → 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.67",
+  "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/",
@@ -19,7 +20,9 @@
   },
   "scripts": {
     "postinstall": "node scripts/install-skills.mjs",
-    "sync-skills": "node scripts/sync-skills.mjs"
+    "sync-skills": "node scripts/sync-skills.mjs",
+    "build:types": "tsc -p tsconfig.json",
+    "check:types": "tsc -p tsconfig.json --noEmit"
   },
   "agents": {
     "skills": "./skills"
@@ -36,5 +39,10 @@
     "jssip": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.3",
+    "jssip": "^3.13.8",
+    "typescript": "^5.9.3"
   }
 }

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

@@ -6,6 +6,19 @@ import axios from "axios";
  * @property {object} [headers] - Additional headers to include in the request
  */
 
+/**
+ * @typedef {Object} SignalHouseSDKConfig
+ * @property {string} apiKey - The API key for authenticating requests to the SignalHouse API
+ * @property {string} baseUrl - The base URL for the SignalHouse API (e.g., "https://api.signalhouse.com")
+ * @property {boolean} [enableAdmin=false] - Enable admin-scoped behaviors on domains that support them
+ */
+
+/**
+ * The envelope every domain method resolves to. Non-2xx responses never reject; check `success` first.
+ * @template T
+ * @typedef {{ success: true, data: T, status: number } | { success: false, error: string|Object, status: number|null }} SdkResponse
+ */
+
 // Main SDK Class (SignalHouseSDK.js)
 import { Auth } from "./domains/Auth.js";
 import { Billing } from "./domains/Billing.js";
@@ -16,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";
@@ -29,19 +43,15 @@ import { Agents } from "./domains/Agents.js";
 export class SignalHouseSDK {
 	/**
 	 * Initialize the SignalHouseSDK with the required configuration
-	 * @param {Object} config - The configuration object for initializing the SDK
-	 * @param {string} config.apiKey - The API key for authenticating requests to the SignalHouse API
-	 * @param {string} config.baseUrl - The base URL for the SignalHouse API (e.g., "https://api.signalhouse.com")
-	 * @param {boolean} [config.enableAdmin=false] - Enable admin-scoped behaviors on domains that support them.
+	 * @param {SignalHouseSDKConfig} config - The configuration object for initializing the SDK
 	 * @throws {Error} Throws an error if the API key or base URL is missing from the configuration
-	 * @returns {SignalHouseSDK} An instance of the SignalHouseSDK
 	 */
-	constructor(config = {}) {
+	constructor(config) {
 		// Validate required config parameters
-		if (!config.apiKey) {
+		if (!config?.apiKey) {
 			throw new Error("API key is required to initialize SignalHouseSDK");
 		}
-		if (!config.baseUrl) {
+		if (!config?.baseUrl) {
 			throw new Error("Base URL is required to initialize SignalHouseSDK");
 		}
 
@@ -64,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);
@@ -90,19 +101,21 @@ export class SignalHouseSDK {
 		const instance = axios.create({ baseURL: this.baseUrl, headers: isMultipart ? {} : { "Content-Type": "application/json" } });
 
 		// Add a request interceptor to include the API key in the Authorization header
-		instance.interceptors.request.use((config) => {
+		instance.interceptors.request.use((/** @type {import('axios').InternalAxiosRequestConfig & { token?: string }} */ config) => {
 			const token = config.token || this.apiKey;
 			config.headers.Authorization = `Bearer ${token}`;
 			delete config.token; // Remove token from config to avoid sending it as a header
 			return config;
 		});
 
-		// Standardize responses
+		// Standardize responses. The fulfilled handler deliberately replaces the AxiosResponse with the
+		// SdkResponse envelope, which axios's interceptor typing does not model; the cast keeps that intent visible.
 		instance.interceptors.response.use(
 			// Standard 2xx responses
-			(response) => {
+			/** @type {(response: import('axios').AxiosResponse) => any} */
+			((response) => {
 				return { success: true, data: response.data, status: response.status };
-			},
+			}),
 
 			// Non-2xx responses
 			(error) => {
@@ -156,7 +169,7 @@ export class SignalHouseSDK {
 	_require(fields) {
 		for (const [name, value] of Object.entries(fields)) {
 			if (value === undefined || value === null || value === "") {
-				const error = new Error(`Missing required parameter: ${name}`);
+				const error = /** @type {Error & { status?: number }} */ (new Error(`Missing required parameter: ${name}`));
 				error.name = "SignalHouseValidationError";
 				error.status = 400; // Match API validation code
 				throw error;