@signalhousellc/sdk 1.0.65 → 1.0.66

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

@@ -0,0 +1,114 @@
+# Why 10DLC registrations get rejected
+
+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.
+
+## How to read a rejection
+
+`rejectionReason` is **free text, 10 to 256 characters** (verified: `campaign.validation.js`). It
+is not an enum and cannot be reliably pattern-matched.
+
+Registry errors arrive with a numeric code and a description, and the code is the reliable part.
+**These are TCR's own error codes, not HTTP status codes**. They arrive *inside* the response
+body of what is typically an HTTP 400, in the shape
+`External service error: TCR - Request failed with status code 400 - [{ "code": 503, "description": "..." }]`.
+A `503` here means "reference id already in use", not "service unavailable". Do not reason about
+them as HTTP semantics.
+
+## Registry error codes seen in production
+
+### 509: "Brand does not qualify for submitted campaign use-case"
+
+The brand is not eligible for the use case, on carrier-side vetting criteria. Two real cases:
+a generic technology company rejected for `UCAAS_HIGH` (which expects a recognized UCaaS
+provider), and a brand with `brandScore: 0` rejected for `DELIVERY_NOTIFICATION`.
+
+**Not retryable.** Resubmitting the same campaign cannot fix it. The two real options are to
+switch to a use case the brand qualifies for (`LOW_VOLUME` unblocks immediately), or to re-vet
+the brand to earn a qualifying score.
+
+Related: a brand with `brandScore: null` has not been scored by the registry yet. Campaigns
+depending on a score will keep failing until scoring runs, and that is not something the
+platform can force.
+
+### 501: invalid sub-use-case
+
+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`. Resubmit with
+`SOCIAL` removed.
+
+⚠️ **Known platform bug, tracked as SHGHL-2943.** Signal House validates `subUsecases` against
+the *use-case* enum, so `SOCIAL` is selectable as a sub-use-case even though the registry always
+rejects it. **Delete this subsection when SHGHL-2943 ships.** It documents a defect, and a
+workaround left in a skill becomes permanent.
+
+**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
+re-approved internally before it re-registers.
+
+### 503: "Reference ID already in use"
+
+A duplicate `referenceId` on brand creation. The brand cannot be repaired: create a **new**
+brand with the same details and **omit `referenceId` entirely**.
+
+This is specific to a brand that landed in `TCR_REJECTED`. It is **not** the general rule: a
+brand in `UNVERIFIED` can be fixed and re-submitted with an ordinary update (`PUT /brand/:brandId`
+calls the registry and writes back its fresh status) or with `PUT /brand/revet/:brandId`. Only
+`TCR_REJECTED` refuses both and forces recreation.
+
+## Platform-side rejections (before the registry ever sees it)
+
+**No numbers on the campaign.** Verified in `campaign.service.js`: registration throws
+`No phone numbers assigned to campaign with ID <campaignId>`. At least one number must be
+attached to the campaign. Confirmed by a real ticket where a campaign was rejected for exactly
+this.
+
+**Campaign not internally approved.** Campaigns wait on Signal House approval before they are
+upstreamed to the provider. "Not approved in our system yet" is a distinct state from any
+registry rejection.
+
+## Content and use-case rejections
+
+**Missing content attribute for the declared activity.** Real example: *"Campaign is for direct
+lending or loan arrangement and is missing content attribute indicating direct lending."* The
+campaign's declared attributes have to match what the traffic and landing page actually show.
+A landing page saying "no direct lending" while the campaign reads as lending is a rejection.
+
+## Adjacent gotchas
+
+**Brand deletion is blocked by campaigns.** The actual error is
+`Cannot delete brand <brandId> because it has active campaigns`, and the gate is broader than
+"active" suggests: it blocks on any campaign not yet `EXPIRED`. Campaigns must be cleared first.
+A brand can also show `EXPIRED` in Signal House while still `ACTIVE` at the registry, and the two
+are not automatically in sync.
+
+**Brand edits and fees, settled from the code.** Ordinary brand updates are **free**:
+`brandUpdate` exists in the fee schedule but is never charged anywhere. Updating landing URLs is
+its own path and charges nothing. The $4.50 people ask about is `brandRevet`, and it is only
+charged by an explicit re-vet (`PUT /brand/revet/:brandId`), never as a side effect of an edit.
+`brandCreate` is the same $4.50 and applies to creating a new brand, which is why a
+registry-rejected brand that must be recreated does cost again.
+
+What an edit *can* cost you is time, not money: changing verification-relevant data moves the
+brand `VERIFIED → UNVERIFIED` and it re-verifies.
+
+**A failed campaign holds its reserved funds.** Funds reserved at campaign creation are released
+for `PENDING_REVIEW` / `REJECTED` / `TCR_REGISTER_FAILED` when the campaign is **deleted**, not
+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

@@ -0,0 +1,84 @@
+---
+name: signalhouse-advisor
+description: >-
+  Planning a Signal House integration: the order the platform actually enforces, which work is
+  asynchronous and how long it really takes, what the caller's role permits, and which Signal House
+  skill answers which question.
+  TRIGGER when the user asks how to build on Signal House, wants an integration plan or timeline,
+  asks "what do I need to send my first message", is scoping or estimating work, or is deciding
+  which endpoint or SDK namespace to reach for.
+  SKIP once the plan is settled and the work is one specific area. Hand off to signalhouse-setup,
+  signalhouse-10dlc, signalhouse-numbers, signalhouse-sms or signalhouse-webhooks and follow that.
+---
+
+# Planning a Signal House integration
+
+## What cannot happen
+
+**There is no path from zero to a sent message in one sitting.** Brand and campaign registration go
+to external registries and carriers. Approval is measured in **days**, not minutes, and it can be
+rejected. Any plan, estimate or demo script that ends "and then we send a test message" on day one
+is wrong, and stating it optimistically wastes the customer's launch date rather than saving it.
+
+**The order is enforced by the platform, not by convention.** Brand before campaign; numbers
+attached at campaign creation; campaign `ACTIVE` before any send. A plan that discovers this at step
+nine has to be rebuilt from step two.
+
+**A plan is only executable if the token's role permits it.** Roles are checked server-side and
+differ sharply: a customer `api` service user is bound to a single group, `developer` reaches
+messaging, numbers, keys and webhooks, `billing` reaches billing only, and the `signalhouse_*` roles
+are staff. Confirm what the authenticated caller actually is before planning work it cannot perform.
+When the role is unknown, say so and plan against the least privilege rather than assuming `admin`.
+
+**Nothing about cost may be stated from memory.** Fees are per group, configurable and writable.
+`GET /billing/fees/:groupId` is the only correct answer to what something costs, and a number
+written into a plan reads as authoritative long after it stops being true.
+
+## The pipeline, in the order it must happen
+
+1. **Credential and group.** A token, and the `groupId` it is scoped to. `signalhouse-setup`.
+2. **Webhooks.** Before the first write, not after the first surprise. Most of what follows resolves
+   out of band. `signalhouse-webhooks`.
+3. **Funded wallet.** Registration and number purchase are charged. An unfunded account fails at the
+   first billable step, which is usually the brand.
+4. **Brand.** Submitted for verification. Days. Can be rejected, and some rejections require
+   recreating the brand rather than editing it. `signalhouse-10dlc`.
+5. **Numbers.** These can be bought while the brand is still verifying. Buying is not gated; sending is.
+   `signalhouse-numbers`.
+6. **Campaign.** Created **with its numbers attached**, then registered downstream. More days.
+   `signalhouse-10dlc`.
+7. **Send.** Only once the campaign is `ACTIVE` and the number is `READY`. `signalhouse-sms`.
+
+Steps 4 and 5 overlap. Steps 4 and 6 do not.
+
+## Asynchronous by design
+
+Mutating operations across brand, campaign and number return **202** and complete out of band. The
+HTTP response means accepted, not done. This shapes the whole integration:
+
+- **Subscribe, do not poll.** The platform's own guidance says so, and a polling loop hits rate
+  limits while still finding out late.
+- **Every long-running step needs a persisted state machine on the caller's side.** An integration
+  that holds "waiting for brand approval" in memory loses it on the next deploy.
+- **Design for rejection, not just delay.** Brand and campaign both have terminal failure states. A
+  flow with no path for "rejected, here is why" is unfinished.
+
+## Which skill answers which question
+
+| The question | Skill |
+|---|---|
+| How do I authenticate, what token, why a 401 | `signalhouse-setup` |
+| How do I know when something finished | `signalhouse-webhooks` |
+| Why is my campaign rejected or stuck, what does TCR need | `signalhouse-10dlc` |
+| How do I find, buy, or release numbers, what do they cost | `signalhouse-numbers` |
+| How do I send, why did a send fail, what does a message cost | `signalhouse-sms` |
+
+If a question spans two of these, answer with the constraint first and the mechanics second. The
+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`).
+- **Current fees and balance:** the billing endpoints, read live, per group.

