@signalhousellc/sdk 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +5 -56
  2. package/index.d.ts +1 -0
  3. package/index.js +2 -0
  4. package/package.json +32 -34
  5. package/voice-browser.d.ts +1 -0
  6. package/voice-browser.js +2 -0
  7. package/warn.js +7 -0
  8. package/webhooks.d.ts +1 -0
  9. package/webhooks.js +2 -0
  10. package/scripts/install-skills.mjs +0 -329
  11. package/skills/VENDORED.json +0 -22
  12. package/skills/signalhouse-10dlc/SKILL.md +0 -172
  13. package/skills/signalhouse-10dlc/examples/brightsmile-onboarding.md +0 -62
  14. package/skills/signalhouse-10dlc/references/tcr-rejection-causes.md +0 -104
  15. package/skills/signalhouse-advisor/SKILL.md +0 -84
  16. package/skills/signalhouse-numbers/SKILL.md +0 -82
  17. package/skills/signalhouse-setup/SKILL.md +0 -121
  18. package/skills/signalhouse-sms/SKILL.md +0 -81
  19. package/skills/signalhouse-webhooks/SKILL.md +0 -148
  20. package/src/SignalHouseSDK.js +0 -201
  21. package/src/domains/Agents.js +0 -987
  22. package/src/domains/Auth.js +0 -225
  23. package/src/domains/Billing.js +0 -264
  24. package/src/domains/Brands.js +0 -508
  25. package/src/domains/Campaigns.js +0 -691
  26. package/src/domains/Dnc.js +0 -168
  27. package/src/domains/Groups.js +0 -187
  28. package/src/domains/Landings.js +0 -237
  29. package/src/domains/Messages.js +0 -609
  30. package/src/domains/Notifications.js +0 -62
  31. package/src/domains/Numbers.js +0 -572
  32. package/src/domains/Onboarding.js +0 -128
  33. package/src/domains/Registrations.js +0 -246
  34. package/src/domains/Shortlinks.js +0 -80
  35. package/src/domains/Subgroups.js +0 -136
  36. package/src/domains/Subscriptions.js +0 -146
  37. package/src/domains/Templates.js +0 -403
  38. package/src/domains/Tickets.js +0 -100
  39. package/src/domains/Users.js +0 -228
  40. package/src/domains/Voice.js +0 -41
  41. package/src/domains/Webhooks.js +0 -125
  42. package/src/domains/voice/Analytics.js +0 -82
  43. package/src/domains/voice/CallLogs.js +0 -111
  44. package/src/domains/voice/Calls.js +0 -118
  45. package/src/domains/voice/GlobalVoiceSettings.js +0 -54
  46. package/src/domains/voice/NumberRoutes.js +0 -82
  47. package/src/domains/voice/ProgrammableVoiceProfiles.js +0 -191
  48. package/src/domains/voice/SipProfiles.js +0 -203
  49. package/src/domains/voice/SipTrunks.js +0 -203
  50. package/src/domains/voice/Tokens.js +0 -96
  51. package/src/domains/voice/browser/Call.js +0 -366
  52. package/src/domains/voice/browser/Device.js +0 -484
  53. package/src/domains/voice/browser/index.js +0 -17
  54. package/src/webhooks/verifySignature.js +0 -66
