@messagebird/sdk 0.42.0 → 0.43.0

package/dist/index.mjs

@@ -785,6 +785,17 @@ var BirdTimeoutError = class extends BirdError {
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
 };
+/**
+* An API call on a client constructed without `apiKey` (a receiver-only
+* client, which can still `unwrap` webhooks). Thrown before any request.
+*/
+var BirdMissingApiKeyError = class extends BirdError {
+	constructor(message) {
+		super(message);
+		this.name = "BirdMissingApiKeyError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
 /** A webhook payload failed signature verification (bad signature, stale timestamp, malformed headers). */
 var BirdWebhookVerificationError = class extends BirdError {
 	constructor(message) {
@@ -1050,6 +1061,7 @@ var BirdHTTPClient = class {
 	*          `AbortError` if the caller's signal aborts.
 	*/
 	async request(call, options) {
+		if (this.defaults.missingAuth) throw new BirdMissingApiKeyError(this.defaults.missingAuth);
 		const maxRetries = options.maxRetries ?? this.defaults.maxRetries;
 		const timeout = options.timeout ?? this.defaults.timeout;
 		const idempotencyKey = options.idempotencyKey ?? (isMutation(options.method) ? crypto.randomUUID() : void 0);
@@ -3999,6 +4011,188 @@ const listMailboxLabels = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* List webhook endpoints
+*
+* Returns the workspace's webhook endpoints as a cursor-paginated list, newest first by default. Endpoint objects never include the signing secret; to inspect a single endpoint, use [Get a webhook endpoint](/docs/api/reference/get-webhook).
+*
+*/
+const listWebhooks = (options) => (options?.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/webhooks",
+	...options
+});
+/**
+* Create a webhook endpoint
+*
+* Registers an `active` webhook endpoint that receives the event types in `events` as signed HTTPS `POST` requests. See the [webhooks guide](/docs/guides/webhooks) for delivery, signing, and retry behavior.
+*
+* The `201` response is the only response that includes the signing secret (`whsec_` prefix). Store it immediately; if it is lost, [rotate the signing secret](/docs/api/reference/rotate-webhook-secret).
+*
+* A non-HTTPS or non-public `url`, an unknown event type, or exceeding the organization's endpoint limit returns `422`.
+*
+*/
+const createWebhook = (options) => (options.client ?? client).post({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/webhooks",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
+* Delete a webhook endpoint
+*
+* Permanently removes the webhook endpoint and stops all deliveries to it, including retries of earlier failed deliveries. This cannot be undone: recreating an endpoint later mints a new `id` and signing secret. To stop deliveries temporarily instead, set `status` to `paused` with [Update a webhook endpoint](/docs/api/reference/update-webhook).
+*
+*/
+const deleteWebhook = (options) => (options.client ?? client).delete({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/webhooks/{webhook_id}",
+	...options
+});
+/**
+* Get a webhook endpoint
+*
+* Returns one webhook endpoint's configuration and current delivery `status`, including its URL and subscribed event types. The signing secret is never included; if you lost it, mint a new one with [Rotate webhook signing secret](/docs/api/reference/rotate-webhook-secret).
+*
+*/
+const getWebhook = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/webhooks/{webhook_id}",
+	...options
+});
+/**
+* Update a webhook endpoint
+*
+* Updates the webhook endpoint. Only the fields you send change: `events` replaces the
+* whole subscription set, and `status` pauses or re-enables delivery.
+*
+* The `200` response is the updated endpoint. Invalid input (a non-HTTPS or non-public
+* `url`, an event type outside the catalog) returns a `422`.
+*
+*/
+const updateWebhook = (options) => (options.client ?? client).patch({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/webhooks/{webhook_id}",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
+* Rotate webhook signing secret
+*
+* Generates a new signing secret for the endpoint and returns it exactly once: store it
+* immediately, it cannot be retrieved after this response. For 24 hours every delivery
+* is signed with both the old and the new secret, so a receiver verifying with either
+* keeps working while you roll the new one out. After the window the old secret stops
+* signing. Verification details are in the [webhooks guide](/docs/guides/webhooks).
+*
+* An endpoint holds at most 5 concurrently valid secrets, so rotating repeatedly within
+* the overlap window fails with `WebhookTooManySecrets` until an older secret expires.
+*
+*/
+const rotateWebhookSecret = (options) => (options.client ?? client).post({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/webhooks/{webhook_id}/rotate-secret",
+	...options
+});
+/**
+* Test a webhook with a sample event
+*
+* Sends a signed synthetic event and returns whether your endpoint accepted it, its HTTP status, and the round-trip latency. An unreachable endpoint returns `status: failed` in the response body. The endpoint has 10 seconds to respond.
+*
+* The body is a minimal JSON object with the event `type`, signed like a real delivery. It does not mirror that event's payload. Tests work on paused endpoints and do not appear in [List delivery attempts](/docs/api/reference/list-webhook-attempts).
+*
+* The operation returns `412` if the endpoint lacks a valid signing secret or, when `event_type` is omitted, has no subscribed event type to use.
+*
+*/
+const testWebhook = (options) => (options.client ?? client).post({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/webhooks/{webhook_id}/test",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
+* List delivery attempts
+*
+* Returns the endpoint's recent delivery attempts, newest first. Each entry is one HTTP
+* request, so a retried event appears once per try; use it to see what failed and why
+* before requesting redelivery with
+* [Replay missed events](/docs/api/reference/create-webhook-replay).
+*
+* Bound the window with the `before`/`after` timestamps and cap the page with `limit`.
+* To page further back without a cursor, pass the oldest `attempted_at`
+* you received as `before`.
+*
+*/
+const listWebhookAttempts = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/webhooks/{webhook_id}/attempts",
+	...options
+});
+/**
 * List your allocated numbers
 *
 * Returns a paginated list of the phone numbers currently allocated to your workspace, newest first. Each entry is either a dedicated number you bought or a shared number managed for you, as its `kind` field indicates. Pass `number` to look one up, or narrow the list with `country_code`, `number_type`, `prefix`, and `capabilities`. An allocated number is not always enough to send from it: some countries also require an approved registration for the sender.
@@ -6567,10 +6761,155 @@ var VerifyResource = class {
 	}
 };
 //#endregion
+//#region src/resources/webhooks.gen.ts
+var WebhooksResourceBase = class extends Resource {
+	/**
+	* List the workspace's webhook endpoints (URL, subscribed events, status) as a cursor page.
+	*
+	* @example Iterate every webhook endpoint
+	* for await (const endpoint of bird.webhooks.list()) {
+	*   console.log(endpoint.id, endpoint.url, endpoint.status);
+	* }
+	*/
+	list(query, options) {
+		return this.paginated("GET", options, ({ signal, headers }, cursor) => listWebhooks({
+			client: this.client,
+			query: {
+				...query,
+				starting_after: cursor ?? query?.starting_after
+			},
+			headers,
+			signal
+		}));
+	}
+	/**
+	* Read one endpoint's URL, subscribed event types, and current delivery status. The signing secret is never included, and can only be rotated rather than retrieved.
+	*
+	* @example Fetch one endpoint by id
+	* const endpoint = await bird.webhooks.get("whk_01krdgeqcxet5s7t44vh8rt9mg");
+	* console.log(endpoint.url, endpoint.events);
+	*/
+	get(webhookId, options) {
+		return this.call("GET", options, ({ signal, headers }) => getWebhook({
+			client: this.client,
+			path: { webhook_id: webhookId },
+			headers,
+			signal
+		}));
+	}
+	/**
+	* Register an HTTPS endpoint to receive this workspace's events, subscribed to the event types in `events` and active immediately. The response is the only place the signing secret appears, and it can never be read back afterward, only rotated.
+	*
+	* @example Subscribe an endpoint to events
+	* const created = await bird.webhooks.create({
+	*   url: "https://acme.com/hooks/bird",
+	*   events: ["email.delivered", "email.bounced"],
+	*   description: "Delivery pipeline",
+	* });
+	* console.log(created.id, created.secret);
+	*/
+	create(params, options) {
+		return this.call("POST", options, ({ signal, headers }) => createWebhook({
+			client: this.client,
+			body: params,
+			headers,
+			signal
+		}));
+	}
+	/**
+	* Send a signed synthetic event and get the outcome synchronously: whether the endpoint accepted, the HTTP status it returned, and the round-trip latency. An unreachable endpoint comes back as a failed status in the body rather than a request error. The receiver has 10 seconds, the body is a minimal stub carrying only the event type, and a test reaches even a paused endpoint without being recorded in the delivery attempts.
+	*
+	* @example Send a test event to an endpoint
+	* const result = await bird.webhooks.test("whk_01krdgeqcxet5s7t44vh8rt9mg", {
+	*   event_type: "email.delivered",
+	* });
+	* console.log(result.status);
+	*/
+	test(webhookId, params = {}, options) {
+		return this.call("POST", options, ({ signal, headers }) => testWebhook({
+			client: this.client,
+			path: { webhook_id: webhookId },
+			body: params,
+			headers,
+			signal
+		}));
+	}
+	/**
+	* Permanently remove an endpoint and stop every delivery to it, including retries of earlier failures. Recreating it later mints a new ID and signing secret; to stop deliveries temporarily instead, set its status to `paused`.
+	*
+	* @example Stop delivery to an endpoint
+	* await bird.webhooks.delete("whk_01krdgeqcxet5s7t44vh8rt9mg");
+	*/
+	delete(webhookId, options) {
+		return this.call("DELETE", options, ({ signal, headers }) => deleteWebhook({
+			client: this.client,
+			path: { webhook_id: webhookId },
+			headers,
+			signal
+		}));
+	}
+	/**
+	* List an endpoint's recent delivery attempts, newest first. Each entry is one HTTP request, so a retried event appears once per try. Pagination uses the `before`/`after` timestamps; page further back by passing the oldest `attempted_at` you received as `before`.
+	*
+	* @example Inspect recent delivery attempts
+	* const attempts = await bird.webhooks.attempts(
+	*   "whk_01krdgeqcxet5s7t44vh8rt9mg",
+	* );
+	* for (const attempt of attempts.data) {
+	*   console.log(attempt.status, attempt.response_status_code);
+	* }
+	*/
+	attempts(webhookId, query, options) {
+		return this.call("GET", options, ({ signal, headers }) => listWebhookAttempts({
+			client: this.client,
+			path: { webhook_id: webhookId },
+			query,
+			headers,
+			signal
+		}));
+	}
+	/**
+	* Mint a new signing secret and return it exactly once; it cannot be retrieved afterward. Both the old and new secrets sign every delivery for 24 hours, after which the old one stops signing. An endpoint holds at most 5 valid secrets, so rotating repeatedly inside that window fails.
+	*
+	* @example Rotate an endpoint's signing secret
+	* const rotated = await bird.webhooks.rotateSecret(
+	*   "whk_01krdgeqcxet5s7t44vh8rt9mg",
+	* );
+	* console.log(rotated.secret);
+	*/
+	rotateSecret(webhookId, options) {
+		return this.call("POST", options, ({ signal, headers }) => rotateWebhookSecret({
+			client: this.client,
+			path: { webhook_id: webhookId },
+			headers,
+			signal
+		}));
+	}
+	/**
+	* Change an endpoint's URL, description, subscribed event types, or delivery status. Only the fields sent change: `events` replaces the whole subscription set, and `status` pauses or re-enables delivery. Events fired while paused are not delivered.
+	*
+	* @example Change the subscribed event types
+	* const endpoint = await bird.webhooks.update("whk_01krdgeqcxet5s7t44vh8rt9mg", {
+	*   events: ["email.delivered"],
+	* });
+	* console.log(endpoint.events);
+	*/
+	update(webhookId, params = {}, options) {
+		return this.call("PATCH", options, ({ signal, headers }) => updateWebhook({
+			client: this.client,
+			path: { webhook_id: webhookId },
+			body: params,
+			headers,
+			signal
+		}));
+	}
+};
+//#endregion
 //#region src/resources/webhooks.ts
-var WebhooksResource = class {
+var WebhooksResource = class extends WebhooksResourceBase {
 	#secret;
-	constructor(config) {
+	constructor(core, client, config) {
+		super(core, client);
 		this.#secret = config?.secret;
 	}
 	/**
@@ -7329,8 +7668,11 @@ const DEFAULT_TIMEOUT_MS = 6e4;
 const DEFAULT_MAX_RETRIES = 2;
 function resolveBaseUrl(options) {
 	if (options.baseUrl) return options.baseUrl;
-	const region = options.region ?? regionFromApiKey(options.apiKey);
-	if (!region) throw new Error("Unable to determine region: API key is not in the expected bk_{region}_{token} format. Pass an explicit `region` or `baseUrl`.");
+	const region = options.region ?? (options.apiKey ? regionFromApiKey(options.apiKey) : void 0);
+	if (!region) {
+		if (!options.apiKey) return void 0;
+		throw new Error("Unable to determine region: API key is not in the expected bk_{region}_{token} format. Pass an explicit `region` or `baseUrl`.");
+	}
 	return baseUrlForRegion(region);
 }
 function resolveRawRequestUrl(baseUrl, path) {
@@ -7375,6 +7717,7 @@ var BirdClient = class {
 	core;
 	#client;
 	#baseUrl;
+	#missingAuth;
 	#fetch;
 	#headers;
 	/** Email channel: `bird.email.send(...)`, `.get(...)`, `.list(...)`. */
@@ -7415,14 +7758,16 @@ var BirdClient = class {
 	realtime;
 	constructor(options) {
 		const opts = options;
+		if (!opts.apiKey && !opts.webhooks?.secret) throw new BirdError("Configure `apiKey` for API calls, or `webhooks: { secret }` for a receiver-only client.");
+		if (!opts.apiKey) this.#missingAuth = "This client has no API key (webhook verification only); pass `apiKey` to call the API.";
 		this.#baseUrl = resolveBaseUrl(opts);
 		this.#fetch = opts.fetch ?? fetch;
 		this.#headers = {
 			...opts.defaultHeaders,
-			Authorization: `Bearer ${opts.apiKey}`,
-			"User-Agent": `bird-sdk-js/0.42.0`,
+			...opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {},
+			"User-Agent": `bird-sdk-js/0.43.0`,
 			"Bird-Surface": "sdk-js",
-			"Bird-Version": "0.42.0"
+			"Bird-Version": "0.43.0"
 		};
 		const caller = detectCaller();
 		if (caller) this.#headers["Bird-Caller"] = caller;
@@ -7434,6 +7779,7 @@ var BirdClient = class {
 		this.core = new BirdHTTPClient({
 			timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
 			maxRetries: opts.maxRetries ?? DEFAULT_MAX_RETRIES,
+			missingAuth: this.#missingAuth,
 			credentials: {
 				RealtimeKey: {
 					header: "X-Realtime-Key",
@@ -7463,7 +7809,7 @@ var BirdClient = class {
 		this.domains = new DomainsResource(this.core, this.#client);
 		this.lookup = new LookupResource(this.core, this.#client);
 		this.numbers = new NumbersResource(this.core, this.#client);
-		this.webhooks = new WebhooksResource(opts.webhooks);
+		this.webhooks = new WebhooksResource(this.core, this.#client, opts.webhooks);
 		this.realtime = new RealtimeResource(this.core, this.#client, opts.realtime);
 	}
 	/**
@@ -7480,6 +7826,7 @@ var BirdClient = class {
 	* console.log(suppressions.data.length);
 	*/
 	request(req, options) {
+		if (this.#missingAuth || this.#baseUrl === void 0) throw new BirdMissingApiKeyError(this.#missingAuth ?? "This client has no API key (webhook verification only); pass `apiKey` to call the API.");
 		const url = resolveRawRequestUrl(this.#baseUrl, req.path);
 		return apiPromise(this.core.request((ctx) => this.#raw(url, req, ctx, options?.headers), {
 			method: req.method,
@@ -7891,6 +8238,6 @@ const WhatsAppTemplateParameterType = {
 	Video: "video"
 };
 //#endregion
-export { BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, BirdWebhookVerificationError, EmailEventType, EmailLookupFlag, EmailLookupReason, EmailLookupResult, LookupFlag, LookupPropertyStatus, NumberCapability, NumberType, NumbersOrderStatus, PreferenceChannel, PreferenceOrigin, SMSErrorCode, SMSKeywordOperation, SMSSuppressionCoverage, SMSSuppressionEndReason, SMSSuppressionOrigin, SMSSuppressionReason, TemplateLanguageStatus, TemplateStatus, VerificationAttemptFailureReason, VerificationChannel, VerificationTerminalReason, WebhookEventType, WhatsAppErrorCode, WhatsAppEventType, WhatsAppTemplateCategory, WhatsAppTemplateParameterType, baseUrlForRegion, regionFromApiKey };
+export { BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdMissingApiKeyError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, BirdWebhookVerificationError, EmailEventType, EmailLookupFlag, EmailLookupReason, EmailLookupResult, LookupFlag, LookupPropertyStatus, NumberCapability, NumberType, NumbersOrderStatus, PreferenceChannel, PreferenceOrigin, SMSErrorCode, SMSKeywordOperation, SMSSuppressionCoverage, SMSSuppressionEndReason, SMSSuppressionOrigin, SMSSuppressionReason, TemplateLanguageStatus, TemplateStatus, VerificationAttemptFailureReason, VerificationChannel, VerificationTerminalReason, WebhookEventType, WhatsAppErrorCode, WhatsAppEventType, WhatsAppTemplateCategory, WhatsAppTemplateParameterType, baseUrlForRegion, regionFromApiKey };
 
 //# sourceMappingURL=index.mjs.map