@agentpress/sdk 0.5.4 → 0.6.0

package/README.md

@@ -5,7 +5,7 @@ TypeScript SDK for the AgentPress webhook API.
 - **Package:** `@agentpress/sdk` (npm, public)
 - **Output:** Dual ESM (`.mjs`) + CJS (`.cjs`)
 - **Node:** >= 22.0.0
-- **Dependencies:** `jose` for Partner MCP JWT verification; webhook signing uses `node:crypto`
+- **Dependencies:** `jose` for Partner MCP JWT verification; action webhook signing uses `node:crypto`
 
 ## Installation
 
@@ -35,7 +35,7 @@ await client.webhooks.send({
 
 ```typescript
 const client = new AgentPress({
-  webhookSecret: "whsec_...",          // Required for send/verify (must start with "whsec_")
+  webhookSecret: "whsec_...",          // Required for default Svix sends, verify, and action management
   baseUrl: "https://api.agent.press",  // Default
   timeout: 30_000,                     // Default, in milliseconds
   org: "default-org",                  // Default org slug
@@ -45,7 +45,9 @@ const client = new AgentPress({
 });
 ```
 
-All options are optional. `webhookSecret` is required when calling `send`, `verify`, `verifyOrThrow`, `constructEvent`, or action management methods.
+All options are optional. `webhookSecret` is required when calling `send` with
+the default Svix signing mode, HMAC/shared-token sends without an auth override,
+`verify`, `verifyOrThrow`, `constructEvent`, or action management methods.
 
 **Validation rules:**
 - `webhookSecret` must start with `"whsec_"` or a `ConfigurationError` is thrown
@@ -58,7 +60,10 @@ The client exposes `client.webhooks`, `client.actions`, `client.userApprovals`,
 
 ### client.webhooks.send(params)
 
-Signs and sends an arbitrary webhook payload via HMAC-SHA256.
+Sends an arbitrary action webhook payload. By default the SDK uses Svix-style
+signing with the client's `webhookSecret`, which matches the default
+verification scheme for new AgentPress action webhooks. Pass `auth` to match
+another verification scheme configured for the action webhook.
 
 ```typescript
 const response = await client.webhooks.send({
@@ -73,26 +78,55 @@ const response = await client.webhooks.send({
 
 **Endpoint:** `POST {baseUrl}/webhooks/actions/{org}/{action}`
 
+`action` is the action webhook identifier shown on the AgentPress webhook detail
+page. The older `/webhooks/ingest/{org}/{identifier}` listener endpoint is kept
+only for compatibility APIs; new integrations should use `send()`.
+
 **Params (`WebhookSendParams`):**
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `action` | `string` | Webhook action identifier (used in URL path) |
 | `payload` | `Record<string, unknown>` | Arbitrary JSON payload to sign and send |
+| `auth` | `WebhookSendAuth` | Optional verification override. Defaults to Svix with the client's `webhookSecret`. |
 
 **Returns (`WebhookResponse`):**
 
 ```typescript
 {
   success: boolean;
-  actionId?: string;         // ID of created action
+  actionId?: string;         // ID of created or existing action
   alreadyExists?: boolean;   // Duplicate externalId
-  skipped?: boolean;
+  skipped?: boolean;         // Compatibility field for skipped deliveries
+  buffered?: boolean;        // HTTP 202: accepted but waiting on configuration
+  eventId?: string;          // Buffered/skipped webhook_events row
+  reason?: string;           // Machine-readable buffered/skipped reason
   data?: Record<string, unknown>;
 }
 ```
 
-**Throws:** `ConfigurationError` (missing secret), `HttpError` (non-2xx), `TimeoutError`
+Configuration/resolution gaps such as a missing action rule, disabled rule, or
+unresolved user return HTTP `202` with `buffered: true` instead of throwing.
+The delivery is persisted and appears in the Actions ledger for debugging and
+retry.
+
+**Compatibility notes:**
+- Existing `client.webhooks.send()` callers continue to work for action
+  webhooks using the default Svix verification scheme. No SDK method was
+  removed.
+- If the webhook is configured for `hmac_sha256`, `shared_token`, or `none`,
+  pass the matching `auth` option. Manual sender scripts must send the matching
+  headers.
+- Existing listener aliases and `/webhooks/ingest/{org}/{identifier}` remain
+  compatibility paths, but new integrations should use `send()` and
+  `/webhooks/actions/{org}/{action}`.
+- `202` with `buffered: true` is accepted delivery without a created action yet;
+  check `response.buffered` before using `response.actionId`.
+- For `verificationScheme: "none"`, the URL is the credential and can rotate
+  when the webhook is created, switched to `none`, or rotated. Copy the latest
+  URL after those operations.
+
+**Throws:** `ConfigurationError` (missing required secret/token), `HttpError` (non-2xx), `TimeoutError`
 
 **Signing details:** Each request gets three headers automatically:
 - `svix-id` -- unique message ID (`msg_<uuid>`)
@@ -101,6 +135,34 @@ const response = await client.webhooks.send({
 
 The signature input is `${msgId}.${timestamp}.${body}`.
 
+```typescript
+await client.webhooks.send({
+  action: "billing_events",
+  auth: {
+    scheme: "hmac_sha256",
+    secret: process.env.AGENTPRESS_WEBHOOK_SECRET!,
+  },
+  payload: {
+    eventType: "invoice.created",
+    data: { invoiceId: "inv_123" },
+  },
+});
+```
+
+**Auth schemes:**
+
+| Scheme | Params | Notes |
+|--------|--------|-------|
+| `svix` | `{ secret?, msgId?, timestamp? }` | Adds `svix-id`, `svix-timestamp`, and `svix-signature`. Uses `webhookSecret` when `secret` is omitted. |
+| `hmac_sha256` | `{ secret?, timestamp? }` | Adds `x-webhook-timestamp` and `x-webhook-signature` using `signHmacWebhookRequest`. Uses `webhookSecret` when `secret` is omitted. |
+| `shared_token` | `{ token? }` | Adds `x-webhook-token`. Uses `webhookSecret` when `token` is omitted. |
+| `none` | none | Sends no verification headers. Only use for capability-URL action webhooks intentionally configured with no header verification. |
+
+For `verificationScheme: "none"`, the action webhook URL itself is the
+credential. Creating, switching, or rotating such a webhook may mint a new
+unguessable `webhookIdentifier`; copy the latest URL from AgentPress before
+updating manual sender scripts.
+
 ---
 
 ### client.webhooks.verify(params)

package/dist/index.cjs

@@ -607,7 +607,57 @@ function validatePayload(raw) {
 	return event;
 }
 //#endregion
+//#region src/webhooks/actionWebhookSigning.ts
+/**
+* Sign an outbound request for an AgentPress action webhook that uses the
+* `hmac_sha256` verification scheme
+* (`POST /webhooks/actions/:org/:identifier`).
+*
+* Produces the two headers AgentPress verifies:
+*
+* - `x-webhook-timestamp` — unix seconds; AgentPress rejects timestamps more
+*   than 5 minutes from its own clock.
+* - `x-webhook-signature` — `v1=<hex HMAC-SHA256 of "${timestamp}.${rawBody}">`.
+*
+* Send the exact `rawBody` string you signed — any re-serialization after
+* signing (re-ordered keys, whitespace changes) invalidates the signature.
+*
+* @example
+* ```ts
+* const rawBody = JSON.stringify({ eventType: "review.created", data: {...} });
+* const { headers } = signHmacWebhookRequest({ secret, rawBody });
+* await fetch(actionWebhookUrl, {
+*   method: "POST",
+*   body: rawBody,
+*   headers: { "content-type": "application/json", ...headers },
+* });
+* ```
+*/
+function signHmacWebhookRequest(params) {
+	const timestamp = Math.floor(params.timestamp ?? Date.now() / 1e3).toString();
+	return { headers: {
+		"x-webhook-timestamp": timestamp,
+		"x-webhook-signature": `v1=${(0, node_crypto.createHmac)("sha256", params.secret).update(`${timestamp}.${params.rawBody}`).digest("hex")}`
+	} };
+}
+/**
+* Build the auth header for an AgentPress action webhook that uses the
+* `shared_token` verification scheme. AgentPress also accepts
+* `Authorization: Bearer <token>`; this helper uses the dedicated
+* `x-webhook-token` header so it never collides with other auth middleware.
+*/
+function sharedTokenHeaders(token) {
+	return { "x-webhook-token": token };
+}
+//#endregion
 //#region src/webhooks/client.ts
+function pathSegment(value) {
+	return encodeURIComponent(value);
+}
+function requireSecret(scheme, secret) {
+	if (!secret) throw new ConfigurationError(`webhookSecret or auth.${scheme === "shared_token" ? "token" : "secret"} is required for ${scheme} action webhook sends`);
+	return secret;
+}
 var WebhooksClient = class {
 	options;
 	http;
@@ -617,7 +667,8 @@ var WebhooksClient = class {
 	}
 	/**
 	* Send an arbitrary webhook payload to AgentPress.
-	* Signs the payload with HMAC-SHA256 (Svix-compatible).
+	* Signs the payload with the verification scheme configured on the action
+	* webhook. Defaults to Svix-compatible signing.
 	*
 	* On the happy path the response is synchronous: `{ success: true,
 	* actionId, data }`, or `{ success, actionId, alreadyExists: true, data }`
@@ -630,28 +681,81 @@ var WebhooksClient = class {
 	* auto-processes once an operator fixes the configuration, so check
 	* {@link WebhookResponse.buffered} before relying on `actionId`.
 	*
-	* @throws ConfigurationError if webhookSecret is not configured
+	* @throws ConfigurationError if the selected verification scheme needs a
+	* secret/token and none is configured
 	* @throws HttpError on non-2xx response
 	* @throws TimeoutError if request exceeds timeout
 	*/
 	async send(params) {
-		if (!this.options.webhookSecret) throw new ConfigurationError("webhookSecret is required for webhook operations");
-		const path = `/webhooks/actions/${this.options.org}/${params.action}`;
+		const path = `/webhooks/actions/${pathSegment(this.options.org)}/${pathSegment(params.action)}`;
 		const body = JSON.stringify(params.payload);
-		const msgId = randomMessageId();
-		const timestamp = Math.floor(Date.now() / 1e3);
-		const signature = sign(this.options.webhookSecret, msgId, timestamp, body);
+		const auth = params.auth ?? { scheme: "svix" };
+		const headers = {};
+		if (auth.scheme === "svix") {
+			const secret = requireSecret("svix", auth.secret ?? this.options.webhookSecret);
+			const msgId = auth.msgId ?? randomMessageId();
+			const timestamp = Math.floor(auth.timestamp ?? Date.now() / 1e3);
+			Object.assign(headers, {
+				"svix-id": msgId,
+				"svix-timestamp": String(timestamp),
+				"svix-signature": sign(secret, msgId, timestamp, body)
+			});
+		} else if (auth.scheme === "hmac_sha256") {
+			const secret = requireSecret("hmac_sha256", auth.secret ?? this.options.webhookSecret);
+			Object.assign(headers, signHmacWebhookRequest({
+				secret,
+				rawBody: body,
+				timestamp: auth.timestamp
+			}).headers);
+		} else if (auth.scheme === "shared_token") {
+			const token = requireSecret("shared_token", auth.token ?? this.options.webhookSecret);
+			Object.assign(headers, sharedTokenHeaders(token));
+		}
 		return this.http.request(path, {
 			method: "POST",
 			body,
-			headers: {
+			headers
+		});
+	}
+	/**
+	* Send a payload to the legacy Actions listener ingestion endpoint
+	* (`POST /webhooks/ingest/:org/:identifier`).
+	*
+	* New integrations should prefer {@link send}; this method is kept for
+	* existing listener integrations and SDK patch compatibility.
+	*/
+	async sendToActionsListener(params) {
+		const path = `/webhooks/ingest/${pathSegment(this.options.org)}/${pathSegment(params.identifier)}`;
+		const body = JSON.stringify(params.payload);
+		const headers = {};
+		if (params.auth.scheme === "svix") {
+			const msgId = params.auth.msgId ?? randomMessageId();
+			const timestamp = Math.floor(params.auth.timestamp ?? Date.now() / 1e3);
+			Object.assign(headers, {
 				"svix-id": msgId,
 				"svix-timestamp": String(timestamp),
-				"svix-signature": signature
-			}
+				"svix-signature": sign(params.auth.secret, msgId, timestamp, body)
+			});
+		} else if (params.auth.scheme === "hmac_sha256") Object.assign(headers, signHmacWebhookRequest({
+			secret: params.auth.secret,
+			rawBody: body,
+			timestamp: params.auth.timestamp
+		}).headers);
+		else if (params.auth.scheme === "shared_token") Object.assign(headers, sharedTokenHeaders(params.auth.token));
+		return this.http.request(path, {
+			method: "POST",
+			body,
+			headers
 		});
 	}
 	/**
+	* @deprecated Use {@link sendToActionsListener}. Kept as a compatibility
+	* alias for integrations created before the Actions listener naming update.
+	*/
+	async sendToListener(params) {
+		return this.sendToActionsListener(params);
+	}
+	/**
 	* Verify an inbound Svix webhook signature.
 	*
 	* @returns true if valid, false if invalid or expired
@@ -793,49 +897,6 @@ const ACTION_EVENT_TYPES = [
 	"action.expired"
 ];
 //#endregion
-//#region src/webhooks/ingestSigning.ts
-/**
-* Sign an outbound request for an AgentPress inbound webhook listener that
-* uses the `hmac_sha256` verification scheme
-* (`POST /webhooks/ingest/:org/:identifier`).
-*
-* Produces the two headers AgentPress verifies:
-*
-* - `x-webhook-timestamp` — unix seconds; AgentPress rejects timestamps more
-*   than 5 minutes from its own clock.
-* - `x-webhook-signature` — `v1=<hex HMAC-SHA256 of "${timestamp}.${rawBody}">`.
-*
-* Send the exact `rawBody` string you signed — any re-serialization after
-* signing (re-ordered keys, whitespace changes) invalidates the signature.
-*
-* @example
-* ```ts
-* const rawBody = JSON.stringify({ eventType: "review.created", data: {...} });
-* const { headers } = signHmacWebhookRequest({ secret, rawBody });
-* await fetch(ingestUrl, {
-*   method: "POST",
-*   body: rawBody,
-*   headers: { "content-type": "application/json", ...headers },
-* });
-* ```
-*/
-function signHmacWebhookRequest(params) {
-	const timestamp = Math.floor(params.timestamp ?? Date.now() / 1e3).toString();
-	return { headers: {
-		"x-webhook-timestamp": timestamp,
-		"x-webhook-signature": `v1=${(0, node_crypto.createHmac)("sha256", params.secret).update(`${timestamp}.${params.rawBody}`).digest("hex")}`
-	} };
-}
-/**
-* Build the auth header for an AgentPress inbound webhook listener that uses
-* the `shared_token` verification scheme. AgentPress also accepts
-* `Authorization: Bearer <token>`; this helper uses the dedicated
-* `x-webhook-token` header so it never collides with other auth middleware.
-*/
-function sharedTokenHeaders(token) {
-	return { "x-webhook-token": token };
-}
-//#endregion
 exports.ACTION_EVENT_TYPES = ACTION_EVENT_TYPES;
 exports.ActionsClient = ActionsClient;
 exports.AgentPress = AgentPress;