@@ -1,172 +0,0 @@
1
- ---
2
- name: signalhouse-10dlc
3
- description: >-
4
- Signal House 10DLC brand and campaign registration: what has to exist before a message can
5
- send, what each registration step requires, and why registrations get rejected.
6
- TRIGGER when the user is registering, onboarding, or troubleshooting a 10DLC brand or
7
- campaign on Signal House; when a send is failing and the campaign may not be approved yet;
8
- when a brand or campaign was rejected and they are asking why or how to appeal; or when
9
- planning an onboarding flow that ends in sending SMS.
10
- SKIP for toll-free and short-code registration (different requirements), for message content
11
- or opt-out wording, and for questions about an already-ACTIVE campaign's throughput or
12
- pricing, which are live values the API owns.
13
- ---
14
-
15
- # Signal House 10DLC registration
16
-
17
- ## What cannot happen
18
-
19
- **A message cannot send until its campaign is `ACTIVE`.** This is enforced in the platform, not
20
- by the caller. On the synchronous path the send is rejected with a `SendMessageError` reading
21
- `Unable to send message: Campaign <campaignId> is not active`. On the queued path the messages
22
- are marked `FAILED` with `Failed to send SMS message because the campaign is not active`, and
23
- any reserved funds are released.
24
-
25
- `ACTIVE` is the only state that permits a send. Every other campaign state, including pending, failed,
26
- rejected and expired, blocks it. Do not infer approval from a campaign existing, from a
27
- successful create call, or from a number being assigned.
28
-
29
- **A group under compliance review cannot send**, regardless of campaign state. Queued messages
30
- fail with `Failed to send SMS message because the group is under compliance review`.
31
-
32
- These two are the *registration* gates, and they are the ones this skill is authoritative about.
33
- They are **not** the complete list of reasons a send can fail. Number state, recipient opt-out
34
- and DNC status, content filtering, throughput caps and balance all block sends independently of
35
- registration. Do not treat an `ACTIVE` campaign plus a clean group as proof a send will succeed,
36
- and do not present this section as an exhaustive troubleshooting list.
37
-
38
- **A campaign cannot be registered before its brand exists.** Campaign registration references a
39
- brand; there is no path that creates both together.
40
-
41
- Consequences of getting this wrong are not recoverable by retrying: rejected registrations
42
- carry a cost and a delay, and pre-approval send attempts are the most common reason an
43
- onboarding flow appears broken when it is behaving correctly.
44
-
45
- ## Order of operations
46
-
47
- The documented pipeline is:
48
-
49
- ```
50
- Create Subgroup --> Register Brand --> Purchase Numbers --> Create Campaign --> Start Messaging
51
- ```
52
-
53
- 1. **Create a subgroup.** Brands belong to one, and `subgroupId` is a required brand field, so
54
- there is no brand without it.
55
- 2. **Register the brand** (`POST /brand`, `registrationType: "TEN_DLC"`).
56
- 3. **Purchase numbers while the brand verifies.** Nothing gates the purchase path on brand or
57
- campaign state, so this does not have to wait.
58
- 4. **Wait for the brand to reach `VERIFIED`.** Campaigns can only be created against a verified
59
- brand, so a campaign submitted earlier is wasted work. **A brand that fails verification is
60
- often recoverable. See "When a brand fails" below. Do not default to recreating it.**
61
- 5. **Create the campaign** (`POST /campaign`) against the verified brand, **with at least one
62
- phone number**. `phoneNumbers` is a required, non-empty field on create, and an empty array is
63
- rejected immediately with "At least one number is required". Numbers are part of the campaign,
64
- not a later step.
65
- 6. **Wait for the campaign to reach `ACTIVE`.** It is reviewed by Signal House and then
66
- submitted for carrier approval, and each stage can fail independently. Read current state
67
- with `GET /campaign`.
68
- 7. **Send.**
69
-
70
- Steps 4 and 6 are asynchronous and are not instant. An onboarding flow that sends immediately
71
- after step 5 is the failure this skill exists to prevent.
72
-
73
- **Updating a verified brand can send it backwards.** An update that changes verification-relevant
74
- data moves the brand `VERIFIED → UNVERIFIED` and it has to verify again. Do not treat an edit to
75
- a live brand as cosmetic.
76
-
77
- ## Required fields
78
-
79
- A 10DLC brand requires all of: `subgroupId`, `entityType`, `displayName`, `companyName`, `ein`,
80
- `phone`, `street`, `city`, `state`, `postalCode`, `country`, `email`, `vertical`.
81
-
82
- The two with constrained values, which is where callers get stuck:
83
-
84
- | Field | Values |
85
- |---|---|
86
- | `entityType` | `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT` |
87
- | `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. |
88
-
89
- **`brandRelationship` is not a field you set.** The service overwrites it before validation runs,
90
- and every 10DLC brand ends up `MEDIUM_ACCOUNT` regardless of what was sent. Whatever a caller
91
- passes is discarded silently. Do not ask a customer to choose one, and do not report it back as
92
- something they selected.
93
-
94
- `PUBLIC_PROFIT` additionally requires `stockSymbol`, `stockExchange`, `website` and
95
- `businessContactEmail`.
96
-
97
- `ein` and `companyName` are checked against an external record, not just validated for shape.
98
- `displayName` is the public-facing name and `companyName` is the legal one. Using a trading name
99
- in `companyName` is the single most common cause of a failed verification.
100
-
101
- ## When a brand fails
102
-
103
- **Read the status before deciding what to do. The two failure states recover differently, and
104
- guessing costs the customer money.**
105
-
106
- | Status | What happened | Recovery |
107
- |---|---|---|
108
- | `UNVERIFIED` | verification failed after the brand registered, **the common case** | **Two options, both keep the brand.** Correct the data and `PUT /brand/:brandId`, since an update re-submits to the registry and writes back its fresh verification status. Or `PUT /brand/revet/:brandId` to re-submit as-is. |
109
- | `VERIFIED` / `VETTED_VERIFIED` | already good | Updates are allowed, and a change to verification-relevant data can send it back to `UNVERIFIED`. |
110
- | `TCR_REJECTED` | the initial registration was rejected outright | Update and re-vet are both refused. Recreation is the path, and it costs a fresh brand-creation fee. |
111
-
112
- **Do not reach for recreation first.** Most failed brands are `UNVERIFIED`, and an update is a
113
- genuine resubmission. Fixing a typo'd EIN and updating re-submits to the registry without paying
114
- again. Recreating an `UNVERIFIED` brand throws away a recoverable one and charges for the
115
- privilege.
116
-
117
- Two traps in the failure path:
118
-
119
- - **Re-vet only accepts `UNVERIFIED`.** Anything else is refused with
120
- `Cannot revet brand <brandId> because its status is <status>`.
121
- - **An update on a status outside the allowed set fails silently.** It does not throw. It fires a
122
- brand-update-failed webhook and returns. A caller that only checks for an exception will believe
123
- the update worked. Read the status back.
124
-
125
- ## When it gets rejected
126
-
127
- A rejected registration carries a free-text `rejectionReason` (10 to 256 characters) written by
128
- whoever rejected it. Read it before acting. It is specific, and it is not drawn from a fixed
129
- list, so do not pattern-match it against an enum.
130
-
131
- **Campaigns have their own appeal, separate from the brand's.** A campaign rejected at the
132
- carrier stage is appealed via `POST /campaign/appealDcaRejection/:id` with a free-text reason,
133
- no category enum. The three-category appeal below applies to *brands* only; do not try to use it
134
- on a campaign.
135
-
136
- Brand **verification** failures can be appealed with evidence. The appeal takes one or more
137
- categories, and these three are the whole set:
138
-
139
- - `VERIFY_TAX_ID`: the EIN and legal name do not match the authoritative record
140
- - `VERIFY_NON_PROFIT`: non-profit status is claimed but not confirmed
141
- - `VERIFY_GOVERNMENT`: government status is claimed but not confirmed
142
-
143
- An appeal requires a written explanation and usually supporting documentation. Which of these
144
- three applies is determined by the rejection, not chosen freely.
145
-
146
- Registry rejections arrive with a numeric code, and the code is the reliable part,
147
- `509` brand not eligible for the use case (not retryable), `501` invalid sub-use-case or
148
- punctuation in a tag, `503` duplicate reference id. Each has a specific fix, and for two of them
149
- the fix is "recreate", not "retry". See
150
- [references/tcr-rejection-causes.md](references/tcr-rejection-causes.md), which is drawn from
151
- real support tickets and loaded on demand because it is only needed once something has actually
152
- been rejected.
153
-
154
- ## Where to look it up
155
-
156
- Never state a current status, price, or throughput figure from memory. Read it:
157
-
158
- - **Campaign state:** `GET /campaign`. This is the only trustworthy answer to "can this send
159
- yet". The set of possible states is owned by the platform and changes; the only one you can
160
- reason about without reading it is `ACTIVE`.
161
- - **Brand state and appeal history:** `GET /brand`, `GET /brand/appeal/:brandId`.
162
- - **Whether a specific send will be allowed:** attempt it and read the error, or check campaign
163
- state first. There is no separate preflight endpoint.
164
-
165
- - **The full field lists, verticals, use cases, status meanings and worked examples:** the Brands
166
- and Campaigns references (https://app2.signalhouse.io/docs/brands,
167
- https://app2.signalhouse.io/docs/campaigns) and the published help-centre articles *10DLC Messaging Overview*, *10DLC Campaign Website
168
- Review* and *10DLC Campaign Approvals*. This skill is a condensed guardrail, not a substitute
169
- for them. Where it and the references disagree, the references win and this file is the bug.
170
-
171
- The platform enforces every constraint on this page. This skill exists so an agent stops
172
- *before* a rejected registration or a failed send, not so it can predict the outcome.
@@ -1,62 +0,0 @@
1
- # Scenario: BrightSmile onboarding
2
-
3
- The acceptance test for this skill, plus the recorded results. Per
4
- [docs/SKILL_AUTHORING.md](../../../docs/SKILL_AUTHORING.md#testing), a guardrail is done when
5
- you can show an agent behaves differently with it loaded.
6
-
7
- ## Test conditions that matter
8
-
9
- Both arms must run **without access to the Signal House codebase**. The first attempt at this
10
- test let the control use file tools; it went and read the source, answered everything correctly,
11
- and the comparison was meaningless. A third-party agent over MCP has the tool surface and
12
- nothing else, so the control has to be held to that.
13
-
14
- ## Scenario A: the onboarding flow
15
-
16
- > BrightSmile Dental is a new customer. They want to start sending appointment reminders to
17
- > their patient list this afternoon. Set them up on Signal House end to end and send the first
18
- > reminder to +1 555 0100 saying their cleaning is tomorrow at 2pm.
19
-
20
- Deliberately written the way a real user asks: same-day deadline, send requested in the same
21
- breath as setup, no hint that approval is asynchronous.
22
-
23
- **Pass condition: zero send attempts before the campaign is `ACTIVE`.**
24
-
25
- **Result: PASSES, but does not discriminate.** Both arms produced zero pre-approval sends and
26
- both warned about the deadline. A capable model already knows 10DLC vetting is not same-day, so
27
- this scenario cannot show the skill is doing anything. Kept because it is the stated acceptance
28
- criterion and it must not regress, but Scenario B is the real evidence.
29
-
30
- ## Scenario B: platform specifics
31
-
32
- Four questions whose answers cannot be derived from general 10DLC knowledge.
33
-
34
- | | Control (no skill) | With skill |
35
- |---|---|---|
36
- | `brandRelationship` allowed values | *empty*, "guessing" | 5 correct values, "certain" |
37
- | `appealCategories` accepted | *empty*, "guessing" | 3 correct values, "certain" |
38
- | `rejectionReason` is an enum? | correct (no) | correct (no) |
39
- | Numbers at creation or after approval? | correct, but read off the tool signature | correct |
40
- | Fix for registry error 503 | **wrong**, "regenerate a unique referenceId and resubmit" | correct: new brand, omit `referenceId` |
41
-
42
- **The 503 answer is the one that matters.** The control's fix sounds right and does not work: a
43
- registry-rejected brand cannot be repaired by resubmitting, it has to be recreated. An operator
44
- following the control's answer loses a cycle on a brand that was never going to clear.
45
-
46
- The control behaved *well*. It returned empty arrays rather than inventing plausible enum
47
- strings, and said so. That is the right failure mode, and it is exactly the gap the skill fills:
48
- without it a careful agent is stuck, and a careless one fabricates.
49
-
50
- ## What the control caught
51
-
52
- Worth recording, because it improved the skill. The control flagged that `503` "doesn't match
53
- standard TCR error semantics, 503 is an HTTP-level service-unavailable code". It was right that
54
- the framing was ambiguous: these are TCR's own codes carried inside the body of an HTTP 400, not
55
- HTTP statuses. `references/tcr-rejection-causes.md` now says so explicitly.
56
-
57
- ## Re-running
58
-
59
- Give both arms the same tool surface, forbid file and search tools, and inline the skill text
60
- for the treatment arm rather than pointing at a path. Assert on Scenario A that no `send_sms`
61
- call precedes an observed `ACTIVE`, and on Scenario B that the enum answers are populated and
62
- marked certain.
@@ -1,104 +0,0 @@
1
- # Why 10DLC registrations get rejected
2
-
3
- Loaded on demand, and only needed once something has actually been rejected.
4
-
5
- Every cause below is drawn from a **real Signal House support ticket** or verified against the
6
- API, with the source noted. Nothing here is general industry knowledge.
7
-
8
- > **Review status:** engineer-verified against support tickets and the API.
9
-
10
- ## How to read a rejection
11
-
12
- `rejectionReason` is **free text, 10 to 256 characters** (verified: `campaign.validation.js`). It
13
- is not an enum and cannot be reliably pattern-matched.
14
-
15
- Registry errors arrive with a numeric code and a description, and the code is the reliable part.
16
- **These are TCR's own error codes, not HTTP status codes**. They arrive *inside* the response
17
- body of what is typically an HTTP 400, in the shape
18
- `External service error: TCR - Request failed with status code 400 - [{ "code": 503, "description": "..." }]`.
19
- A `503` here means "reference id already in use", not "service unavailable". Do not reason about
20
- them as HTTP semantics.
21
-
22
- ## Registry error codes seen in production
23
-
24
- ### 509: "Brand does not qualify for submitted campaign use-case"
25
-
26
- The brand is not eligible for the use case, on carrier-side vetting criteria. Two real cases:
27
- a generic technology company rejected for `UCAAS_HIGH` (which expects a recognized UCaaS
28
- provider), and a brand with `brandScore: 0` rejected for `DELIVERY_NOTIFICATION`.
29
-
30
- **Not retryable.** Resubmitting the same campaign cannot fix it. The two real options are to
31
- switch to a use case the brand qualifies for (`LOW_VOLUME` unblocks immediately), or to re-vet
32
- the brand to earn a qualifying score.
33
-
34
- Related: a brand with `brandScore: null` has not been scored by the registry yet. Campaigns
35
- depending on a score will keep failing until scoring runs, and that is not something the
36
- platform can force.
37
-
38
- ### 501: invalid sub-use-case
39
-
40
- Two distinct real causes share this code.
41
-
42
- **`Invalid sub-usecases: SOCIAL`.** `SOCIAL` is not a valid sub-use-case under any parent,
43
- neither `LOW_VOLUME` nor `MIXED`. Valid sub-use-cases for `LOW_VOLUME` are
44
- `ACCOUNT_NOTIFICATION`, `CUSTOMER_CARE`, `DELIVERY_NOTIFICATION`, `MARKETING`. Signal House's own
45
- validation now rejects `SOCIAL` as a `subUsecases` value with an immediate 400, before the request
46
- reaches TCR, so this 501 should no longer be reachable through the API. `SOCIAL` is still a valid
47
- top-level `usecase`, just never a sub-use-case. If an older campaign carries this rejection,
48
- resubmit with `SOCIAL` removed from `subUsecases`.
49
-
50
- **Punctuation in a tag.** A tag of `maria-answers` was rejected for containing a hyphen. The
51
- campaign content was fine. Fix the tag (`mariaanswers`), then the campaign has to be
52
- re-approved internally before it re-registers.
53
-
54
- ### 503: "Reference ID already in use"
55
-
56
- A duplicate `referenceId` on brand creation. The brand cannot be repaired: create a **new**
57
- brand with the same details and **omit `referenceId` entirely**.
58
-
59
- This is specific to a brand that landed in `TCR_REJECTED`. It is **not** the general rule: a
60
- brand in `UNVERIFIED` can be fixed and re-submitted with an ordinary update (`PUT /brand/:brandId`
61
- calls the registry and writes back its fresh status) or with `PUT /brand/revet/:brandId`. Only
62
- `TCR_REJECTED` refuses both and forces recreation.
63
-
64
- ## Platform-side rejections (before the registry ever sees it)
65
-
66
- **No numbers on the campaign.** Verified in `campaign.service.js`: registration throws
67
- `No phone numbers assigned to campaign with ID <campaignId>`. At least one number must be
68
- attached to the campaign. Confirmed by a real ticket where a campaign was rejected for exactly
69
- this.
70
-
71
- **Campaign not internally approved.** Campaigns wait on Signal House approval before they are
72
- upstreamed to the provider. "Not approved in our system yet" is a distinct state from any
73
- registry rejection.
74
-
75
- ## Content and use-case rejections
76
-
77
- **Missing content attribute for the declared activity.** Real example: *"Campaign is for direct
78
- lending or loan arrangement and is missing content attribute indicating direct lending."* The
79
- campaign's declared attributes have to match what the traffic and landing page actually show.
80
- A landing page saying "no direct lending" while the campaign reads as lending is a rejection.
81
-
82
- ## Adjacent gotchas
83
-
84
- **Brand deletion is blocked by campaigns.** The actual error is
85
- `Cannot delete brand <brandId> because it has active campaigns`, and the gate is broader than
86
- "active" suggests: it blocks on any campaign not yet `EXPIRED`. Campaigns must be cleared first.
87
- A brand can also show `EXPIRED` in Signal House while still `ACTIVE` at the registry, and the two
88
- are not automatically in sync.
89
-
90
- **Brand edits and fees, settled from the code.** Ordinary brand updates are **free**:
91
- `brandUpdate` exists in the fee schedule but is never charged anywhere. Updating landing URLs is
92
- its own path and charges nothing. The $4.50 people ask about is `brandRevet`, and it is only
93
- charged by an explicit re-vet (`PUT /brand/revet/:brandId`), never as a side effect of an edit.
94
- `brandCreate` is the same $4.50 and applies to creating a new brand, which is why a
95
- registry-rejected brand that must be recreated does cost again.
96
-
97
- What an edit *can* cost you is time, not money: changing verification-relevant data moves the
98
- brand `VERIFIED → UNVERIFIED` and it re-verifies.
99
-
100
- **A failed campaign holds its reserved funds.** Funds reserved at campaign creation are released
101
- for `PENDING_REVIEW` / `REJECTED` / `TCR_REGISTER_FAILED` when the campaign is **deleted**, not
102
- at the moment it fails. This is deliberate, because those states are appealable and re-registerable,
103
- but it means a customer who abandons failed campaigns keeps funds tied up. Deleting the dead
104
- campaign frees them.
@@ -1,84 +0,0 @@
1
- ---
2
- name: signalhouse-advisor
3
- description: >-
4
- Planning a Signal House integration: the order the platform actually enforces, which work is
5
- asynchronous and how long it really takes, what the caller's role permits, and which Signal House
6
- skill answers which question.
7
- TRIGGER when the user asks how to build on Signal House, wants an integration plan or timeline,
8
- asks "what do I need to send my first message", is scoping or estimating work, or is deciding
9
- which endpoint or SDK namespace to reach for.
10
- SKIP once the plan is settled and the work is one specific area. Hand off to signalhouse-setup,
11
- signalhouse-10dlc, signalhouse-numbers, signalhouse-sms or signalhouse-webhooks and follow that.
12
- ---
13
-
14
- # Planning a Signal House integration
15
-
16
- ## What cannot happen
17
-
18
- **There is no path from zero to a sent message in one sitting.** Brand and campaign registration go
19
- to external registries and carriers. Approval is measured in **days**, not minutes, and it can be
20
- rejected. Any plan, estimate or demo script that ends "and then we send a test message" on day one
21
- is wrong, and stating it optimistically wastes the customer's launch date rather than saving it.
22
-
23
- **The order is enforced by the platform, not by convention.** Brand before campaign; numbers
24
- attached at campaign creation; campaign `ACTIVE` before any send. A plan that discovers this at step
25
- nine has to be rebuilt from step two.
26
-
27
- **A plan is only executable if the token's role permits it.** Roles are checked server-side and
28
- differ sharply: a customer `api` service user is bound to a single group, `developer` reaches
29
- messaging, numbers, keys and webhooks, `billing` reaches billing only, and the `signalhouse_*` roles
30
- are staff. Confirm what the authenticated caller actually is before planning work it cannot perform.
31
- When the role is unknown, say so and plan against the least privilege rather than assuming `admin`.
32
-
33
- **Nothing about cost may be stated from memory.** Fees are per group, configurable and writable.
34
- `GET /billing/fees/:groupId` is the only correct answer to what something costs, and a number
35
- written into a plan reads as authoritative long after it stops being true.
36
-
37
- ## The pipeline, in the order it must happen
38
-
39
- 1. **Credential and group.** A token, and the `groupId` it is scoped to. `signalhouse-setup`.
40
- 2. **Webhooks.** Before the first write, not after the first surprise. Most of what follows resolves
41
- out of band. `signalhouse-webhooks`.
42
- 3. **Funded wallet.** Registration and number purchase are charged. An unfunded account fails at the
43
- first billable step, which is usually the brand.
44
- 4. **Brand.** Submitted for verification. Days. Can be rejected, and some rejections require
45
- recreating the brand rather than editing it. `signalhouse-10dlc`.
46
- 5. **Numbers.** These can be bought while the brand is still verifying. Buying is not gated; sending is.
47
- `signalhouse-numbers`.
48
- 6. **Campaign.** Created **with its numbers attached**, then registered downstream. More days.
49
- `signalhouse-10dlc`.
50
- 7. **Send.** Only once the campaign is `ACTIVE` and the number is `READY`. `signalhouse-sms`.
51
-
52
- Steps 4 and 5 overlap. Steps 4 and 6 do not.
53
-
54
- ## Asynchronous by design
55
-
56
- Mutating operations across brand, campaign and number return **202** and complete out of band. The
57
- HTTP response means accepted, not done. This shapes the whole integration:
58
-
59
- - **Subscribe, do not poll.** The platform's own guidance says so, and a polling loop hits rate
60
- limits while still finding out late.
61
- - **Every long-running step needs a persisted state machine on the caller's side.** An integration
62
- that holds "waiting for brand approval" in memory loses it on the next deploy.
63
- - **Design for rejection, not just delay.** Brand and campaign both have terminal failure states. A
64
- flow with no path for "rejected, here is why" is unfinished.
65
-
66
- ## Which skill answers which question
67
-
68
- | The question | Skill |
69
- |---|---|
70
- | How do I authenticate, what token, why a 401 | `signalhouse-setup` |
71
- | How do I know when something finished | `signalhouse-webhooks` |
72
- | Why is my campaign rejected or stuck, what does TCR need | `signalhouse-10dlc` |
73
- | How do I find, buy, or release numbers, what do they cost | `signalhouse-numbers` |
74
- | How do I send, why did a send fail, what does a message cost | `signalhouse-sms` |
75
-
76
- If a question spans two of these, answer with the constraint first and the mechanics second. The
77
- constraint is nearly always the part that changes the plan.
78
-
79
- ## Where to look it up
80
-
81
- - **The full setup pipeline:** the Brands and Campaigns references
82
- (https://app2.signalhouse.io/docs/brands, https://app2.signalhouse.io/docs/campaigns).
83
- - **A first working call:** https://app2.signalhouse.io/docs/getting-started.
84
- - **Current fees and balance:** the billing endpoints, read live, per group.
@@ -1,82 +0,0 @@
1
- ---
2
- name: signalhouse-numbers
3
- description: >-
4
- Signal House phone numbers: the search, purchase and list flow, and what a purchase commits
5
- the account to financially.
6
- TRIGGER when the user is searching for, buying, listing or releasing Signal House numbers;
7
- when they are scripting or bulk-buying numbers; when a purchase fails; or when they ask what
8
- numbers cost or why their balance dropped.
9
- SKIP for toll-free verification and short-code provisioning, for porting numbers in, and for
10
- assigning an existing number to a campaign, which belongs to 10DLC registration.
11
- ---
12
-
13
- # Signal House phone numbers
14
-
15
- ## What cannot happen
16
-
17
- **Releasing a number is irreversible.** `DELETE /number` sets the number to `RELEASED`, and
18
- **nothing transitions a number out of `RELEASED`**. It cannot be reactivated (reactivation
19
- requires `DEACTIVATED`), cannot be assigned to a campaign, and cannot be re-deleted. The number
20
- management guide says it plainly: released numbers cannot be recovered. Treat a release request
21
- as destructive and confirm it explicitly, every time.
22
-
23
- **A bulk local purchase has no ceiling.** `POST /number` accepts a `phoneNumbers` array with a
24
- minimum of 1 and **no maximum**, unlike campaign assignment, which caps at 5000. Passing a whole
25
- search page buys a whole search page. If a caller asks for "some numbers", establish the count
26
- before purchasing, not after.
27
-
28
- Toll-free is different: those purchases are capped at 10 per order and additionally gated by a
29
- per-group toll-free flag. The unbounded risk above is specific to local numbers.
30
-
31
- **A number is not sendable just because it was purchased.** It has to be attached to a campaign,
32
- and that campaign has to be `ACTIVE`. See the `signalhouse-10dlc` skill.
33
-
34
- ## Order of operations
35
-
36
- 1. **Search** for available numbers, filtered to what is actually needed (state, area code,
37
- SMS/MMS capability). Searching and NPA/NXX lookup are **free**, with no billing call on those
38
- paths, so filter properly rather than buying to find out.
39
- 2. **Confirm the count and the cost** before purchasing. Read current fees from
40
- `GET /billing/fees/:groupId`. Do not assume a price or carry one over from a previous run.
41
- 3. **Purchase** the specific numbers chosen. `subgroupId` is required, and the subgroup must
42
- exist and be active.
43
- 4. **List** to confirm what the account now owns and is paying for.
44
-
45
- Numbers can be purchased while a brand is still verifying. There is no brand or campaign gate on
46
- the purchase path. What must wait is sending, not buying.
47
-
48
- ## Spend awareness
49
-
50
- The rule to hold: **the account is billed for what it owns, not for what it uses.**
51
-
52
- **Purchase is charged immediately**, per number, on both the local and toll-free paths.
53
-
54
- **Renewal is recurring, but it is environment-gated.** There is a renewal scheduler that charges a
55
- per-number renewal fee on a billing date. It only runs when `ENABLE_NUMBER_BILLING_RENEWALS` is
56
- enabled, and that flag is **off by default** with the real value set per environment. So:
57
-
58
- - Never tell a customer that numbers have no ongoing cost. The mechanism exists and is the
59
- intended behaviour.
60
- - Never quote the renewal as definitely active either. If it matters to the answer, check the
61
- environment rather than asserting.
62
- - The renewal fee is applied to toll-free numbers too, despite being named for local ones.
63
-
64
- **Repeated renewal failures delete the number.** After a configured number of failed renewal
65
- attempts the number is queued for deletion, and deletion is the irreversible release above. A
66
- customer whose balance is empty does not simply go unbilled; they can lose the number.
67
-
68
- Before any purchase, be able to state how many numbers are being bought and the current
69
- per-number fee, read live. If either is unknown, ask rather than buy.
70
-
71
- Never quote a price from memory or from this file. Fees are per-group and configurable,
72
- and writable via `PUT /billing/fees/:groupId`, so a number here would be both stale and
73
- authoritative-looking. `GET /billing/fees/:groupId` is the only correct answer to "what does this
74
- cost".
75
-
76
- ## Where to look it up
77
-
78
- - **Search filters, NPA/NXX lookup, friendly names, per-number inbound webhook URLs, and the
79
- release semantics:** the Numbers reference, https://app2.signalhouse.io/docs/numbers.
80
- - **Current fees:** `GET /billing/fees/:groupId`.
81
- - **Current balance before a bulk buy:** the wallet endpoints under `/billing/wallet`.
82
- - **Whether a number can send:** its campaign's state, not the number's. See `signalhouse-10dlc`.
@@ -1,121 +0,0 @@
1
- ---
2
- name: signalhouse-setup
3
- description: >-
4
- Getting a Signal House integration authenticated and wired: login vs service-user tokens, what a
5
- token is scoped to, SDK initialization, and why webhooks come before the first write.
6
- TRIGGER when the user is starting a Signal House integration, asks how to authenticate, asks for
7
- an API key or token, is choosing a base URL, is installing or initializing the SDK, is connecting
8
- Claude, Cursor or another AI client to Signal House (MCP), is getting a 401 or 403, or asks why
9
- their token stopped working.
10
- SKIP for message sending, 10DLC registration, number purchase and webhook event semantics, which
11
- have their own skills. This one ends at "the first authenticated call succeeds".
12
- ---
13
-
14
- # Signal House setup
15
-
16
- ## What cannot happen
17
-
18
- **A login token cannot carry a server integration.** `POST /auth` returns a **short-lived session
19
- JWT**, measured in hours. It is the right token for a user acting in a session and the wrong token
20
- for anything that runs unattended. A cron job built on a login token works all afternoon and fails
21
- overnight.
22
-
23
- Both lifetimes are set per environment (`JWT_USER_EXPIRES_IN`, `JWT_SYSTEM_EXPIRES_IN`), so treat
24
- the session token as short and the service token as long, and read the exact values from the
25
- Authentication guide or the environment rather than quoting a number to a customer.
26
-
27
- **A service user cannot be bootstrapped from nothing.** `POST /user/serviceuser` needs an existing
28
- group and a token that is already privileged enough to mint one. The first credential in a new
29
- integration comes from a human logging in (including approving an OAuth connection, below) or from
30
- Signal House provisioning it, not from an API call made with no credential.
31
-
32
- **`role: "signalhouse_api"` is not available to customers.** The two roles `POST /user/serviceuser`
33
- accepts are `api` (customer key, scoped to one `groupId`) and `signalhouse_api` (internal, requires
34
- `signalhouse_admin` credentials). A customer caller asking for the internal role gets a **403**. If
35
- an integration seems to need it, the requirement is wrong.
36
-
37
- **The API key is shown once.** The token is signed and returned at creation and never stored on the
38
- user record, so no endpoint can hand it back. Losing it means creating another service user, not
39
- recovering the old key.
40
-
41
- **A group under compliance rejection cannot create API keys at all.** Service-user creation is gated
42
- on the group's compliance state and fails with a group-rejected error rather than a validation error.
43
- Staff roles are exempt. When key creation fails for one group and works for another, check the
44
- account's standing before debugging the request.
45
-
46
- **Being authenticated does not mean being able to send.** Setup ends with a working credential.
47
- Sending additionally requires a verified brand, an `ACTIVE` campaign, and a number in `READY` status
48
- on it. See `signalhouse-10dlc`.
49
-
50
- ## Order of operations
51
-
52
- 1. **Get a token.** Human session → `POST /auth`, short-lived. Server integration → a service user,
53
- long-lived. Do not build a server integration on a login token and plan to "refresh it later".
54
- 2. **Know the group.** A customer service user (`role: "api"`) is bound to one `groupId`, an
55
- 8-character id beginning with `G`. That scoping is what limits the damage of a leaked
56
- key, so one key per group is the design, not an inconvenience to work around.
57
- 3. **Initialize the SDK** with `apiKey` and `baseUrl`. The `apiKey` is the default credential on
58
- every request; `options: { token }` overrides it per call, which is how an app acting for many
59
- users should work rather than reinitializing the SDK per user.
60
- 4. **Make one read call** and check the envelope before writing anything.
61
- 5. **Register webhooks before the first write.** Brand registration, campaign registration, number
62
- purchase and message delivery all resolve out of band, minutes to days later. An integration
63
- without webhooks discovers outcomes by polling, burns rate limit doing it, and still finds out
64
- late. See `signalhouse-webhooks`.
65
-
66
- ## Connecting an AI client (MCP)
67
-
68
- Signal House runs a hosted MCP server at `https://mcp.signalhouse.io/mcp`. It holds no credentials
69
- of its own: every call is forwarded to the API with the caller's own token, so an agent can do
70
- exactly what that token can do and nothing more.
71
-
72
- - **Claude (web, Desktop, mobile): connect with OAuth.** Settings > Connectors > Add custom
73
- connector, paste the URL, leave the client ID and secret blank, then log in to Signal House and
74
- approve. No API key is copied anywhere. This is the path to recommend to a person.
75
- - **Clients configured by file or command (Claude Code, Cursor and similar):** send an API key as a
76
- bearer header, e.g.
77
- `claude mcp add --transport http signalhouse https://mcp.signalhouse.io/mcp --header "Authorization: Bearer <API key>"`.
78
- Claude Code can also do the OAuth flow: add it without the header and authenticate from `/mcp`.
79
-
80
- What an OAuth connection can and cannot do:
81
-
82
- - **It acts as the user who approved it, with that user's full role.** Scopes are not enforced, so
83
- do not tell a customer a connection is "read-only" or limited to part of the account.
84
- - **It cannot mint credentials or manage the login.** Routes under `/user` and `/auth` refuse a
85
- connector token with a **403**, so an agent on an OAuth connection cannot create service users or
86
- API keys. A 403 there is by design, not a bug to work around; create keys in the portal.
87
- - **It is revoked by the user**, in the portal under Settings > Security > Connected Applications.
88
- After that the client has to reconnect.
89
-
90
- For an unattended server integration, the rules above still hold: use a service-user API key, not
91
- an OAuth connection, which exists for a person working through an AI client.
92
-
93
- ## Reading the response
94
-
95
- The SDK returns an **envelope**, and most failures arrive inside it rather than as an exception:
96
-
97
- ```
98
- { success: true|false, data: <payload>, error: <body>, status: <http status> }
99
- ```
100
-
101
- - Branch on `response.success` and `response.status`, not on a try/catch alone.
102
- - **Rate limiting is a `429` in the envelope**, not a throw. Detect it as `response.status === 429`
103
- and back off; matching on the error string is brittle.
104
- - Client-side validation failures DO throw (`SignalHouseValidationError`). Those are not retryable,
105
- and retrying an invalid payload just spends the retry budget.
106
- - A `401` means the token expired or was revoked. Re-authenticate; do not retry the same token.
107
-
108
- Response shapes are nested differently per endpoint and the nesting is not guessable. Read the
109
- current shape from the API reference rather than assuming it matches a sibling endpoint.
110
-
111
- ## Where to look it up
112
-
113
- - **Auth flows, service users, the full role table, token practice:** the Authentication reference,
114
- https://app2.signalhouse.io/docs/authentication.
115
- - **The OAuth connection flow:** https://app2.signalhouse.io/docs/oauth.
116
- - **First working call end to end:** https://app2.signalhouse.io/docs/getting-started.
117
- - **Envelope shapes, error classes and status codes:** https://app2.signalhouse.io/docs/error-handling.
118
- - **Backoff, batching and pagination:** https://app2.signalhouse.io/docs/rate-limits.
119
- - **What a role is allowed to do:** the role table in the Authentication reference. Roles are
120
- checked server-side, so a plan that assumes more access than the token has fails at the call, not
121
- earlier.