package/skills/signalhouse-numbers/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: signalhouse-numbers
+description: >-
+  Signal House phone numbers: the search, purchase and list flow, and what a purchase commits
+  the account to financially.
+  TRIGGER when the user is searching for, buying, listing or releasing Signal House numbers;
+  when they are scripting or bulk-buying numbers; when a purchase fails; or when they ask what
+  numbers cost or why their balance dropped.
+  SKIP for toll-free verification and short-code provisioning, for porting numbers in, and for
+  assigning an existing number to a campaign, which belongs to 10DLC registration.
+---
+
+# Signal House phone numbers
+
+## What cannot happen
+
+**Releasing a number is irreversible.** `DELETE /number` sets the number to `RELEASED`, and
+**nothing transitions a number out of `RELEASED`**. It cannot be reactivated (reactivation
+requires `DEACTIVATED`), cannot be assigned to a campaign, and cannot be re-deleted. The number
+management guide says it plainly: released numbers cannot be recovered. Treat a release request
+as destructive and confirm it explicitly, every time.
+
+**A bulk local purchase has no ceiling.** `POST /number` accepts a `phoneNumbers` array with a
+minimum of 1 and **no maximum**, unlike campaign assignment, which caps at 5000. Passing a whole
+search page buys a whole search page. If a caller asks for "some numbers", establish the count
+before purchasing, not after.
+
+Toll-free is different: those purchases are capped at 10 per order and additionally gated by a
+per-group toll-free flag. The unbounded risk above is specific to local numbers.
+
+**A number is not sendable just because it was purchased.** It has to be attached to a campaign,
+and that campaign has to be `ACTIVE`. See the `signalhouse-10dlc` skill.
+
+## Order of operations
+
+1. **Search** for available numbers, filtered to what is actually needed (state, area code,
+   SMS/MMS capability). Searching and NPA/NXX lookup are **free**, with no billing call on those
+   paths, so filter properly rather than buying to find out.
+2. **Confirm the count and the cost** before purchasing. Read current fees from
+   `GET /billing/fees/:groupId`. Do not assume a price or carry one over from a previous run.
+3. **Purchase** the specific numbers chosen. `subgroupId` is required, and the subgroup must
+   exist and be active.
+4. **List** to confirm what the account now owns and is paying for.
+
+Numbers can be purchased while a brand is still verifying. There is no brand or campaign gate on
+the purchase path. What must wait is sending, not buying.
+
+## Spend awareness
+
+The rule to hold: **the account is billed for what it owns, not for what it uses.**
+
+**Purchase is charged immediately**, per number, on both the local and toll-free paths.
+
+**Renewal is recurring, but it is environment-gated.** There is a renewal scheduler that charges a
+per-number renewal fee on a billing date. It only runs when `ENABLE_NUMBER_BILLING_RENEWALS` is
+enabled, and that flag is **off by default** with the real value set per environment. So:
+
+- Never tell a customer that numbers have no ongoing cost. The mechanism exists and is the
+  intended behaviour.
+- Never quote the renewal as definitely active either. If it matters to the answer, check the
+  environment rather than asserting.
+- The renewal fee is applied to toll-free numbers too, despite being named for local ones.
+
+**Repeated renewal failures delete the number.** After a configured number of failed renewal
+attempts the number is queued for deletion, and deletion is the irreversible release above. A
+customer whose balance is empty does not simply go unbilled; they can lose the number.
+
+Before any purchase, be able to state how many numbers are being bought and the current
+per-number fee, read live. If either is unknown, ask rather than buy.
+
+Never quote a price from memory or from this file. Fees are per-group and configurable,
+and writable via `PUT /billing/fees/:groupId`, so a number here would be both stale and
+authoritative-looking. `GET /billing/fees/:groupId` is the only correct answer to "what does this
+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`).
+- **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

@@ -0,0 +1,91 @@
+---
+name: signalhouse-setup
+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.
+  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".
+---
+
+# Signal House setup
+
+## What cannot happen
+
+**A login token cannot carry a server integration.** `POST /auth` returns a **short-lived session
+JWT**, measured in hours. It is the right token for a user acting in a session and the wrong token
+for anything that runs unattended. A cron job built on a login token works all afternoon and fails
+overnight.
+
+Both lifetimes are set per environment (`JWT_USER_EXPIRES_IN`, `JWT_SYSTEM_EXPIRES_IN`), so treat
+the session token as short and the service token as long, and read the exact values from the
+Authentication guide or the environment rather than quoting a number to a customer.
+
+**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.
+
+**`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
+`signalhouse_admin` credentials). A customer caller asking for the internal role gets a **403**. If
+an integration seems to need it, the requirement is wrong.
+
+**The API key is shown once.** The token is signed and returned at creation and never stored on the
+user record, so no endpoint can hand it back. Losing it means creating another service user, not
+recovering the old key.
+
+**A group under compliance rejection cannot create API keys at all.** Service-user creation is gated
+on the group's compliance state and fails with a group-rejected error rather than a validation error.
+Staff roles are exempt. When key creation fails for one group and works for another, check the
+account's standing before debugging the request.
+
+**Being authenticated does not mean being able to send.** Setup ends with a working credential.
+Sending additionally requires a verified brand, an `ACTIVE` campaign, and a number in `READY` status
+on it. See `signalhouse-10dlc`.
+
+## Order of operations
+
+1. **Get a token.** Human session → `POST /auth`, short-lived. Server integration → a service user,
+   long-lived. Do not build a server integration on a login token and plan to "refresh it later".
+2. **Know the group.** A customer service user (`role: "api"`) is bound to one `groupId`, an
+   8-character id beginning with `G`. That scoping is what limits the damage of a leaked
+   key, so one key per group is the design, not an inconvenience to work around.
+3. **Initialize the SDK** with `apiKey` and `baseUrl`. The `apiKey` is the default credential on
+   every request; `options: { token }` overrides it per call, which is how an app acting for many
+   users should work rather than reinitializing the SDK per user.
+4. **Make one read call** and check the envelope before writing anything.
+5. **Register webhooks before the first write.** Brand registration, campaign registration, number
+   purchase and message delivery all resolve out of band, minutes to days later. An integration
+   without webhooks discovers outcomes by polling, burns rate limit doing it, and still finds out
+   late. See `signalhouse-webhooks`.
+
+## Reading the response
+
+The SDK returns an **envelope**, and most failures arrive inside it rather than as an exception:
+
+```
+{ success: true|false, data: <payload>, error: <body>, status: <http status> }
+```
+
+- Branch on `response.success` and `response.status`, not on a try/catch alone.
+- **Rate limiting is a `429` in the envelope**, not a throw. Detect it as `response.status === 429`
+  and back off; matching on the error string is brittle.
+- Client-side validation failures DO throw (`SignalHouseValidationError`). Those are not retryable,
+  and retrying an invalid payload just spends the retry budget.
+- A `401` means the token expired or was revoked. Re-authenticate; do not retry the same token.
+
+Response shapes are nested differently per endpoint and the nesting is not guessable. Read the
+current shape from the API reference rather than assuming it matches a sibling endpoint.
+
+## 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.

