@webhooks-cc/sdk 0.1.1 → 0.3.0

package/dist/index.mjs

@@ -1,15 +1,194 @@
+// 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/utils.ts
+var DURATION_REGEX = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)$/;
+function parseDuration(input) {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input) || input < 0) {
+      throw new Error(`Invalid duration: must be a finite non-negative number, got ${input}`);
+    }
+    return input;
+  }
+  const trimmed = input.trim();
+  const asNumber = Number(trimmed);
+  if (!isNaN(asNumber) && trimmed.length > 0) {
+    if (!Number.isFinite(asNumber) || asNumber < 0) {
+      throw new Error(`Invalid duration: must be a finite non-negative number, got "${input}"`);
+    }
+    return asNumber;
+  }
+  const match = DURATION_REGEX.exec(trimmed);
+  if (!match) {
+    throw new Error(`Invalid duration: "${input}"`);
+  }
+  const value = parseFloat(match[1]);
+  switch (match[2]) {
+    case "ms":
+      return value;
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 6e4;
+    case "h":
+      return value * 36e5;
+    default:
+      throw new Error(`Invalid duration: "${input}"`);
+  }
+}
+
+// src/sse.ts
+async function* parseSSE(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let currentEvent = "message";
+  let dataLines = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop();
+      for (const line of lines) {
+        if (line === "" || line === "\r") {
+          if (dataLines.length > 0) {
+            yield { event: currentEvent, data: dataLines.join("\n") };
+            dataLines = [];
+            currentEvent = "message";
+          }
+          continue;
+        }
+        const trimmedLine = line.endsWith("\r") ? line.slice(0, -1) : line;
+        if (trimmedLine.startsWith(":")) {
+          const rawComment = trimmedLine.slice(1);
+          yield {
+            event: "comment",
+            data: rawComment.startsWith(" ") ? rawComment.slice(1) : rawComment
+          };
+          continue;
+        }
+        const colonIdx = trimmedLine.indexOf(":");
+        if (colonIdx === -1) continue;
+        const field = trimmedLine.slice(0, colonIdx);
+        const rawVal = trimmedLine.slice(colonIdx + 1);
+        const val = rawVal.startsWith(" ") ? rawVal.slice(1) : rawVal;
+        switch (field) {
+          case "event":
+            currentEvent = val;
+            break;
+          case "data":
+            dataLines.push(val);
+            break;
+        }
+      }
+    }
+    if (buffer.length > 0) {
+      const trimmedLine = buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer;
+      if (trimmedLine.startsWith(":")) {
+        const rawComment = trimmedLine.slice(1);
+        yield {
+          event: "comment",
+          data: rawComment.startsWith(" ") ? rawComment.slice(1) : rawComment
+        };
+      } else {
+        const colonIdx = trimmedLine.indexOf(":");
+        if (colonIdx !== -1) {
+          const field = trimmedLine.slice(0, colonIdx);
+          const rawVal = trimmedLine.slice(colonIdx + 1);
+          const val = rawVal.startsWith(" ") ? rawVal.slice(1) : rawVal;
+          if (field === "event") currentEvent = val;
+          else if (field === "data") dataLines.push(val);
+        }
+      }
+    }
+    if (dataLines.length > 0) {
+      yield { event: currentEvent, data: dataLines.join("\n") };
+    }
+  } finally {
+    await reader.cancel();
+    reader.releaseLock();
+  }
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://webhooks.cc";
+var DEFAULT_WEBHOOK_URL = "https://go.webhooks.cc";
 var DEFAULT_TIMEOUT = 3e4;
+var SDK_VERSION = "0.3.0";
 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 ALLOWED_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]);
