@signalhousellc/sdk 1.0.68 → 1.1.0

package/src/domains/Registrations.js

@@ -0,0 +1,240 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
+/**
+ * Sender registrations for every jurisdiction and type: the catalog of what a region offers, retail quotes,
+ * customer submissions and staff review operations. `type` selects the shape of `data`
+ * (for VIRTUAL_LONG_CODE: quantity, useCases and the optional voice dossier).
+ */
+export class Registrations {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+
+		if (enableAdmin) {
+			this.admin = {
+				/**
+				 * Approve or reject a registration awaiting Signal House review (signalhouse only)
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for the review decision
+				 * @param {string} params.registrationId - The registration ID (e.g. GB8T9GTD5AZY)
+				 * @param {("APPROVE"|"REJECT")} params.action - The review decision
+				 * @param {string} [params.reason] - Why the registration was rejected; required when action is REJECT
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated registration
+				 */
+				reviewRegistration: async ({ registrationId, action, reason, options = {} }) => {
+					this.client._require({ registrationId, action });
+					const safeId = encodeURIComponent(registrationId);
+					return this.client(`/registration/${safeId}/review`, {
+						method: "POST",
+						body: { action, reason },
+						...options,
+					});
+				},
+
+				/**
+				 * Save corrections to the type's correctable fields for a registration the provider sent back for
+				 * more information; owner, quantity, bundle and provider order never change (signalhouse only)
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for the correction
+				 * @param {string} params.registrationId - The registration ID (e.g. GB8T9GTD5AZY)
+				 * @param {string} params.reason - Why the registration was corrected
+				 * @param {Object} params.data - The type's correctable fields (for VIRTUAL_LONG_CODE: useCases and, for SMS + Voice, voice)
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated registration
+				 */
+				correctRegistration: async ({ registrationId, reason, data, options = {} }) => {
+					this.client._require({ registrationId, reason, data });
+					const safeId = encodeURIComponent(registrationId);
+					return this.client(`/registration/${safeId}/corrections`, {
+						method: "POST",
+						body: { reason, data },
+						...options,
+					});
+				},
+
+				/**
+				 * Allocate a provider-owned number to a registration through the staff recovery path (signalhouse only)
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for the allocation
+				 * @param {string} params.registrationId - The registration ID (e.g. GB8T9GTD5AZY)
+				 * @param {string} params.phoneNumber - The E.164 number (10-15 digits, optional leading +) to allocate
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated registration
+				 */
+				addNumber: async ({ registrationId, phoneNumber, options = {} }) => {
+					this.client._require({ registrationId, phoneNumber });
+					const safeId = encodeURIComponent(registrationId);
+					return this.client(`/registration/${safeId}/numbers`, {
+						method: "POST",
+						body: { phoneNumber },
+						...options,
+					});
+				},
+
+				/**
+				 * Link an existing provider order to a registration parked in RECONCILIATION_REQUIRED (signalhouse only)
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for the reconciliation
+				 * @param {string} params.registrationId - The registration ID (e.g. GB8T9GTD5AZY)
+				 * @param {string} params.externalId - The provider's identifier for the existing order
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated registration
+				 */
+				reconcile: async ({ registrationId, externalId, options = {} }) => {
+					this.client._require({ registrationId, externalId });
+					const safeId = encodeURIComponent(registrationId);
+					return this.client(`/registration/${safeId}/reconcile`, {
+						method: "POST",
+						body: { externalId },
+						...options,
+					});
+				},
+
+				/**
+				 * Download the completed carrier application as DOCX bytes (signalhouse only)
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for the download
+				 * @param {string} params.registrationId - The registration ID (e.g. GB8T9GTD5AZY)
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<ArrayBuffer>>} A promise that resolves to the DOCX document as an ArrayBuffer
+				 */
+				getApplication: async ({ registrationId, options = {} }) => {
+					this.client._require({ registrationId });
+					const safeId = encodeURIComponent(registrationId);
+					return this.client(`/registration/${safeId}/application`, {
+						method: "GET",
+						responseType: "arraybuffer",
+						...options,
+					});
+				},
+			};
+		}
+	}
+
+	/**
+	 * Get the registration types a region offers and whether each can be acquired right now
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for the catalog
+	 * @param {string} params.region - ISO-2 jurisdiction (US, GB or CA; UK is accepted for GB)
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} A promise that resolves to { region, jurisdiction, sendingRequiresRegistration, registeredThrough, provisioning, types }
+	 */
+	async getCatalog({ region, options = {} }) {
+		this.client._require({ region });
+		const queryString = this.client._getQueryString({ region });
+		return this.client(`/registration/catalog${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get retail quotes for a registration type: one quote per capability bundle with per-number setupAmount
+	 * and monthlyAmount, the totals for the quantity (integer microdollars) and etaDays.
+	 * Unavailable (400) while the type cannot be acquired in the region.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for the quote
+	 * @param {string} params.region - ISO-2 jurisdiction (UK is accepted for GB)
+	 * @param {string} params.type - Registration type (e.g. VIRTUAL_LONG_CODE)
+	 * @param {number} [params.quantity=1] - Number of numbers to quote (1-100)
+	 * @param {string} [params.groupId] - Group to price for; staff only
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} A promise that resolves to { data: [quotes] }
+	 */
+	async getQuotes({ region, type, quantity = 1, groupId, options = {} }) {
+		this.client._require({ region, type });
+		const queryString = this.client._getQueryString({ region, type, quantity, groupId });
+		return this.client(`/registration/quotes${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * List registrations for an authorized group; staff may omit groupId to read the review queue
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} [params] - The parameters for filtering the registrations
+	 * @param {string} [params.groupId] - Filter by group ID
+	 * @param {string} [params.subgroupId] - Filter by subgroup ID
+	 * @param {string|string[]} [params.region] - Filter by one ISO-2 jurisdiction or a list
+	 * @param {string} [params.type] - Filter by registration type
+	 * @param {string} [params.kind] - Filter by kind (identity, program, sender)
+	 * @param {string|string[]} [params.status] - Filter by one registration status or a list
+	 * @param {string} [params.parentRegistrationId] - Filter by the parent registration ID
+	 * @param {string} [params.phoneNumber] - Filter to registrations holding this phone number
+	 * @param {string} [params.sortBy] - Sort field: createdAt (default), subgroupId, registrationId, region or status
+	 * @param {string} [params.sortOrder] - Sort direction: asc or desc (default)
+	 * @param {number} [params.page] - Page number (default 1)
+	 * @param {number} [params.limit] - Registrations per page (default 25, max 100)
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} A promise that resolves to { data: [registrations], totalCount, page, limit }
+	 */
+	async getRegistrations({ groupId, subgroupId, region, type, kind, status, parentRegistrationId, phoneNumber, sortBy, sortOrder, page, limit, options = {} } = {}) {
+		const queryString = this.client._getQueryString({ groupId, subgroupId, region, type, kind, status, parentRegistrationId, phoneNumber, sortBy, sortOrder, page, limit });
+		return this.client(`/registration${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single registration with its review outcome, the type's public data and its status history
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for getting the registration
+	 * @param {string} params.registrationId - The registration ID (e.g. GB8T9GTD5AZY)
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} A promise that resolves to the registration
+	 */
+	async getRegistration({ registrationId, options = {} }) {
+		this.client._require({ registrationId });
+		const safeId = encodeURIComponent(registrationId);
+		return this.client(`/registration/${safeId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Cancel a registration. Allowed from SIGNAL_HOUSE_REVIEW, SIGNAL_HOUSE_APPROVED, PENDING_PROVIDER, NEEDS_INFORMATION,
+	 * PAYMENT_REQUIRED and APPROVED (409 otherwise). Numbers already allocated stay on the account and stop sending.
+	 * @async
+	 * @roles api, admin, developer, user
+	 * @param {Object} params - The parameters for cancelling the registration
+	 * @param {string} params.registrationId - The registration ID (e.g. GB8T9GTD5AZY)
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} A promise that resolves to the cancelled registration
+	 */
+	async cancelRegistration({ registrationId, options = {} }) {
+		this.client._require({ registrationId });
+		const safeId = encodeURIComponent(registrationId);
+		return this.client(`/registration/${safeId}`, { method: "DELETE", ...options });
+	}
+
+	/**
+	 * Submit a registration. `type` selects the shape of `data`: for VIRTUAL_LONG_CODE it is { quantity (1-100),
+	 * useCases (1-10 descriptions), voice? } where voice is required exactly when capabilities include VOICE.
+	 * Reuse the same clientRequestId only when retrying an identical payload (409 otherwise).
+	 * Unavailable (400) while the type cannot be acquired in the region.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for the registration
+	 * @param {string} params.region - ISO-2 jurisdiction (UK is accepted for GB)
+	 * @param {string} params.type - Registration type (e.g. VIRTUAL_LONG_CODE)
+	 * @param {string} params.subgroupId - Subgroup that will own the registration and any allocated numbers
+	 * @param {string} params.clientRequestId - Idempotency key (UUID)
+	 * @param {string[]} params.capabilities - One of the type's bundles, e.g. ["SMS"] or ["SMS", "VOICE"]
+	 * @param {Object} params.data - The type's submission fields
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} A promise that resolves to the created registration
+	 */
+	async createRegistration({ region, type, subgroupId, clientRequestId, capabilities, data, options = {} }) {
+		this.client._require({ region, type, subgroupId, clientRequestId, capabilities, data });
+		return this.client("/registration", {
+			method: "POST",
+			body: { region, type, subgroupId, clientRequestId, capabilities, data },
+			...options,
+		});
+	}
+}

package/src/domains/Users.js

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

package/src/domains/Webhooks.js

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

package/src/webhooks/verifySignature.js

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