package/skills/signalhouse-sms/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: signalhouse-sms
+description: >-
+  Sending SMS and MMS on Signal House: what a successful-looking response does not prove, the
+  parameter name that differs between the SDK and the raw API, how segments drive cost, and the
+  carrier and opt-out gates that stop a send.
+  TRIGGER when the user is sending or scripting SMS, MMS or group MMS; when a message came back
+  successful but never arrived; when a send fails or is rejected; when they ask about delivery
+  status, delivery receipts, message cost, segments, emoji, or STOP and opt-outs.
+  SKIP for 10DLC brand and campaign registration, for buying numbers, and for webhook endpoint
+  setup, which have their own skills. This one assumes a number that is already able to send.
+---
+
+# Sending on Signal House
+
+## What cannot happen
+
+**`success: true` does not prove the message went out.** When the Moderation API blocks content, the
+send does **not** raise an API error. The recipients are written to the message log as **accepted but
+`FAILED`** and returned like a normal send, so the caller sees a normal success envelope. Any code
+that treats a 2xx as "delivered" reports a blocked campaign as a working one. Confirm outcomes from
+message status or a delivery webhook, never from the send response alone.
+
+**A number cannot send just because the account owns it.** It must be in `READY` status on an
+`ACTIVE` campaign, under a brand that is `VERIFIED` or `VETTED_VERIFIED`. A brand-new number is not a
+sendable number. See `signalhouse-10dlc`.
+
+**The recipient field is named differently in the SDK and the API.** The raw API takes
+`recipientPhoneNumber` (**singular**, still an array). The JS SDK takes `recipientPhoneNumbers`
+(**plural**) and maps it internally. A direct HTTP caller who copies the SDK's plural name gets a
+validation failure, and it reads as a mysterious 400 rather than a typo.
+
+**Opt-out suppression is environment-gated, so a STOP is not automatically a block.**
+`DNC_ENFORCEMENT_MODE` has three settings, `off`, `log` and `enforce`, and the default is **`log`**.
+In `log` mode the platform queries suppressions and records what it *would* have blocked, then lets
+every recipient through. So:
+
+- Never tell a customer that STOP replies are being enforced without checking the environment.
+- Never tell them suppression does not exist either. The list is real and is being recorded.
+- STOP and HELP confirmations deliberately bypass suppression. They are addressed to someone who is
+  on the list by design, so seeing one go out is not evidence that suppression is broken.
+
+**Sending is billed per segment, not per message.** A single non-GSM character, such as an emoji or a
+curly quote pasted from a document, flips the whole body to a different encoding and
+multiplies the segment count, and the cost, silently. Message body length is a billing decision.
+
+**Carrier throughput is capped above the API.** There is a T-Mobile daily segment cap tracked per
+brand EIN and an AT&T per-minute segment limit. Hitting either fails messages with a recorded reason
+rather than raising an exception at the call site. A burst where most messages went out and some did not
+is what this looks like in practice.
+
+## Order of operations
+
+1. **Confirm the sender can send.** Check the number's status is `READY` rather than assuming.
+2. **Know the segment count and current fee** before a bulk send. Fees are per group and read from
+   `GET /billing/fees/:groupId`. Never quote a price from memory or from this file.
+3. **Send.** `POST /message/sms` (JSON), `POST /message/mms` (multipart, max 5 attachments),
+   `POST /message/groupMessage` (multipart, shared thread). The send is queued and returns **201**
+   with an `insertedMessages` array holding one document per recipient.
+4. **Read the outcome asynchronously.** `statusCallbackUrl` on the send, or `MESSAGE_DELIVERED` /
+   `MESSAGE_FAILED` webhooks. Polling `GET /message` in a loop is the wrong shape and the rate-limit
+   guidance says so explicitly.
+
+Message status runs `ENQUEUED → DEQUEUED → SENT → DELIVERED`, with `FAILED` reachable from the
+middle. `SENT` means handed to the carrier, not received by the handset. Only `DELIVERED` means
+delivered, and not every carrier returns one.
+
+## Querying messages
+
+`GET /message` requires `groupId`, `startDate` and `endDate` **unless** you filter by `id`, which
+routes to a single-record lookup and skips the date-range requirement. Omitting them without an `id`
+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`).
+- **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`).
+- **Why a number cannot send yet:** `signalhouse-10dlc`.

