@signalhousellc/sdk 1.4.0 → 1.4.1

package/package.json

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

package/skills/signalhouse-webhooks/SKILL.md

@@ -17,14 +17,17 @@ description: >-
 **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.
+can hand it back. If it is lost or exposed, rotate it: `POST /webhook/:id/rotate-secret` returns a new
+secret once, and the old one keeps working for a grace window (`graceSeconds`, default 24h, max 7
+days, `0` for none) so the receiver can switch over without dropping deliveries.
 
 A signed delivery carries:
 
 | Header | Value |
 |---|---|
-| `X-SignalHouse-Signature` | hex HMAC-SHA256, keyed with the signing secret, over `${timestamp}.${rawBody}` |
+| `X-SignalHouse-Signature` | hex HMAC-SHA256, keyed with the signing secret, over `${timestamp}.${rawBody}`. During a rotation grace window it stays on the **previous** secret and switches when the window ends |
 | `X-SignalHouse-Timestamp` | the `timestamp` in that string: Unix time in **milliseconds** |
+| `X-SignalHouse-Signature-V1` | `t=<ms>,v1=<hex>[,v1=<hex>]`: one signature per currently valid secret, newest first. During a rotation grace window it carries both the new and the previous secret's signature; accept a match on any |
 | `X-SignalHouse-Delivery-Id` | a UUID for this event to this endpoint, the same on every retry |
 
 A correct verifier:
@@ -37,12 +40,18 @@ A correct verifier:
    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.
+5. **Prefers `X-SignalHouse-Signature-V1`**, so a secret rotation never breaks verification.
+
+In Node, `verifyWebhookSignature` from `@signalhousellc/sdk/webhooks` does all of this and returns
+`{ valid, reason }` without throwing. Other languages implement the five steps directly; the
+Webhook Signing guide has a Python version.
 
 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.
