@webhooks-cc/sdk 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,157 @@
+# @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.
+
+## Install
+
+```bash
+npm install @webhooks-cc/sdk
+```
+
+## Quick Start
+
+```typescript
+import { WebhooksCC } from "@webhooks-cc/sdk";
+
+const client = new WebhooksCC({ apiKey: "whcc_..." });
+
+// Create a temporary endpoint
+const endpoint = await client.endpoints.create({ name: "My 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",
+});
+
+console.log(request.body); // '{"event":"order.created"}'
+console.log(request.headers); // { 'content-type': 'application/json', ... }
+
+// Clean up
+await client.endpoints.delete(endpoint.slug);
+```
+
+## API
+
+### `new WebhooksCC(options)`
+
+| Option    | Type     | Default               | Description          |
+| --------- | -------- | --------------------- | -------------------- |
+| `apiKey`  | `string` | _required_            | API key (`whcc_...`) |
+| `baseUrl` | `string` | `https://webhooks.cc` | API base URL         |
+| `timeout` | `number` | `30000`               | Request timeout (ms) |
+
+### Endpoints
+
+```typescript
+// Create
+const endpoint = await client.endpoints.create({ name: "optional name" });
+
+// List all
+const endpoints = await client.endpoints.list();
+
+// Get by slug
+const endpoint = await client.endpoints.get("abc123");
+
+// Delete
+await client.endpoints.delete("abc123");
+```
+
+### 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)
+});
+
+// Get a single request by 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"),
+});
+```
+
+### Errors
+
+```typescript
+import { WebhooksCC, ApiError } from "@webhooks-cc/sdk";
+
+try {
+  await client.endpoints.get("nonexistent");
+} catch (error) {
+  if (error instanceof ApiError) {
+    console.log(error.statusCode); // 404
+    console.log(error.message); // "API error (404): ..."
+  }
+}
+```
+
+## GitHub Actions
+
+Add your API key as a repository secret named `WHK_API_KEY`:
+
+```yaml
+- name: Run webhook tests
+  env:
+    WHK_API_KEY: ${{ secrets.WHK_API_KEY }}
+  run: npx vitest run
+```
+
+```typescript
+// webhook.test.ts
+import { describe, it, expect, afterAll } from "vitest";
+import { WebhooksCC } from "@webhooks-cc/sdk";
+
+const client = new WebhooksCC({ apiKey: process.env.WHK_API_KEY! });
+
+describe("webhook integration", () => {
+  let slug: string;
+
+  it("receives order webhook", async () => {
+    const endpoint = await client.endpoints.create({ name: "CI Test" });
+    slug = endpoint.slug;
+
+    // Trigger your service to send a webhook to endpoint.url
+    await yourService.registerWebhook(endpoint.url!);
+    await yourService.createOrder();
+
+    const req = await client.requests.waitFor(slug, {
+      timeout: 15000,
+      match: (r) => r.body?.includes("order.created"),
+    });
+
+    const body = JSON.parse(req.body!);
+    expect(body.event).toBe("order.created");
+  });
+
+  afterAll(async () => {
+    if (slug) await client.endpoints.delete(slug);
+  });
+});
+```
+
+## Types
+
+All types are exported:
+
+```typescript
+import type {
+  ClientOptions,
+  Endpoint,
+  Request,
+  CreateEndpointOptions,
+  ListRequestsOptions,
+  WaitForOptions,
+} from "@webhooks-cc/sdk";
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -69,6 +69,34 @@ interface WaitForOptions {
     /** Filter function to match specific requests */
     match?: (request: Request) => boolean;
 }
+/** 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.
  */
