@agentpress/sdk 0.2.70

package/README.md

@@ -0,0 +1,402 @@
+# @agentpress/sdk
+
+Zero-dependency TypeScript SDK for the AgentPress webhook API.
+
+- **Package:** `@agentpress/sdk` (npm, public)
+- **Output:** Dual ESM (`.mjs`) + CJS (`.cjs`)
+- **Node:** >= 22.0.0
+- **Dependencies:** None (uses `node:crypto` for HMAC-SHA256)
+
+## Installation
+
+```bash
+npm install @agentpress/sdk
+# or
+bun add @agentpress/sdk
+```
+
+## Quick Start
+
+```typescript
+import { AgentPress } from "@agentpress/sdk";
+
+const client = new AgentPress({
+  webhookSecret: "whsec_your_secret_here",
+});
+
+// Send a webhook
+await client.webhooks.send({
+  action: "my_action",
+  payload: { eventType: "test", data: { key: "value" } },
+});
+```
+
+## Constructor Options
+
+```typescript
+const client = new AgentPress({
+  webhookSecret: "whsec_...",          // Required for send/verify (must start with "whsec_")
+  baseUrl: "https://api.agent.press",  // Default
+  timeout: 30_000,                     // Default, in milliseconds
+  org: "default-org",                  // Default org slug
+  apiKey: "sk_...",                    // Optional, reserved for future API auth
+  onRequest: (url, init) => {},        // Optional hook, called before every request
+  onResponse: (url, response) => {},   // Optional hook, receives a cloned Response
+});
+```
+
+All options are optional. `webhookSecret` is required only when calling `send`, `verify`, or `verifyOrThrow`.
+
+**Validation rules:**
+- `webhookSecret` must start with `"whsec_"` or a `ConfigurationError` is thrown
+- `timeout` must be a positive finite number
+- Trailing slashes on `baseUrl` are stripped automatically
+
+## API Reference
+
+The client exposes two namespaces: `client.webhooks` and `client.actions`.
+
+### client.webhooks.send(params)
+
+Signs and sends an arbitrary webhook payload via HMAC-SHA256.
+
+```typescript
+const response = await client.webhooks.send({
+  action: "my_webhook_action",
+  payload: {
+    eventType: "order.completed",
+    externalId: "order-456",
+    data: { total: 99.99 },
+  },
+});
+```
+
+**Endpoint:** `POST {baseUrl}/webhooks/actions/{org}/{action}`
+
+**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 |
+
+**Returns (`WebhookResponse`):**
+
+```typescript
+{
+  success: boolean;
+  actionId?: string;         // ID of created action
+  alreadyExists?: boolean;   // Duplicate externalId
+  skipped?: boolean;
+  data?: Record<string, unknown>;
+}
+```
+
+**Throws:** `ConfigurationError` (missing secret), `HttpError` (non-2xx), `TimeoutError`
+
+**Signing details:** Each request gets three headers automatically:
+- `svix-id` -- unique message ID (`msg_<uuid>`)
+- `svix-timestamp` -- Unix seconds
+- `svix-signature` -- `v1,<base64 HMAC-SHA256>`
+
+The signature input is `${msgId}.${timestamp}.${body}`.
+
+---
+
+### client.webhooks.verify(params)
+
+Verifies an inbound Svix webhook signature. Returns `true` if valid, `false` if invalid or expired.
+
+```typescript
+const isValid = client.webhooks.verify({
+  payload: rawRequestBody, // string or Buffer
+  headers: {
+    "svix-id": req.headers["svix-id"],
+    "svix-timestamp": req.headers["svix-timestamp"],
+    "svix-signature": req.headers["svix-signature"],
+  },
+});
+
+if (!isValid) {
+  return new Response("Unauthorized", { status: 401 });
+}
+```
+
+**Params (`WebhookVerifyParams`):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `payload` | `string \| Buffer` | Raw request body |
+| `headers["svix-id"]` | `string` | Message ID header |
+| `headers["svix-timestamp"]` | `string` | Unix timestamp header |
+| `headers["svix-signature"]` | `string` | Signature header (may contain space-separated signatures) |
+
+**Verification rules:**
+- Timestamp must be within 5 minutes of current time (replay protection)
+- Uses timing-safe comparison (`timingSafeEqual`)
+- Supports multiple space-separated signatures in the header (any match = valid)
+
+**Throws:** `ConfigurationError` if `webhookSecret` was not provided
+
+---
+
+### client.webhooks.verifyOrThrow(params)
+
+Same as `verify` but throws `WebhookSignatureError` on invalid signature. Useful in middleware.
+
+```typescript
+try {
+  client.webhooks.verifyOrThrow({
+    payload: rawBody,
+    headers: {
+      "svix-id": headers["svix-id"],
+      "svix-timestamp": headers["svix-timestamp"],
+      "svix-signature": headers["svix-signature"],
+    },
+  });
+  // Signature is valid, proceed
+} catch (error) {
+  if (error instanceof WebhookSignatureError) {
+    return new Response("Invalid signature", { status: 401 });
+  }
+}
+```
+
+### client.webhooks.constructEvent(params)
+
+Verify and parse an inbound webhook from AgentPress in one step. Combines signature verification with JSON parsing and returns a typed `ActionCallbackPayload`. This is the recommended way to handle incoming webhooks.
+
+```typescript
+import { AgentPress, type ActionCallbackPayload } from "@agentpress/sdk";
+
+const client = new AgentPress({ webhookSecret: "whsec_..." });
+
+// Express example
+app.post("/webhooks/agentpress", express.raw({ type: "application/json" }), (req, res) => {
+  const event = client.webhooks.constructEvent({
+    payload: req.body, // raw body string or Buffer
+    headers: {
+      "svix-id": req.headers["svix-id"] as string,
+      "svix-timestamp": req.headers["svix-timestamp"] as string,
+      "svix-signature": req.headers["svix-signature"] as string,
+    },
+  });
+
+  console.log(event.status);        // "completed" | "failed" | ...
+  console.log(event.agentResponse);  // { text: "...", toolCalls: [...] }
+
+  res.status(200).json({ received: true });
+});
+```
+
+**Params:** Same as `verify` / `verifyOrThrow` (`WebhookVerifyParams`).
+
+**Returns (`ActionCallbackPayload`):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `actionId` | `string` | Action identifier |
+| `status` | `ActionStatus` | `"completed"`, `"failed"`, `"rejected"`, etc. |
+| `actionType` | `string` | The action type (e.g., `"order.created"`) |
+| `completedAt` | `string` | ISO 8601 timestamp |
+| `sourceData` | `Record<string, unknown>` | Original data from the inbound webhook |
+| `externalId` | `string \| null` | External system identifier |
+| `userId` | `string \| null` | AgentPress user ID |
+| `threadId` | `string \| null` | Thread ID if a conversation was created |
+| `agentResponse` | `AgentResponse` | Agent's text response and tool call results |
+| `errorMessage` | `string \| null` | Error details if the action failed |
+| `rejectionReason` | `string \| null` | Reason if rejected by a human reviewer |
+
+**Throws:** `WebhookSignatureError` (invalid/expired signature), `ConfigurationError` (missing secret), `AgentPressError` (invalid JSON)
+
+---
+
+### client.actions.approve(actionId, params)
+
+Approve a staged action, optionally modifying the tool call arguments before execution.
+
+```typescript
+// Approve as-is
+await client.actions.approve("act_123", {
+  action: "my_webhook_action",
+});
+
+// Approve with modified arguments
+await client.actions.approve("act_123", {
+  action: "my_webhook_action",
+  editedToolCall: {
+    toolName: "sendEmail",
+    arguments: { subject: "Updated subject" },
+  },
+});
+```
+
+**Endpoint:** `POST {baseUrl}/webhooks/actions/{org}/{action}/manage/{actionId}/approve`
+
+**Params:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `actionId` | `string` | Action ID (first positional argument) |
+| `params.action` | `string` | Webhook action identifier (from callback's `webhookAction` field) |
+| `params.editedToolCall` | `object` (optional) | Modified tool call to use instead of the original |
+
+**Returns (`ActionManageResponse`):**
+
+```typescript
+{
+  success: boolean;
+  actionId: string;
+  status: ActionStatus;
+}
+```
+
+**Throws:** `ConfigurationError` (missing secret), `HttpError` (non-2xx), `TimeoutError`
+
+---
+
+### client.actions.reject(actionId, params)
+
+Reject a staged action with an optional reason.
+
+```typescript
+await client.actions.reject("act_456", {
+  action: "my_webhook_action",
+  reason: "Insufficient context to proceed",
+});
+```
+
+**Endpoint:** `POST {baseUrl}/webhooks/actions/{org}/{action}/manage/{actionId}/reject`
+
+**Params:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `actionId` | `string` | Action ID (first positional argument) |
+| `params.action` | `string` | Webhook action identifier (from callback's `webhookAction` field) |
+| `params.reason` | `string` (optional) | Reason for rejection |
+
+**Returns:** `ActionManageResponse` (same as `approve`)
+
+**Throws:** `ConfigurationError` (missing secret), `HttpError` (non-2xx), `TimeoutError`
+
+---
+
+## Error Handling
+
+All errors extend `AgentPressError`. Import and use `instanceof` for specific handling.
+
+```typescript
+import {
+  AgentPress,
+  AgentPressError,
+  ConfigurationError,
+  HttpError,
+  TimeoutError,
+  WebhookSignatureError,
+} from "@agentpress/sdk";
+
+try {
+  await client.webhooks.send({ action: "test", payload: {} });
+} catch (error) {
+  if (error instanceof HttpError) {
+    // Non-2xx response from the server
+    console.log(error.statusCode);    // e.g. 400, 404, 500
+    console.log(error.responseBody);  // Raw response text
+    console.log(error.url);           // Full request URL
+  } else if (error instanceof TimeoutError) {
+    // Request exceeded the configured timeout
+  } else if (error instanceof ConfigurationError) {
+    // Missing webhookSecret, invalid timeout, etc.
+  } else if (error instanceof WebhookSignatureError) {
+    // Only from verifyOrThrow -- invalid or expired signature
+  } else if (error instanceof AgentPressError) {
+    // Base class: fetch failures, unexpected non-JSON responses
+  }
+}
+```
+
+**Error hierarchy:**
+
+```
+AgentPressError (base)
+  ConfigurationError    -- invalid options or missing webhookSecret
+  HttpError             -- non-2xx response (has statusCode, responseBody, url)
+  TimeoutError          -- request exceeded timeout
+  WebhookSignatureError -- invalid/expired signature (from verifyOrThrow only)
+```
+
+## Exported Types
+
+```typescript
+import type {
+  ActionCallbackPayload,   // Inbound webhook payload from constructEvent()
+  ActionEventType,         // "action.pending_approval" | "action.approved" | ...
+  ActionManageResponse,    // Response from actions.approve() / actions.reject()
+  ActionStatus,            // "pending" | "staged" | "approved" | "rejected" | "completed" | "failed" | "expired"
+  AgentPressOptions,       // Constructor options
+  AgentResponse,           // Agent text response + tool calls
+  ApproveActionParams,     // actions.approve() params
+  RejectActionParams,      // actions.reject() params
+  StagedToolCall,          // Tool call awaiting approval
+  ToolCallResult,          // Individual tool call (name, arguments, result)
+  WebhookResponse,         // Response from send
+  WebhookSendParams,       // send params
+  WebhookVerifyParams,     // verify / verifyOrThrow / constructEvent params
+} from "@agentpress/sdk";
+```
+
+## Full Example: Receiving Action Callbacks
+
+```typescript
+import express from "express";
+import { AgentPress, WebhookSignatureError, type ActionCallbackPayload } from "@agentpress/sdk";
+
+const app = express();
+const client = new AgentPress({ webhookSecret: process.env.WEBHOOK_SECRET });
+
+// Recommended: use constructEvent() for verify + parse in one step
+app.post("/webhooks/agentpress", express.raw({ type: "application/json" }), (req, res) => {
+  let event: ActionCallbackPayload;
+  try {
+    event = client.webhooks.constructEvent({
+      payload: req.body,
+      headers: {
+        "svix-id": req.headers["svix-id"] as string,
+        "svix-timestamp": req.headers["svix-timestamp"] as string,
+        "svix-signature": req.headers["svix-signature"] as string,
+      },
+    });
+  } catch (error) {
+    if (error instanceof WebhookSignatureError) {
+      return res.status(401).json({ error: "Invalid signature" });
+    }
+    throw error;
+  }
+
+  // event is fully typed as ActionCallbackPayload
+  console.log(`Action ${event.actionId} ${event.status}`);
+  if (event.agentResponse.text) {
+    console.log("Agent said:", event.agentResponse.text);
+  }
+
+  res.json({ received: true });
+});
+```
+
+## File Structure
+
+```
+packages/sdk/src/
+  index.ts              -- Public barrel export
+  client.ts             -- AgentPress class, option validation + resolution
+  http.ts               -- HttpClient (fetch wrapper with timeout, hooks, error parsing)
+  errors.ts             -- Error class hierarchy
+  types.ts              -- All exported types and interfaces
+  utils.ts              -- randomMessageId() helper (msg_<uuid>)
+  actions/
+    client.ts           -- ActionsClient (approve, reject)
+  webhooks/
+    client.ts           -- WebhooksClient (send, verify, verifyOrThrow, constructEvent)
+    signing.ts          -- HMAC-SHA256 Svix-compatible sign + verify functions
+```