+var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
+  "host",
+  "connection",
+  "content-length",
+  "transfer-encoding",
+  "keep-alive",
+  "te",
+  "trailer",
+  "upgrade"
+]);
+var SENSITIVE_HEADERS = /* @__PURE__ */ new Set(["authorization", "cookie", "proxy-authorization", "set-cookie"]);
+var ApiError = WebhooksCCError;
+function mapStatusToError(status, message, response) {
+  const isGeneric = message.length < 30;
+  switch (status) {
+    case 401: {
+      const hint = isGeneric ? `${message} \u2014 Get an API key at https://webhooks.cc/account` : message;
+      return new UnauthorizedError(hint);
+    }
+    case 404: {
+      const hint = isGeneric ? `${message} \u2014 Use client.endpoints.list() to see available endpoints.` : message;
+      return new NotFoundError(hint);
+    }
+    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)) {
@@ -31,9 +210,44 @@ var WebhooksCC = class {
         validatePathSegment(slug, "slug");
         return this.request("GET", `/endpoints/${slug}`);
       },
+      update: async (slug, options) => {
+        validatePathSegment(slug, "slug");
+        if (options.mockResponse && options.mockResponse !== null) {
+          const { status } = options.mockResponse;
+          if (!Number.isInteger(status) || status < 100 || status > 599) {
+            throw new Error(`Invalid mock response status: ${status}. Must be an integer 100-599.`);
+          }
+        }
+        return this.request("PATCH", `/endpoints/${slug}`, options);
+      },
       delete: async (slug) => {
         validatePathSegment(slug, "slug");
         await this.request("DELETE", `/endpoints/${slug}`);
+      },
+      send: async (slug, options = {}) => {
+        validatePathSegment(slug, "slug");
+        const rawMethod = (options.method ?? "POST").toUpperCase();
+        if (!ALLOWED_METHODS.has(rawMethod)) {
+          throw new Error(
+            `Invalid HTTP method: "${options.method}". Must be one of: ${[...ALLOWED_METHODS].join(", ")}`
+          );
+        }
+        const { headers = {}, body } = options;
+        const method = rawMethod;
+        const url = `${this.webhookUrl}/w/${slug}`;
+        const fetchHeaders = { ...headers };
+        const hasContentType = Object.keys(fetchHeaders).some(
+          (k) => k.toLowerCase() === "content-type"
+        );
+        if (body !== void 0 && !hasContentType) {
+          fetchHeaders["Content-Type"] = "application/json";
+        }
+        return fetch(url, {
+          method,
+          headers: fetchHeaders,
+          body: body !== void 0 ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
+          signal: AbortSignal.timeout(this.timeout)
+        });
       }
     };
     this.requests = {
@@ -66,13 +280,15 @@ var WebhooksCC = class {
        */
       waitFor: async (endpointSlug, options = {}) => {
         validatePathSegment(endpointSlug, "endpointSlug");
-        const { timeout = 3e4, pollInterval = 500, match } = options;
+        const timeout = parseDuration(options.timeout ?? 3e4);
+        const rawPollInterval = parseDuration(options.pollInterval ?? 500);
+        const { match } = options;
         const safePollInterval = Math.max(
           MIN_POLL_INTERVAL,
-          Math.min(MAX_POLL_INTERVAL, pollInterval)
+          Math.min(MAX_POLL_INTERVAL, rawPollInterval)
         );
         const start = Date.now();
-        let lastChecked = 0;
+        let lastChecked = start - 5 * 60 * 1e3;
         const MAX_ITERATIONS = 1e4;
         let iterations = 0;
         while (Date.now() - start < timeout && iterations < MAX_ITERATIONS) {
@@ -89,38 +305,215 @@ 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 TimeoutError(timeout);
+      },
+      /**
+       * 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: async (requestId, targetUrl) => {
+        validatePathSegment(requestId, "requestId");
+        let parsed;
+        try {
+          parsed = new URL(targetUrl);
+        } catch {
+          throw new Error(`Invalid targetUrl: "${targetUrl}" is not a valid URL`);
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+          throw new Error(`Invalid targetUrl: only http and https protocols are supported`);
         }
-        throw new Error(`Timeout waiting for request after ${timeout}ms`);
+        const captured = await this.requests.get(requestId);
+        const headers = {};
+        for (const [key, val] of Object.entries(captured.headers)) {
+          const lower = key.toLowerCase();
+          if (!HOP_BY_HOP_HEADERS.has(lower) && !SENSITIVE_HEADERS.has(lower)) {
+            headers[key] = val;
+          }
+        }
+        const upperMethod = captured.method.toUpperCase();
+        const body = upperMethod === "GET" || upperMethod === "HEAD" ? void 0 : captured.body ?? void 0;
+        return fetch(targetUrl, {
+          method: captured.method,
+          headers,
+          body,
+          signal: AbortSignal.timeout(this.timeout)
+        });
+      },
+      /**
+       * 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, options = {}) => {
+        validatePathSegment(slug, "slug");
+        const { signal, timeout } = options;
+        const baseUrl = this.baseUrl;
+        const apiKey = this.apiKey;
+        const timeoutMs = timeout !== void 0 ? parseDuration(timeout) : void 0;
+        return {
+          [Symbol.asyncIterator]() {
+            const controller = new AbortController();
+            let timeoutId;
+            let iterator = null;
+            let started = false;
+            const onAbort = () => controller.abort();
+            if (signal) {
+              if (signal.aborted) {
+                controller.abort();
+              } else {
+                signal.addEventListener("abort", onAbort, { once: true });
+              }
+            }
+            if (timeoutMs !== void 0) {
+              timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            }
+            const cleanup = () => {
+              if (timeoutId !== void 0) clearTimeout(timeoutId);
+              if (signal) signal.removeEventListener("abort", onAbort);
+            };
+            const start = async () => {
+              const url = `${baseUrl}/api/stream/${slug}`;
+              const connectController = new AbortController();
+              const connectTimeout = setTimeout(() => connectController.abort(), 3e4);
+              controller.signal.addEventListener("abort", () => connectController.abort(), {
+                once: true
+              });
+              let response;
+              try {
+                response = await fetch(url, {
+                  headers: { Authorization: `Bearer ${apiKey}` },
+                  signal: connectController.signal
+                });
+              } finally {
+                clearTimeout(connectTimeout);
+              }
+              if (!response.ok) {
+                cleanup();
+                const text = await response.text();
+                throw mapStatusToError(response.status, text, response);
+              }
+              if (!response.body) {
+                cleanup();
+                throw new Error("SSE response has no body");
+              }
+              controller.signal.addEventListener(
+                "abort",
+                () => {
+                  response.body?.cancel();
+                },
+                { once: true }
+              );
+              return parseSSE(response.body);
+            };
+            return {
+              [Symbol.asyncIterator]() {
+                return this;
+              },
+              async next() {
+                try {
+                  if (!started) {
+                    started = true;
+                    iterator = await start();
+                  }
+                  while (iterator) {
+                    const { done, value } = await iterator.next();
+                    if (done) {
+                      cleanup();
+                      return { done: true, value: void 0 };
+                    }
+                    if (value.event === "request") {
+                      try {
+                        const data = JSON.parse(value.data);
+                        if (!data.endpointId || !data.method || !data.headers || !data.receivedAt) {
+                          continue;
+                        }
+                        const req = {
+                          id: data._id ?? data.id,
+                          endpointId: data.endpointId,
+                          method: data.method,
+                          path: data.path ?? "/",
+                          headers: data.headers,
+                          body: data.body ?? void 0,
+                          queryParams: data.queryParams ?? {},
+                          contentType: data.contentType ?? void 0,
+                          ip: data.ip ?? "unknown",
+                          size: data.size ?? 0,
+                          receivedAt: data.receivedAt
+                        };
+                        return { done: false, value: req };
+                      } catch {
+                        continue;
+                      }
+                    }
+                    if (value.event === "timeout" || value.event === "endpoint_deleted") {
+                      cleanup();
+                      return { done: true, value: void 0 };
+                    }
+                  }
+                  cleanup();
+                  return { done: true, value: void 0 };
+                } catch (error) {
+                  cleanup();
+                  controller.abort();
+                  if (error instanceof Error && error.name === "AbortError") {
+                    return { done: true, value: void 0 };
+                  }
+                  throw error;
+                }
+              },
+              async return() {
+                cleanup();
+                controller.abort();
+                if (iterator) {
+                  await iterator.return(void 0);
+                }
+                return { done: true, value: void 0 };
+              }
+            };
+          }
+        };
       }
     };
+    if (!options.apiKey || typeof options.apiKey !== "string") {
+      throw new Error("Missing or invalid apiKey. Get one at https://webhooks.cc/account");
+    }
     this.apiKey = options.apiKey;
-    this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    this.baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL);
+    this.webhookUrl = stripTrailingSlashes(options.webhookUrl ?? DEFAULT_WEBHOOK_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 {
-      const response = await fetch(`${this.baseUrl}/api${path}`, {
+      this.hooks.onRequest?.({ method, url });
+    } catch {
+    }
+    try {
+      const response = await fetch(url, {
         method,
         headers: {
           Authorization: `Bearer ${this.apiKey}`,
@@ -129,10 +522,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,18 +547,196 @@ 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 {
       clearTimeout(timeoutId);
     }
   }
+  /** Returns a static description of all SDK operations (no API call). */
+  describe() {
+    return {
+      version: SDK_VERSION,
+      endpoints: {
+        create: {
+          description: "Create a webhook endpoint",
+          params: { name: "string?" }
+        },
+        list: {
+          description: "List all endpoints",
+          params: {}
+        },
+        get: {
+          description: "Get endpoint by slug",
+          params: { slug: "string" }
+        },
+        update: {
+          description: "Update endpoint settings",
+          params: { slug: "string", name: "string?", mockResponse: "object?" }
+        },
+        delete: {
+          description: "Delete endpoint and its requests",
+          params: { slug: "string" }
+        },
+        send: {
+          description: "Send a test webhook to endpoint",
+          params: { slug: "string", method: "string?", headers: "object?", body: "unknown?" }
+        }
+      },
+      requests: {
+        list: {
+          description: "List captured requests",
+          params: { endpointSlug: "string", limit: "number?", since: "number?" }
+        },
+        get: {
+          description: "Get request by ID",
+          params: { requestId: "string" }
+        },
+        waitFor: {
+          description: "Poll until a matching request arrives",
+          params: {
+            endpointSlug: "string",
+            timeout: "number|string?",
+            match: "function?"
+          }
+        },
+        subscribe: {
+          description: "Stream requests via SSE",
+          params: { slug: "string", signal: "AbortSignal?", timeout: "number|string?" }
+        },
+        replay: {
+          description: "Replay a captured request to a URL",
+          params: { requestId: "string", targetUrl: "string" }
+        }
+      }
+    };
+  }
 };
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function stripTrailingSlashes(url) {
+  let i = url.length;
+  while (i > 0 && url[i - 1] === "/") i--;
+  return i === url.length ? url : url.slice(0, i);
+}
+
+// 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;
+  };
+}
+function isShopifyWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "x-shopify-hmac-sha256");
+}
+function isSlackWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "x-slack-signature");
+}
+function isTwilioWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "x-twilio-signature");
+}
+function isPaddleWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "paddle-signature");
+}
+function isLinearWebhook(request) {
+  return Object.keys(request.headers).some((k) => k.toLowerCase() === "linear-signature");
+}
+
+// src/matchers.ts
+function matchMethod(method) {
+  const upper = method.toUpperCase();
+  return (request) => request.method.toUpperCase() === upper;
+}
+function matchHeader(name, value) {
+  const lowerName = name.toLowerCase();
+  return (request) => {
+    const entry = Object.entries(request.headers).find(([k]) => k.toLowerCase() === lowerName);
+    if (!entry) return false;
+    if (value === void 0) return true;
+    return entry[1] === value;
+  };
+}
+function matchBodyPath(path, value) {
+  const keys = path.split(".");
+  return (request) => {
+    const body = parseJsonBody(request);
+    if (typeof body !== "object" || body === null) return false;
+    let current = body;
+    for (const key of keys) {
+      if (current === null || current === void 0) return false;
+      if (Array.isArray(current)) {
+        const idx = Number(key);
+        if (!Number.isInteger(idx) || idx < 0 || idx >= current.length) return false;
+        current = current[idx];
+      } else if (typeof current === "object") {
+        if (!Object.prototype.hasOwnProperty.call(current, key)) return false;
+        current = current[key];
+      } else {
+        return false;
+      }
+    }
+    return current === value;
+  };
+}
+function matchAll(first, ...rest) {
+  const matchers = [first, ...rest];
+  return (request) => matchers.every((m) => m(request));
+}
+function matchAny(first, ...rest) {
+  const matchers = [first, ...rest];
+  return (request) => matchers.some((m) => m(request));
+}
 export {
   ApiError,
-  WebhooksCC
+  NotFoundError,
+  RateLimitError,
+  TimeoutError,
+  UnauthorizedError,
+  WebhooksCC,
+  WebhooksCCError,
+  isGitHubWebhook,
+  isLinearWebhook,
+  isPaddleWebhook,
+  isShopifyWebhook,
+  isSlackWebhook,
+  isStripeWebhook,
+  isTwilioWebhook,
+  matchAll,
+  matchAny,
+  matchBodyPath,
+  matchHeader,
+  matchJsonField,
+  matchMethod,
+  parseDuration,
+  parseJsonBody,
+  parseSSE
 };