@@ -79,6 +107,35 @@ interface ClientOptions {
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** Lifecycle hooks for observability */
+    hooks?: ClientHooks;
+}
+
+/**
+ * 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);
 }
 
 /**
@@ -96,13 +153,9 @@ interface ClientOptions {
  */
 
 /**
- * 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.
  *
@@ -114,6 +167,7 @@ declare class WebhooksCC {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly hooks;
     constructor(options: ClientOptions);
     private request;
     endpoints: {
@@ -141,4 +195,32 @@ declare class WebhooksCC {
     };
 }
 
-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;
+
+export { ApiError, type ClientHooks, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ErrorHookInfo, type ListRequestsOptions, NotFoundError, RateLimitError, type Request, type RequestHookInfo, type ResponseHookInfo, TimeoutError, UnauthorizedError, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isStripeWebhook, matchJsonField, parseJsonBody };

package/dist/index.d.ts

@@ -69,6 +69,34 @@ interface WaitForOptions {
     /** Filter function to match specific requests */
     match?: (request: Request) => boolean;
 }
+/** 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.
  */
@@ -79,6 +107,35 @@ interface ClientOptions {
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** Lifecycle hooks for observability */
+    hooks?: ClientHooks;
+}
+
+/**
+ * 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);
 }
 
 /**
@@ -96,13 +153,9 @@ interface ClientOptions {
  */
 
 /**
- * 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.
  *
@@ -114,6 +167,7 @@ declare class WebhooksCC {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly hooks;
     constructor(options: ClientOptions);
     private request;
     endpoints: {
@@ -141,4 +195,32 @@ declare class WebhooksCC {
     };
 }
 
-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;
+
+export { ApiError, type ClientHooks, type ClientOptions, type CreateEndpointOptions, type Endpoint, type ErrorHookInfo, type ListRequestsOptions, NotFoundError, RateLimitError, type Request, type RequestHookInfo, type ResponseHookInfo, TimeoutError, UnauthorizedError, type WaitForOptions, WebhooksCC, WebhooksCCError, isGitHubWebhook, isStripeWebhook, matchJsonField, parseJsonBody };

package/dist/index.js

@@ -21,22 +21,80 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ApiError: () => ApiError,
-  WebhooksCC: () => WebhooksCC
+  NotFoundError: () => NotFoundError,
+  RateLimitError: () => RateLimitError,
+  TimeoutError: () => TimeoutError,
+  UnauthorizedError: () => UnauthorizedError,
+  WebhooksCC: () => WebhooksCC,
+  WebhooksCCError: () => WebhooksCCError,
+  isGitHubWebhook: () => isGitHubWebhook,
+  isStripeWebhook: () => isStripeWebhook,
+  matchJsonField: () => matchJsonField,
+  parseJsonBody: () => parseJsonBody
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/errors.ts
+var WebhooksCCError = class extends Error {
+  constructor(statusCode, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "WebhooksCCError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var UnauthorizedError = class extends WebhooksCCError {
+  constructor(message = "Invalid or missing API key") {
+    super(401, message);
+    this.name = "UnauthorizedError";
+  }
+};
+var NotFoundError = class extends WebhooksCCError {
+  constructor(message = "Resource not found") {
+    super(404, message);
+    this.name = "NotFoundError";
+  }
+};
+var TimeoutError = class extends WebhooksCCError {
+  constructor(timeoutMs) {
+    super(0, `Request timed out after ${timeoutMs}ms`);
+    this.name = "TimeoutError";
+  }
+};
+var RateLimitError = class extends WebhooksCCError {
+  constructor(retryAfter) {
+    const message = retryAfter ? `Rate limited, retry after ${retryAfter}s` : "Rate limited";
+    super(429, message);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://webhooks.cc";
 var DEFAULT_TIMEOUT = 3e4;
 var MIN_POLL_INTERVAL = 10;
 var MAX_POLL_INTERVAL = 6e4;
-var ApiError = class extends Error {
-  constructor(statusCode, message) {
-    super(`API error (${statusCode}): ${message}`);
-    this.statusCode = statusCode;
-    this.name = "ApiError";
+var ApiError = WebhooksCCError;
+function mapStatusToError(status, message, response) {
+  switch (status) {
+    case 401:
+      return new UnauthorizedError(message);
+    case 404:
+      return new NotFoundError(message);
+    case 429: {
+      const retryAfterHeader = response.headers.get("retry-after");
+      let retryAfter;
+      if (retryAfterHeader) {
+        const parsed = parseInt(retryAfterHeader, 10);
+        retryAfter = Number.isNaN(parsed) ? void 0 : parsed;
+      }
+      return new RateLimitError(retryAfter);
+    }
+    default:
+      return new WebhooksCCError(status, message);
   }
-};
+}
 var SAFE_PATH_SEGMENT_REGEX = /^[a-zA-Z0-9_-]+$/;
 function validatePathSegment(segment, name) {
   if (!SAFE_PATH_SEGMENT_REGEX.test(segment)) {
@@ -116,38 +174,39 @@ var WebhooksCC = class {
               return matched;
             }
           } catch (error) {
-            if (error instanceof ApiError) {
-              if (error.statusCode === 401) {
-                throw new Error("Authentication failed: invalid or expired API key");
-              }
-              if (error.statusCode === 403) {
-                throw new Error("Access denied: insufficient permissions for this endpoint");
+            if (error instanceof WebhooksCCError) {
+              if (error instanceof UnauthorizedError) {
+                throw error;
               }
-              if (error.statusCode === 404) {
-                throw new Error(`Endpoint "${endpointSlug}" not found`);
+              if (error instanceof NotFoundError) {
+                throw error;
               }
-              if (error.statusCode < 500) {
+              if (error.statusCode < 500 && !(error instanceof RateLimitError)) {
                 throw error;
               }
             }
           }
           await sleep(safePollInterval);
         }
-        if (iterations >= MAX_ITERATIONS) {
-          throw new Error(`Max iterations (${MAX_ITERATIONS}) reached while waiting for request`);
-        }
-        throw new Error(`Timeout waiting for request after ${timeout}ms`);
+        throw new TimeoutError(timeout);
       }
     };
     this.apiKey = options.apiKey;
     this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.hooks = options.hooks ?? {};
   }
   async request(method, path, body) {
+    const url = `${this.baseUrl}/api${path}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    const start = Date.now();
+    try {
+      this.hooks.onRequest?.({ method, url });
+    } catch {
+    }
     try {
-      const response = await fetch(`${this.baseUrl}/api${path}`, {
+      const response = await fetch(url, {
         method,
         headers: {
           Authorization: `Bearer ${this.apiKey}`,
@@ -156,10 +215,20 @@ var WebhooksCC = class {
         body: body ? JSON.stringify(body) : void 0,
         signal: controller.signal
       });
+      const durationMs = Date.now() - start;
       if (!response.ok) {
-        const error = await response.text();
-        const sanitizedError = error.length > 200 ? error.slice(0, 200) + "..." : error;
-        throw new ApiError(response.status, sanitizedError);
+        const errorText = await response.text();
+        const sanitizedError = errorText.length > 200 ? errorText.slice(0, 200) + "..." : errorText;
+        const error = mapStatusToError(response.status, sanitizedError, response);
+        try {
+          this.hooks.onError?.({ method, url, error, durationMs });
+        } catch {
+        }
+        throw error;
+      }
+      try {
+        this.hooks.onResponse?.({ method, url, status: response.status, durationMs });
+      } catch {
       }
       if (response.status === 204 || response.headers.get("content-length") === "0") {
         return void 0;
@@ -171,7 +240,17 @@ var WebhooksCC = class {
       return response.json();
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Request timed out after ${this.timeout}ms`);
+        const timeoutError = new TimeoutError(this.timeout);
+        try {
+          this.hooks.onError?.({
+            method,
+            url,
+            error: timeoutError,
+            durationMs: Date.now() - start
+          });
+        } catch {
+        }
+        throw timeoutError;
       }
       throw error;
     } finally {
@@ -182,8 +261,41 @@ var WebhooksCC = class {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+// src/helpers.ts
+function parseJsonBody(request) {
+  if (!request.body) return void 0;
+  try {
+    return JSON.parse(request.body);
+  } catch {
+    return void 0;
+  }
+}
+function isStripeWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "stripe-signature");
+}
+function isGitHubWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "x-github-event");
+}
+function matchJsonField(field, value) {
+  return (request) => {
+    const body = parseJsonBody(request);
+    if (typeof body !== "object" || body === null) return false;
+    if (!Object.prototype.hasOwnProperty.call(body, field)) return false;
+    return body[field] === value;
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiError,
-  WebhooksCC
+  NotFoundError,
+  RateLimitError,
+  TimeoutError,
+  UnauthorizedError,
+  WebhooksCC,
+  WebhooksCCError,
+  isGitHubWebhook,
+  isStripeWebhook,
+  matchJsonField,
+  parseJsonBody
 });

package/dist/index.mjs

@@ -1,15 +1,64 @@
+// src/errors.ts
+var WebhooksCCError = class extends Error {
+  constructor(statusCode, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "WebhooksCCError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var UnauthorizedError = class extends WebhooksCCError {
+  constructor(message = "Invalid or missing API key") {
+    super(401, message);
+    this.name = "UnauthorizedError";
+  }
+};
+var NotFoundError = class extends WebhooksCCError {
+  constructor(message = "Resource not found") {
+    super(404, message);
+    this.name = "NotFoundError";
+  }
+};
+var TimeoutError = class extends WebhooksCCError {
+  constructor(timeoutMs) {
+    super(0, `Request timed out after ${timeoutMs}ms`);
+    this.name = "TimeoutError";
+  }
+};
+var RateLimitError = class extends WebhooksCCError {
+  constructor(retryAfter) {
+    const message = retryAfter ? `Rate limited, retry after ${retryAfter}s` : "Rate limited";
+    super(429, message);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://webhooks.cc";
 var DEFAULT_TIMEOUT = 3e4;
 var MIN_POLL_INTERVAL = 10;
 var MAX_POLL_INTERVAL = 6e4;
-var ApiError = class extends Error {
-  constructor(statusCode, message) {
-    super(`API error (${statusCode}): ${message}`);
-    this.statusCode = statusCode;
-    this.name = "ApiError";
+var ApiError = WebhooksCCError;
+function mapStatusToError(status, message, response) {
+  switch (status) {
+    case 401:
+      return new UnauthorizedError(message);
+    case 404:
+      return new NotFoundError(message);
+    case 429: {
+      const retryAfterHeader = response.headers.get("retry-after");
+      let retryAfter;
+      if (retryAfterHeader) {
+        const parsed = parseInt(retryAfterHeader, 10);
+        retryAfter = Number.isNaN(parsed) ? void 0 : parsed;
+      }
+      return new RateLimitError(retryAfter);
+    }
+    default:
+      return new WebhooksCCError(status, message);
   }
-};
+}
 var SAFE_PATH_SEGMENT_REGEX = /^[a-zA-Z0-9_-]+$/;
 function validatePathSegment(segment, name) {
   if (!SAFE_PATH_SEGMENT_REGEX.test(segment)) {
@@ -89,38 +138,39 @@ var WebhooksCC = class {
               return matched;
             }
           } catch (error) {
-            if (error instanceof ApiError) {
-              if (error.statusCode === 401) {
-                throw new Error("Authentication failed: invalid or expired API key");
-              }
-              if (error.statusCode === 403) {
-                throw new Error("Access denied: insufficient permissions for this endpoint");
+            if (error instanceof WebhooksCCError) {
+              if (error instanceof UnauthorizedError) {
+                throw error;
               }
-              if (error.statusCode === 404) {
-                throw new Error(`Endpoint "${endpointSlug}" not found`);
+              if (error instanceof NotFoundError) {
+                throw error;
               }
-              if (error.statusCode < 500) {
+              if (error.statusCode < 500 && !(error instanceof RateLimitError)) {
                 throw error;
               }
             }
           }
           await sleep(safePollInterval);
         }
-        if (iterations >= MAX_ITERATIONS) {
-          throw new Error(`Max iterations (${MAX_ITERATIONS}) reached while waiting for request`);
-        }
-        throw new Error(`Timeout waiting for request after ${timeout}ms`);
+        throw new TimeoutError(timeout);
       }
     };
     this.apiKey = options.apiKey;
     this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.hooks = options.hooks ?? {};
   }
   async request(method, path, body) {
+    const url = `${this.baseUrl}/api${path}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    const start = Date.now();
+    try {
+      this.hooks.onRequest?.({ method, url });
+    } catch {
+    }
     try {
-      const response = await fetch(`${this.baseUrl}/api${path}`, {
+      const response = await fetch(url, {
         method,
         headers: {
           Authorization: `Bearer ${this.apiKey}`,
@@ -129,10 +179,20 @@ var WebhooksCC = class {
         body: body ? JSON.stringify(body) : void 0,
         signal: controller.signal
       });
+      const durationMs = Date.now() - start;
       if (!response.ok) {
-        const error = await response.text();
-        const sanitizedError = error.length > 200 ? error.slice(0, 200) + "..." : error;
-        throw new ApiError(response.status, sanitizedError);
+        const errorText = await response.text();
+        const sanitizedError = errorText.length > 200 ? errorText.slice(0, 200) + "..." : errorText;
+        const error = mapStatusToError(response.status, sanitizedError, response);
+        try {
+          this.hooks.onError?.({ method, url, error, durationMs });
+        } catch {
+        }
+        throw error;
+      }
+      try {
+        this.hooks.onResponse?.({ method, url, status: response.status, durationMs });
+      } catch {
       }
       if (response.status === 204 || response.headers.get("content-length") === "0") {
         return void 0;
@@ -144,7 +204,17 @@ var WebhooksCC = class {
       return response.json();
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Request timed out after ${this.timeout}ms`);
+        const timeoutError = new TimeoutError(this.timeout);
+        try {
+          this.hooks.onError?.({
+            method,
+            url,
+            error: timeoutError,
+            durationMs: Date.now() - start
+          });
+        } catch {
+        }
+        throw timeoutError;
       }
       throw error;
     } finally {
@@ -155,7 +225,40 @@ var WebhooksCC = class {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+// src/helpers.ts
+function parseJsonBody(request) {
+  if (!request.body) return void 0;
+  try {
+    return JSON.parse(request.body);
+  } catch {
+    return void 0;
+  }
+}
+function isStripeWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "stripe-signature");
+}
+function isGitHubWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "x-github-event");
+}
+function matchJsonField(field, value) {
+  return (request) => {
+    const body = parseJsonBody(request);
+    if (typeof body !== "object" || body === null) return false;
+    if (!Object.prototype.hasOwnProperty.call(body, field)) return false;
+    return body[field] === value;
+  };
+}
 export {
   ApiError,
-  WebhooksCC
+  NotFoundError,
+  RateLimitError,
+  TimeoutError,
+  UnauthorizedError,
+  WebhooksCC,
+  WebhooksCCError,
+  isGitHubWebhook,
+  isStripeWebhook,
+  matchJsonField,
+  parseJsonBody
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@webhooks-cc/sdk",
-  "version": "0.1.0",
-  "description": "Official SDK for webhooks.cc — programmatic webhook testing",
+  "version": "0.2.0",
+  "description": "TypeScript SDK for webhooks.cc — create endpoints, capture requests, assert in tests",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -13,7 +13,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "webhook",