package/skills/signalhouse-webhooks/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: signalhouse-webhooks
+description: >-
+  Signal House webhooks: how delivery actually behaves, what a receiver can and cannot trust,
+  and the retry window before an event is lost for good.
+  TRIGGER when the user is setting up, debugging, or writing a receiver for Signal House
+  webhooks; when webhook events appear to be missing, duplicated, or arriving late; when they
+  ask how to verify a webhook is genuine; or when they are choosing an authType.
+  SKIP for inbound message handling logic itself, for the SMS send path, and for questions about
+  which events exist. That list is in the webhooks guide and changes independently of this.
+---
+
+# Signal House webhooks
+
+## What cannot happen
+
+**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.
+
+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.
+
+Practical consequences a receiver has to design around:
+
+- **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.
+
+> ⚠️ Tracked as **SHGHL-2944**. Delete this section when signing ships. A workaround left in a
+> skill becomes permanent.
+
+## 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.
+
+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.
+- 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.
+
+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.
+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.
+
+   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.
+`authType` picks how Signal House authenticates to the endpoint, and `credentials` is
+`{ key, secret }`, required whenever `authType` is not `NONE`.
+
+| authType | What is sent |
+|---|---|
+| `NONE` | nothing. The endpoint is open to anyone who knows the URL |
+| `BASIC` | HTTP Basic; `key` is the username, `secret` is the password |
+| `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.
+
+**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.
+
+## 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.
+- **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.

package/src/domains/Campaigns.js

@@ -64,7 +64,7 @@
  * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy for the campaign (optional, must be at most 2048 characters if provided)
  * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions for the campaign (optional, must be at most 2048 characters if provided)
  * @property {string} [embeddedLinkSample] - A sample of the embedded link used in the campaign (optional, must be at most 255 characters if provided)
- * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free campaign. Mirrors the CreateTollFreeCampaignData `tollFree` object with every field optional (useCase, messageVolume, programSummary (40-500), exampleMessage, customerCareEmail, optInImageURLs, optIns, multiNumberReason (≤500)). Phone numbers cannot be changed via update — Toll-Free numbers are locked to their campaign.
+ * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free campaign. Mirrors the CreateTollFreeCampaignData `tollFree` object with every field optional (useCase, messageVolume, programSummary (40-500), exampleMessage (≤1000), customerCareEmail, optInImageURLs, optIns, multiNumberReason (≤500), useCases, channels, landingId). Phone numbers cannot be changed via update — Toll-Free numbers are locked to their campaign.
  */
 
 /**
@@ -79,7 +79,7 @@
  * @property {string} useCase - The Toll-Free use case (required, e.g. TWO_FA, GENERAL_MARKETING, HEALTHCARE, MIXED — one of the Toll-Free use-case values)
  * @property {string} messageVolume - The estimated monthly message volume tier (required, one of TEN, HUNDRED, THOUSAND, TEN_THOUSAND, HUNDRED_THOUSAND, TWO_HUNDRED_FIFTY_THOUSAND, FIVE_HUNDRED_THOUSAND, SEVEN_HUNDRED_FIFTY_THOUSAND, ONE_MILLION, FIVE_MILLION, TEN_MILLION_PLUS)
  * @property {string} programSummary - A summary of the messaging program (required, 40-500 characters)
- * @property {string} exampleMessage - An example message (required, at most 4096 characters; stored verbatim, no STOP/HELP appended by the server)
+ * @property {string} exampleMessage - An example message (required, at most 1000 characters; holds one sample per use case, stored verbatim, no STOP/HELP appended by the server)
  * @property {string} customerCareEmail - A customer-care contact email (required, valid email)
  * @property {Array<string>} optInImageURLs - URLs to opt-in proof images (required, at least one, each at most 2048 characters)
  * @property {Object} [optIns] - Opt-in method details. Each channel is optional.
@@ -88,6 +88,9 @@
  * @property {TollFreeOptIn} [optIns.keyword] - Keyword opt-in details
  * @property {TollFreeOptIn} [optIns.interactiveVoiceResponse] - IVR opt-in details
  * @property {string} [multiNumberReason] - Internally-stored reason the customer requested more than one Toll-Free number on the campaign (optional, at most 500 characters). Required when more than one phone number is assigned; captured for Signal House review only and never sent to the carrier.
+ * @property {string[]} [useCases] - The sender's real use-case picks (optional). `useCase` above carries the single value the carrier accepts (MIXED when there is more than one); these are what a Signal House landing page renders a consent checkbox per. Never forwarded to the carrier.
+ * @property {string[]} [channels] - The channels consent covers ("SMS", "MMS", "VOICE") (optional). Never forwarded to the carrier.
+ * @property {string} [landingId] - The Signal House landing page whose consent boxes this campaign's call-to-action describes (optional). Must be an ACTIVE page owned by the same brand and group.
  */
 
 /**
@@ -261,6 +264,15 @@ export class Campaigns {
    * @param {string} [params.sortOrder] - Sort direction ("asc" or "desc")
    * @param {string} [params.registrationType] - Filter by registration type ("TEN_DLC", "TOLL_FREE", or "SHORT_CODE")
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   *
+   * Every record carries a `sentiment` object -- trailing 7-day and 30-day inbound reply sentiment,
+   * refreshed periodically from analytics rather than computed per request: `{ sevenDay, thirtyDay,
+   * updatedAt }`, each window being `{ score, label, scoredCount, positive, neutral, negative }`. The
+   * object is always present and fully populated, so it can be read without a presence check.
+   * `score` is a volume-weighted average in -100..100 and is null when nothing was scored in the
+   * window, which is not the same as a score of 0 -- null means nobody replied, 0 means replies
+   * averaged neutral. `updatedAt` is null until the first rollup writes the record, and it tracks when
+   * the figures last CHANGED, not when the job last ran.
    * @returns {Promise<Array|Object>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
    */
   async getCampaigns({
@@ -441,13 +453,18 @@ export class Campaigns {
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for capturing the opt-in image
    * @param {string} params.brandId - The ID of the brand whose generated landing page should be captured
+   * @param {string} [params.landingId] - The specific page to capture. Required for Toll-Free brands, which have
+   *   one page per campaign — omitted, the request is refused rather than guessing which page to shoot. A 10DLC
+   *   brand has a single page, so it may be omitted there
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the brandId parameter is missing
    * @returns {Promise<Object>} The response from the server containing the hosted image's id and URL
    */
-  async captureOptInImageFromLanding({ brandId, options = {} }) {
+  async captureOptInImageFromLanding({ brandId, landingId, options = {} }) {
     this.client._require({ brandId });
-    return this.client(`/campaign/opt-in-image/from-landing`, { method: 'POST', body: { brandId }, ...options });
+    const body = { brandId };
+    if (landingId) body.landingId = landingId;
+    return this.client(`/campaign/opt-in-image/from-landing`, { method: 'POST', body, ...options });
   }
 
   /**