@webhooks-cc/sdk 0.1.1 → 0.3.0

package/README.md

@@ -1,98 +1,186 @@
 # @webhooks-cc/sdk
 
-TypeScript SDK for [webhooks.cc](https://webhooks.cc). Create temporary webhook endpoints, capture requests, and assert on their contents in your test suite.
+TypeScript SDK for [webhooks.cc](https://webhooks.cc). Create webhook endpoints, capture requests, match and replay them, and stream events in real time.
 
 ## Install
 
 ```bash
 npm install @webhooks-cc/sdk
+# or: pnpm add / yarn add / bun add
 ```
 
-## Quick Start
+## Quick start
 
 ```typescript
-import { WebhooksCC } from '@webhooks-cc/sdk';
+import { WebhooksCC, matchAll, matchMethod, matchHeader } from "@webhooks-cc/sdk";
 
-const client = new WebhooksCC({ apiKey: 'whcc_...' });
+const client = new WebhooksCC({ apiKey: "whcc_..." });
 
-// Create a temporary endpoint
-const endpoint = await client.endpoints.create({ name: 'My Test' });
+// Create an endpoint
+const endpoint = await client.endpoints.create({ name: "stripe-test" });
 console.log(endpoint.url); // https://go.webhooks.cc/w/abc123
 
 // Point your service at endpoint.url, then wait for the webhook
 const request = await client.requests.waitFor(endpoint.slug, {
-  timeout: 10000,
-  match: (r) => r.method === 'POST',
+  timeout: "30s",
+  match: matchAll(matchMethod("POST"), matchHeader("stripe-signature")),
 });
 
-console.log(request.body);   // '{"event":"order.created"}'
-console.log(request.headers); // { 'content-type': 'application/json', ... }
+console.log(request.body); // '{"type":"checkout.session.completed",...}'
 
 // Clean up
 await client.endpoints.delete(endpoint.slug);
 ```
 
-## API
+## Client options
 
-### `new WebhooksCC(options)`
+```typescript
+new WebhooksCC(options);
+```
+
+| Option       | Type          | Default                  | Description               |
+| ------------ | ------------- | ------------------------ | ------------------------- |
+| `apiKey`     | `string`      | _required_               | API key (`whcc_...`)      |
+| `baseUrl`    | `string`      | `https://webhooks.cc`    | API base URL              |
+| `webhookUrl` | `string`      | `https://go.webhooks.cc` | Webhook receiver URL      |
+| `timeout`    | `number`      | `30000`                  | HTTP request timeout (ms) |
+| `hooks`      | `ClientHooks` | —                        | Lifecycle callbacks       |
 
-| Option    | Type     | Default                | Description          |
-|-----------|----------|------------------------|----------------------|
-| `apiKey`  | `string` | *required*             | API key (`whcc_...`) |
-| `baseUrl` | `string` | `https://webhooks.cc`  | API base URL         |
-| `timeout` | `number` | `30000`                | Request timeout (ms) |
+### Hooks
+
+```typescript
+const client = new WebhooksCC({
+  apiKey: "whcc_...",
+  hooks: {
+    onRequest: (info) => console.log(info.method, info.url),
+    onResponse: (info) => console.log(info.status),
+    onError: (info) => console.error(info.error),
+  },
+});
+```
 
-### Endpoints
+## Endpoints
 
 ```typescript
 // Create
-const endpoint = await client.endpoints.create({ name: 'optional name' });
+const endpoint = await client.endpoints.create({ name: "my-test" });
 
 // List all
 const endpoints = await client.endpoints.list();
 
 // Get by slug
-const endpoint = await client.endpoints.get('abc123');
+const endpoint = await client.endpoints.get("abc123");
+
+// Update name or mock response
+await client.endpoints.update("abc123", {
+  name: "New Name",
+  mockResponse: { status: 201, body: '{"ok":true}', headers: {} },
+});
+
+// Clear mock response
+await client.endpoints.update("abc123", { mockResponse: null });
+
+// Send a test webhook
+const res = await client.endpoints.send("abc123", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: { event: "test" },
+});
 
 // Delete
-await client.endpoints.delete('abc123');
+await client.endpoints.delete("abc123");
 ```
 
-### Requests
+## Requests
 
 ```typescript
-// List captured requests for an endpoint
-const requests = await client.requests.list('endpoint-slug', {
-  limit: 50,     // default: 50, max: 1000
-  since: Date.now() - 60000, // only after this timestamp (ms)
+// List captured requests
+const requests = await client.requests.list("endpoint-slug", {
+  limit: 50,
+  since: Date.now() - 60000,
 });
 
 // Get a single request by ID
-const request = await client.requests.get('request-id');
+const request = await client.requests.get("request-id");
 
 // Poll until a matching request arrives
-const request = await client.requests.waitFor('endpoint-slug', {
-  timeout: 30000,     // max wait (ms), default: 30000
-  pollInterval: 500,  // poll interval (ms), default: 500
-  match: (r) => r.method === 'POST' && r.body?.includes('order'),
+const request = await client.requests.waitFor("endpoint-slug", {
+  timeout: "30s", // human-readable or milliseconds
+  pollInterval: "500ms",
+  match: matchHeader("stripe-signature"),
 });
+
+// Replay a captured request to a target URL
+const res = await client.requests.replay(request.id, "http://localhost:3000/webhooks");
+
+// Stream requests in real time via SSE
+for await (const req of client.requests.subscribe("endpoint-slug")) {
+  console.log(req.method, req.body);
+}
 ```
 
-### Errors
+## Matchers
+
+Composable functions for `waitFor`'s `match` option:
 
 ```typescript
-import { WebhooksCC, ApiError } from '@webhooks-cc/sdk';
+import { matchMethod, matchHeader, matchBodyPath, matchAll, matchAny } from "@webhooks-cc/sdk";
+
+// Match POST requests with a specific header
+matchAll(matchMethod("POST"), matchHeader("x-event-type", "payment.success"));
+
+// Match header presence (any value)
+matchHeader("stripe-signature");
+
+// Match a nested JSON body field
+matchBodyPath("data.object.id", "sub_123");
+
+// Match any of several conditions
+matchAny(matchHeader("stripe-signature"), matchHeader("x-github-event"));
+```
+
+## Provider helpers
+
+Detect webhook sources by their signature headers:
+
+```typescript
+import { isStripeWebhook, isGitHubWebhook } from "@webhooks-cc/sdk";
+
+if (isStripeWebhook(request)) {
+  // has stripe-signature header
+}
+```
+
+Available: `isStripeWebhook`, `isGitHubWebhook`, `isShopifyWebhook`, `isSlackWebhook`, `isTwilioWebhook`, `isPaddleWebhook`, `isLinearWebhook`.
+
+## Self-description
+
+AI agents can call `client.describe()` to get a structured summary of all SDK operations, parameters, and return types — no API call required.
+
+```typescript
+const desc = client.describe();
+// { version: "0.3.0", endpoints: { create: { ... }, ... }, requests: { ... } }
+```
+
+## Errors
+
+All API errors extend `WebhooksCCError` and include actionable recovery hints:
+
+```typescript
+import { WebhooksCC, WebhooksCCError, NotFoundError } from "@webhooks-cc/sdk";
 
 try {
-  await client.endpoints.get('nonexistent');
+  await client.endpoints.get("nonexistent");
 } catch (error) {
-  if (error instanceof ApiError) {
+  if (error instanceof WebhooksCCError) {
     console.log(error.statusCode); // 404
-    console.log(error.message);    // "API error (404): ..."
+    console.log(error.message); // includes what went wrong and how to fix it
   }
 }
 ```
 
+Error classes: `WebhooksCCError`, `UnauthorizedError`, `NotFoundError`, `TimeoutError`, `RateLimitError`. The legacy `ApiError` alias is still exported for backward compatibility.
+
 ## GitHub Actions
 
 Add your API key as a repository secret named `WHK_API_KEY`:
@@ -106,16 +194,16 @@ Add your API key as a repository secret named `WHK_API_KEY`:
 
 ```typescript
 // webhook.test.ts
-import { describe, it, expect, afterAll } from 'vitest';
-import { WebhooksCC } from '@webhooks-cc/sdk';
+import { describe, it, expect, afterAll } from "vitest";
+import { WebhooksCC, matchHeader } from "@webhooks-cc/sdk";
 
 const client = new WebhooksCC({ apiKey: process.env.WHK_API_KEY! });
 
-describe('webhook integration', () => {
+describe("webhook integration", () => {
   let slug: string;
 
-  it('receives order webhook', async () => {
-    const endpoint = await client.endpoints.create({ name: 'CI Test' });
+  it("receives Stripe webhook", async () => {
+    const endpoint = await client.endpoints.create({ name: "CI Test" });
     slug = endpoint.slug;
 
     // Trigger your service to send a webhook to endpoint.url
@@ -123,12 +211,12 @@ describe('webhook integration', () => {
     await yourService.createOrder();
 
     const req = await client.requests.waitFor(slug, {
-      timeout: 15000,
-      match: (r) => r.body?.includes('order.created'),
+      timeout: "15s",
+      match: matchHeader("stripe-signature"),
     });
 
     const body = JSON.parse(req.body!);
-    expect(body.event).toBe('order.created');
+    expect(body.type).toBe("checkout.session.completed");
   });
 
   afterAll(async () => {
@@ -144,12 +232,17 @@ All types are exported:
 ```typescript
 import type {
   ClientOptions,
+  ClientHooks,
   Endpoint,
   Request,
   CreateEndpointOptions,
+  UpdateEndpointOptions,
+  SendOptions,
   ListRequestsOptions,
   WaitForOptions,
-} from '@webhooks-cc/sdk';
+  SubscribeOptions,
+  SDKDescription,
+} from "@webhooks-cc/sdk";
 ```
 
 ## License

package/dist/index.d.mts

@@ -49,6 +49,30 @@ interface CreateEndpointOptions {
     /** Display name for the endpoint */
     name?: string;
 }
+/**
+ * Options for updating an existing endpoint.
+ */
+interface UpdateEndpointOptions {
+    /** New display name */
+    name?: string;
+    /** Mock response config, or null to clear */
+    mockResponse?: {
+        status: number;
+        body: string;
+        headers: Record<string, string>;
+    } | null;
+}
+/**
+ * Options for sending a test webhook to an endpoint.
+ */
+interface SendOptions {
+    /** HTTP method (default: "POST") */
+    method?: string;
+    /** HTTP headers to include */
+    headers?: Record<string, string>;
+    /** Request body (will be JSON-serialized if not a string) */
+    body?: unknown;
+}
 /**
  * Options for listing captured requests.
  */
@@ -62,13 +86,50 @@ interface ListRequestsOptions {
  * Options for waitFor() polling behavior.
  */
 interface WaitForOptions {
-    /** Maximum time to wait in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Interval between polls in milliseconds (default: 500, min: 10, max: 60000) */
-    pollInterval?: number;
+    /** Maximum time to wait (ms or duration string like "30s", "5m") (default: 30000) */
+    timeout?: number | string;
+    /** Interval between polls (ms or duration string) (default: 500, min: 10, max: 60000) */
+    pollInterval?: number | string;
     /** Filter function to match specific requests */
     match?: (request: Request) => boolean;
 }
+/**
+ * Options for subscribe() SSE streaming.
+ */
+interface SubscribeOptions {
+    /** AbortSignal to cancel the subscription */
+    signal?: AbortSignal;
+    /** Maximum time to stream (ms or duration string like "30m") */
+    timeout?: number | string;
+}
+/** Info passed to the onRequest hook before a request is sent. */
+interface RequestHookInfo {
+    method: string;
+    url: string;
+}
+/** Info passed to the onResponse hook after a successful response. */
+interface ResponseHookInfo {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+}
+/** Info passed to the onError hook when a request fails. */
+interface ErrorHookInfo {
+    method: string;
+    url: string;
+    error: Error;
+    durationMs: number;
+}
+/**
+ * Lifecycle hooks for observability and telemetry integration.
+ * All hooks are optional and are called synchronously (fire-and-forget).
+ */
+interface ClientHooks {
+    onRequest?: (info: RequestHookInfo) => void;
+    onResponse?: (info: ResponseHookInfo) => void;
+    onError?: (info: ErrorHookInfo) => void;
+}
 /**
  * Configuration options for the WebhooksCC client.
  */
@@ -77,8 +138,50 @@ interface ClientOptions {
     apiKey: string;
     /** Base URL for the API (default: https://webhooks.cc) */
     baseUrl?: string;
+    /** Base URL for sending webhooks (default: https://go.webhooks.cc) */
+    webhookUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** Lifecycle hooks for observability */
+    hooks?: ClientHooks;
+}
+/** Description of a single SDK operation. */
+interface OperationDescription {
+    description: string;
+    params: Record<string, string>;
+}
+/** Self-describing schema returned by client.describe(). */
+interface SDKDescription {
+    version: string;
+    endpoints: Record<string, OperationDescription>;
+    requests: Record<string, OperationDescription>;
+}
+
+/**
+ * Base error class for all webhooks.cc SDK errors.
+ * Extends the standard Error with an HTTP status code.
+ */
+declare class WebhooksCCError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+/** Thrown when the API key is invalid or missing (401). */
+declare class UnauthorizedError extends WebhooksCCError {
+    constructor(message?: string);
+}
+/** Thrown when the requested resource does not exist (404). */
+declare class NotFoundError extends WebhooksCCError {
+    constructor(message?: string);
+}
+/** Thrown when the request times out. */
+declare class TimeoutError extends WebhooksCCError {
+    constructor(timeoutMs: number);
+}
+/** Thrown when the API returns 429 Too Many Requests. */
+declare class RateLimitError extends WebhooksCCError {
+    /** Seconds until the rate limit resets, if provided by the server. */
+    readonly retryAfter?: number;
+    constructor(retryAfter?: number);
 }
 
 /**
@@ -86,23 +189,21 @@ interface ClientOptions {
  *
  * @example
  * ```typescript
+ * import { WebhooksCC, matchMethod } from '@webhooks-cc/sdk';
+ *
  * const client = new WebhooksCC({ apiKey: 'whcc_...' });
  * const endpoint = await client.endpoints.create({ name: 'My Webhook' });
  * const request = await client.requests.waitFor(endpoint.slug, {
- *   timeout: 10000,
- *   match: (r) => r.method === 'POST'
+ *   timeout: '30s',
+ *   match: matchMethod('POST'),
  * });
  * ```
  */
 
 /**
- * Error thrown when an API request fails with a specific HTTP status code.
- * Allows callers to distinguish between different error types.
+ * @deprecated Use {@link WebhooksCCError} instead. Kept for backward compatibility.
  */
-declare class ApiError extends Error {
-    readonly statusCode: number;
-    constructor(statusCode: number, message: string);
-}
+declare const ApiError: typeof WebhooksCCError;
 /**
  * Client for the webhooks.cc API.
  *
@@ -113,14 +214,20 @@ declare class ApiError extends Error {
 declare class WebhooksCC {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly webhookUrl;
     private readonly timeout;
+    private readonly hooks;
     constructor(options: ClientOptions);
     private request;
+    /** Returns a static description of all SDK operations (no API call). */
+    describe(): SDKDescription;
     endpoints: {
         create: (options?: CreateEndpointOptions) => Promise<Endpoint>;
         list: () => Promise<Endpoint[]>;
         get: (slug: string) => Promise<Endpoint>;
+        update: (slug: string, options: UpdateEndpointOptions) => Promise<Endpoint>;
         delete: (slug: string) => Promise<void>;
+        send: (slug: string, options?: SendOptions) => Promise<Response>;
     };
     requests: {
         list: (endpointSlug: string, options?: ListRequestsOptions) => Promise<Request[]>;
@@ -138,7 +245,112 @@ declare class WebhooksCC {
          * @throws Error if timeout expires or max iterations (10000) reached
          */
         waitFor: (endpointSlug: string, options?: WaitForOptions) => Promise<Request>;
+        /**
+         * Replay a captured request to a target URL.
+         *
+         * Fetches the original request by ID and re-sends it to the specified URL
+         * with the original method, headers, and body. Hop-by-hop headers are stripped.
+         */
+        replay: (requestId: string, targetUrl: string) => Promise<Response>;
+        /**
+         * Stream incoming requests via SSE as an async iterator.
+         *
+         * Connects to the SSE endpoint and yields Request objects as they arrive.
+         * The connection is closed when the iterator is broken, the signal is aborted,
+         * or the timeout expires.
+         *
+         * No automatic reconnection — if the connection drops, the iterator ends.
+         */
+        subscribe: (slug: string, options?: SubscribeOptions) => AsyncIterable<Request>;
     };
 }
 
-export { ApiError, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ListRequestsOptions, type Request, type WaitForOptions, WebhooksCC };
+/**
+ * Safely parse a JSON request body.
+ * Returns undefined if the body is empty or not valid JSON.
+ */
+declare function parseJsonBody(request: Request): unknown | undefined;
+/**
+ * Check if a request looks like a Stripe webhook.
+ * Matches on the `stripe-signature` header being present.
+ */
+declare function isStripeWebhook(request: Request): boolean;
+/**
+ * Check if a request looks like a GitHub webhook.
+ * Matches on the `x-github-event` header being present.
+ */
+declare function isGitHubWebhook(request: Request): boolean;
+/**
+ * Returns a match function that checks whether a JSON field in the
+ * request body equals the expected value.
+ *
+ * @example
+ * ```ts
+ * const req = await client.requests.waitFor(slug, {
+ *   match: matchJsonField("type", "checkout.session.completed"),
+ * });
+ * ```
+ */
+declare function matchJsonField(field: string, value: unknown): (request: Request) => boolean;
+/** Check if a request looks like a Shopify webhook. */
+declare function isShopifyWebhook(request: Request): boolean;
+/** Check if a request looks like a Slack webhook. */
+declare function isSlackWebhook(request: Request): boolean;
+/** Check if a request looks like a Twilio webhook. */
+declare function isTwilioWebhook(request: Request): boolean;
+/** Check if a request looks like a Paddle webhook. */
+declare function isPaddleWebhook(request: Request): boolean;
+/** Check if a request looks like a Linear webhook. */
+declare function isLinearWebhook(request: Request): boolean;
+
+/** Match requests by HTTP method (case-insensitive). */
+declare function matchMethod(method: string): (request: Request) => boolean;
+/** Match requests that have a specific header, optionally with a specific value. Header names are matched case-insensitively; values are matched with exact (case-sensitive) equality. */
+declare function matchHeader(name: string, value?: string): (request: Request) => boolean;
+/**
+ * Match requests by a dot-notation path into the JSON body.
+ * Supports array indexing with numeric path segments (e.g., `"items.0.id"`).
+ *
+ * @example
+ * ```ts
+ * matchBodyPath("data.object.id", "obj_123")
+ * matchBodyPath("type", "checkout.session.completed")
+ * matchBodyPath("items.0.name", "Widget")
+ * ```
+ */
+declare function matchBodyPath(path: string, value: unknown): (request: Request) => boolean;
+/** Match when ALL matchers return true. Requires at least one matcher. */
+declare function matchAll(first: (request: Request) => boolean, ...rest: Array<(request: Request) => boolean>): (request: Request) => boolean;
+/** Match when ANY matcher returns true. Requires at least one matcher. */
+declare function matchAny(first: (request: Request) => boolean, ...rest: Array<(request: Request) => boolean>): (request: Request) => boolean;
+
+/**
+ * Parse a duration value into milliseconds.
+ *
+ * Accepts:
+ * - Numbers: passed through as-is (treated as milliseconds)
+ * - Numeric strings: `"500"` → 500
+ * - Duration strings: `"30s"` → 30000, `"5m"` → 300000, `"1.5s"` → 1500, `"500ms"` → 500
+ *
+ * @throws {Error} If the input string is not a valid duration format
+ */
+declare function parseDuration(input: number | string): number;
+
+/** A parsed SSE frame with event type and data. */
+interface SSEFrame {
+    event: string;
+    data: string;
+}
+/**
+ * Async generator that parses SSE frames from a ReadableStream.
+ *
+ * Handles:
+ * - Multi-line `data:` fields (joined with newlines)
+ * - `event:` type fields
+ * - Comment lines (`: ...`) — yielded with event "comment"
+ * - Empty data fields
+ * - Frames terminated by blank lines
+ */
+declare function parseSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<SSEFrame, void, undefined>;
+
+export { ApiError, type ClientHooks, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ErrorHookInfo, type ListRequestsOptions, NotFoundError, type OperationDescription, RateLimitError, type Request, type RequestHookInfo, type ResponseHookInfo, type SDKDescription, type SSEFrame, type SendOptions, type SubscribeOptions, TimeoutError, UnauthorizedError, type UpdateEndpointOptions, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isLinearWebhook, isPaddleWebhook, isShopifyWebhook, isSlackWebhook, isStripeWebhook, isTwilioWebhook, matchAll, matchAny, matchBodyPath, matchHeader, matchJsonField, matchMethod, parseDuration, parseJsonBody, parseSSE };