+- **Endpoints created before signing shipped (2026-09-03) are sent unsigned** until they get a
+  secret. They report `hasSigningSecret: false`. Call `POST /webhook/:id/rotate-secret` once (or use
+  *Create signing secret* in the portal's webhook edit view) to issue their first secret; deliveries
+  are signed from then on.
 - **Per-number inbound URLs are never signed** (see below).
 
 For anything unsigned, the old rules still apply: do not treat the request as authenticated, and
@@ -50,9 +59,10 @@ never take an irreversible or financial action on webhook content alone. Read th
 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.
 
-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.
+The `authType` setting (`NONE`, `BASIC`, `API_KEY`, `OAUTH2`, `HMAC`) chooses what *else* Signal
+House sends to the receiver. Signing does not depend on it: every endpoint with a secret is signed
+whatever `authType` says. `BASIC`/`API_KEY`/`OAUTH2` add credentials as a second layer; `HMAC` sends
+none and declares that the receiver authenticates by the signature alone.
 
 ## Retry behaviour, and when an event is gone
 
@@ -100,7 +110,7 @@ So a correct receiver:
 
 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`.
+`{ key, secret }`, required whenever `authType` is not `NONE` or `HMAC` (and rejected with those two).
 
 | authType | What is sent |
 |---|---|
@@ -108,10 +118,10 @@ Webhooks are created per group, and numbers can additionally carry their own inb
 | `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 |
+| `HMAC` | no credentials and no Authorization header; the receiver verifies the signature headers. Rejected for an endpoint with no signing secret until it has one |
 
-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.
+Verify the signature on every endpoint that has one. `HMAC` (or `NONE`) is fine for a receiver
+that verifies signatures; `BASIC` or `API_KEY` on top 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
@@ -124,7 +134,9 @@ signed group endpoint instead.
 
 ## Where to look it up
 
-- **Event types, payload shape and the signing scheme:** the Webhooks reference,
+- **The signing scheme, verification and rotation:** the Webhook Signing guide,
+  https://app2.signalhouse.io/docs/webhook-signing.
+- **Event types and payload shape:** 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`

package/src/domains/Agents.js

@@ -143,6 +143,24 @@
  * @property {boolean} [allowGreetingInterruption] - Whether a caller may talk over the greeting.
  * @property {string[]} [keyterms] - Words the transcriber is biased toward — names, jargon, unusual spellings.
  * @property {Object|null} [backgroundSound] - Ambient audio bed as `{ preset, volume }`; null = silence.
+ * @property {AgentWorkflow|null} [workflow] - Conversation workflow graph. Voice channel only — sending one on webchat or sms is a 400. null = no workflow.
+ */
+
+/**
+ * A conversation workflow graph, in the voice runtime's own shape. Nodes and edges are keyed
+ * maps rather than arrays: an edge names its endpoints by node key, and a node's `edge_order`
+ * names its outgoing edges in the order their conditions are evaluated.
+ *
+ * Node bodies are deliberately not enumerated here. Node types are defined by the runtime and
+ * new ones appear without an SDK release, so the SDK passes them through untouched. The API
+ * validates the envelope — an entry point under the node key `start_node` typed `start` (the
+ * runtime looks it up by that exact key), no second `start` node, at most 200 nodes, and every
+ * edge endpoint naming a node that exists — and rejects a graph that fails any of those.
+ * @typedef {Object} AgentWorkflow
+ * @property {Object<string, Object>} nodes - Nodes keyed by node id. Each carries at least `type` and `position` ({ x, y }).
+ * @property {Object<string, Object>} edges - Edges keyed by edge id. Each carries `source` and `target` node ids.
+ * @property {Object<string, Object>} [subgraphs] - Nested subgraphs keyed by subgraph id.
+ * @property {boolean} [prevent_subagent_loops] - Stop a subagent handing control back to one that already ran.
  */
 
 export class Agents {
@@ -234,14 +252,16 @@ export class Agents {
 	}
 
 	/**
-	 * Delete (inactivate) an agent profile by its id.
+	 * Permanently delete an agent profile by its id.
+	 *
+	 * Permanently deletes the agent, its channel settings, and any tools and knowledge scoped to it, plus their provider-side counterparts. Tools and knowledge shared across the account are untouched. Conversation records survive — a transcript outlives the agent that produced it.
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for deleting an agent profile.
 	 * @param {string} params.id - The id of the agent profile to delete.
 	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the id parameter is missing.
-	 * @returns {Promise<SdkResponse<any>>} - The inactivated agent profile returned from the server.
+	 * @returns {Promise<Object>} - The deleted agent profile, as it was.
 	 */
 	async deleteAgentProfile({ id, options = {} }) {
 		this.client._require({ id });

package/src/domains/Messages.js

@@ -300,11 +300,12 @@ export class Messages {
 	 * @param {("day"|"exact")} [params.dateBounds] - Which contract binds startDate/endDate. "day": each bound is widened to its whole UTC day. "exact": a timestamp is bound as the instant it names and a bare date is its whole UTC day. Omitted: "day".
 	 * @param {string|string[]} [params.region] - ISO-2 country filter: US, GB or CA (any case of UK/GB/GBR/United Kingdom is accepted for GB); one value, an array, or a comma-separated string; omitted = every region. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
 	 * @param {Object[]|string} [params.regionScopes] - Array of OR-ed branches `{ region, channels, brandId?, campaignId?, phoneNumber? }` (channels among tenDLC, virtualLongCode, tollFree, shortCode, p2p); `[]` matches nothing. Sent as JSON unless already a string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400.
+	 * @param {string} [params.errorCode] - Narrow the breakdown to a single failure reason: a numeric Infobip carrier code (as a string, e.g. "607"), the Signal House campaign-opt-out code "OUT", or a no-code failure class (other, moderation, att_limit, p2p_stop, campaign_opt_out, dnc_blocked, bind_hold_expired). Omitted = every reason.
 	 * @param {RequestOptions} [params.options]
 	 * @returns {Promise<SdkResponse<any>>} - { rows, totalCount, totalErrors: { sms, mms, p2p, all }, page, limit }
 	 */
-	async getAnalyticsByErrorCode({ groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, region, regionScopes, dateBounds, options = {} }) {
-		const filters = { groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, region, regionScopes, dateBounds };
+	async getAnalyticsByErrorCode({ groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, region, regionScopes, dateBounds, errorCode, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, registrationId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, region, regionScopes, dateBounds, errorCode };
 		const queryString = this.client._getQueryString(withRegionScopes(filters));
 		return this.client(`/message/analytics/by-error-code${queryString}`, { method: "GET", ...options });
 	}

package/src/domains/Users.js

@@ -31,6 +31,7 @@
  * @property {string} role - The role of the service user: "api" for a customer API key (required)
  * @property {string[]} [allowedIps] - Only accept this API key from these IPv4/IPv6 addresses or CIDR ranges (max 100). Omit or pass [] for no IP restriction. Customer API keys only.
  * @property {string[]} [allowedCountries] - Only accept this API key from these countries, as ISO 3166-1 alpha-2 codes such as "US" (max 250). Omit or pass [] for no country restriction. Customer API keys only.
+ * @property {string[]} [allowedDestinationCountries] - Only let this API key send messages to these countries, as ISO 3166-1 alpha-2 codes such as "US" (max 250). Sends to any other country are rejected with a 403 DESTINATION_COUNTRY_NOT_ALLOWED. Omit or pass [] for any country. Customer API keys only.
  */
 
 /**
@@ -51,6 +52,7 @@
  * @property {string} [status] - The status of the user (e.g., "active", "inactive")
  * @property {string[]} [allowedIps] - Customer API keys only: replace the key's allowed IPv4/IPv6 addresses or CIDR ranges ([] removes the restriction). Requires an interactive admin or developer session; an API key cannot change its own restrictions.
  * @property {string[]} [allowedCountries] - Customer API keys only: replace the key's allowed ISO 3166-1 alpha-2 country codes ([] removes the restriction). Requires an interactive admin or developer session.
+ * @property {string[]} [allowedDestinationCountries] - Customer API keys only: replace the countries the key may send messages to ([] allows any country). Requires an interactive admin or developer session.
  */
 
 export class Users {

package/src/domains/Webhooks.js

@@ -40,7 +40,9 @@ export class Webhooks {
 	 * same event, for receiver-side dedup), plus `X-SignalHouse-Signature-V1` (`t=<ms>,v1=<hex>[,v1=<hex>]`,
 	 * every currently valid signature). Store this secret now: it is never returned again by any read
 	 * (SHGHL-2944). If it's lost, call `rotateWebhookSecret`. Verify deliveries with
-	 * `verifyWebhookSignature` from `@signalhousellc/sdk/webhooks` (Node only).
+	 * `verifyWebhookSignature` from `@signalhousellc/sdk/webhooks` (Node only). `webhookData.authType` is one of
+	 * `NONE` (default), `BASIC`, `API_KEY`, `OAUTH2` or `HMAC`; `HMAC` (SHGHL-3595) sends no credentials, so the
+	 * receiver authenticates by the signature alone, and must be sent without `credentials` or `apiHeaderPrefix`.
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for creating a webhook
@@ -58,7 +60,9 @@ export class Webhooks {
 	 * Update an existing webhook with the specified data. `updateData` may include `name`, `url`,
 	 * `subscribedEvents` and (SHGHL-3486) `authType`, `apiHeaderPrefix` and `credentials` (`{ key, secret? }`)
 	 * to change the endpoint's own credentials in place: credentials are required when switching to an auth
-	 * type that needs them, and omitted credentials keep the stored ones. Like every read of a webhook, the
+	 * type that needs them, and omitted credentials keep the stored ones. Switching to `NONE` or `HMAC` clears
+	 * the stored credentials; `HMAC` is rejected for an endpoint with no signing secret (call
+	 * `rotateWebhookSecret` first). Like every read of a webhook, the
 	 * response carries `hasSigningSecret` and `hasCredentials` (booleans), never a secret or credential.
 	 * @async
 	 * @roles api, admin, developer

package/src/domains/voice/ProgrammableVoiceProfiles.js

@@ -9,12 +9,13 @@
  * @property {string} name - Profile name (required).
  * @property {string[]} subgroupIds - Subgroups this profile spans (required, at least one).
  * @property {string} [region] - Region/POP label.
- * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"|"CALL_CONTROL"} [routeAction] - Inbound call action (default "FORWARD"). Deliver the call to a PSTN number (FORWARD), ring the profile's subgroup registered softphones (WEBRTC), send to a SIP trunk (SIP_TRUNK), ring a registered SIP endpoint (SIP_PROFILE), or hand the call to your programmable call-control webhook that returns SHML (CALL_CONTROL).
+ * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"|"CALL_CONTROL"|"AI"} [routeAction] - Inbound call action (default "FORWARD"). Deliver the call to a PSTN number (FORWARD), ring the profile's subgroup registered softphones (WEBRTC), send to a SIP trunk (SIP_TRUNK), ring a registered SIP endpoint (SIP_PROFILE), hand the call to your programmable call-control webhook that returns SHML (CALL_CONTROL), or answer it with an AI agent (AI).
  * @property {string} [forwardToE164] - Destination number, required when routeAction is "FORWARD".
  * @property {number} [forwardAfterSeconds] - Ring seconds before the action fires.
  * @property {string} [routeSipTrunkId] - SIP trunk id, required when routeAction is "SIP_TRUNK".
  * @property {string} [routeSipProfileId] - SIP endpoint id, required when routeAction is "SIP_PROFILE".
  * @property {string} [webhookUrl] - Your inbound voice webhook (SHML program URL), required when routeAction is "CALL_CONTROL". Inbound calls to this profile's numbers are driven by the SHML your webhook returns.
+ * @property {string} [routeAgentProfileId] - AI agent profile id (AGP…), required when routeAction is "AI". The agent's prompt, voice, model and tools are read when the call lands, so editing the agent takes effect on the next call with nothing to re-save here.
  * @property {boolean} [recordingEnabled] - Record calls on this profile.
  * @property {boolean} [enabled] - Active state (default true).
  */
@@ -24,12 +25,13 @@
  * @property {string} [name] - Profile name.
  * @property {string[]} [subgroupIds] - Subgroups this profile spans.
  * @property {string|null} [region] - Region/POP label.
- * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"|"CALL_CONTROL"} [routeAction] - Inbound call action (FORWARD | WEBRTC | SIP_TRUNK | SIP_PROFILE | CALL_CONTROL).
+ * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"|"CALL_CONTROL"|"AI"} [routeAction] - Inbound call action (FORWARD | WEBRTC | SIP_TRUNK | SIP_PROFILE | CALL_CONTROL | AI).
  * @property {string|null} [forwardToE164] - FORWARD destination.
  * @property {number|null} [forwardAfterSeconds] - Ring seconds before the action fires.
  * @property {string|null} [routeSipTrunkId] - SIP trunk id (required when routeAction is "SIP_TRUNK").
  * @property {string|null} [routeSipProfileId] - SIP endpoint id (required when routeAction is "SIP_PROFILE").
  * @property {string|null} [webhookUrl] - Inbound voice webhook / SHML program URL (required when routeAction is "CALL_CONTROL"). Pass null to clear.
+ * @property {string|null} [routeAgentProfileId] - AI agent profile id (AGP…), required when routeAction is "AI". Pass null to clear.
  * @property {boolean} [recordingEnabled] - Record calls on this profile.
  * @property {boolean} [enabled] - Active state.
  */