webhookadmin 0.1.0

package/dist/index.cjs

@@ -0,0 +1,586 @@
+'use strict';
+
+// src/errors.ts
+var WebhookAdminError = class extends Error {
+  name = "WebhookAdminError";
+  /** HTTP status. Undefined when no response was received. */
+  status;
+  /** API error code, such as `invalid` or `not_found`. */
+  code;
+  /** Per-field messages for validation errors. */
+  fields;
+  /** Request ID (`x-request-id`, or Cloudflare's `cf-ray`) to quote when contacting support. */
+  requestId;
+  constructor(message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.status = options.status;
+    this.code = options.code;
+    this.fields = options.fields;
+    this.requestId = options.requestId;
+  }
+};
+var AuthenticationError = class extends WebhookAdminError {
+  name = "AuthenticationError";
+};
+var PermissionError = class extends WebhookAdminError {
+  name = "PermissionError";
+};
+var NotFoundError = class extends WebhookAdminError {
+  name = "NotFoundError";
+};
+var ValidationError = class extends WebhookAdminError {
+  name = "ValidationError";
+};
+var PlanLimitError = class extends WebhookAdminError {
+  name = "PlanLimitError";
+};
+var ConflictError = class extends WebhookAdminError {
+  name = "ConflictError";
+};
+var RateLimitError = class extends WebhookAdminError {
+  name = "RateLimitError";
+  /** Seconds to wait before retrying, from `retry-after`. */
+  retryAfter;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.retryAfter = options.retryAfter;
+  }
+};
+var ApiError = class extends WebhookAdminError {
+  name = "ApiError";
+};
+var ConnectionError = class extends WebhookAdminError {
+  name = "ConnectionError";
+};
+var TimeoutError = class extends ConnectionError {
+  name = "TimeoutError";
+};
+var WebhookVerificationError = class extends WebhookAdminError {
+  name = "WebhookVerificationError";
+};
+function parseRetryAfter(value, now = Date.now()) {
+  if (value === null || value.trim() === "") return void 0;
+  const n = Number(value);
+  if (Number.isFinite(n)) return Math.max(0, n);
+  const at = Date.parse(value);
+  return Number.isNaN(at) ? void 0 : Math.max(0, (at - now) / 1e3);
+}
+function requestIdOf(headers) {
+  return headers.get("x-request-id") ?? headers.get("cf-ray") ?? void 0;
+}
+function errorFromResponse(status, text, headers) {
+  let body = {};
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object") body = parsed;
+  } catch {
+  }
+  const options = {
+    status,
+    code: typeof body.error === "string" ? body.error : void 0,
+    fields: body.fields && typeof body.fields === "object" ? body.fields : void 0,
+    requestId: requestIdOf(headers)
+  };
+  const message = typeof body.message === "string" ? body.message : `HTTP ${status}`;
+  switch (status) {
+    case 401:
+      return new AuthenticationError(message, options);
+    case 403:
+      return new PermissionError(message, options);
+    case 404:
+      return new NotFoundError(message, options);
+    case 400:
+    case 413:
+    case 422:
+      return new ValidationError(message, options);
+    case 402:
+      return new PlanLimitError(message, options);
+    case 409:
+      return new ConflictError(message, options);
+    case 429:
+      return new RateLimitError(message, { ...options, retryAfter: parseRetryAfter(headers.get("retry-after")) });
+    default:
+      return new ApiError(message, options);
+  }
+}
+
+// src/version.ts
+var VERSION = "0.1.0";
+var USER_AGENT = `webhookadmin-node/${VERSION}`;
+
+// src/http.ts
+var MAX_RATE_LIMIT_WAIT_MS = 6e4;
+var BACKOFF_BASE_MS = 500;
+var BACKOFF_MAX_MS = 8e3;
+function backoff(attempt, random = Math.random) {
+  const base = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** attempt);
+  return Math.round(base * (0.75 + random() * 0.5));
+}
+function rateLimitWait(headers, now = Date.now()) {
+  const after = parseRetryAfter(headers.get("retry-after"), now);
+  if (after !== void 0) return Math.ceil(after * 1e3);
+  const reset = Number(headers.get("x-ratelimit-reset"));
+  if (headers.get("x-ratelimit-reset") && Number.isFinite(reset)) return Math.max(0, reset * 1e3 - now);
+  return void 0;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new ConnectionError("Request was aborted", { cause: signal?.reason }));
+    };
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var Http = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  url(path2, query = {}) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== "") qs.set(k, String(v));
+    const s = qs.toString();
+    return `${this.config.baseUrl}${path2}${s ? `?${s}` : ""}`;
+  }
+  async request(req, options = {}) {
+    const maxRetries = options.maxRetries ?? this.config.maxRetries;
+    for (let attempt = 0; ; attempt++) {
+      const r = await this.once(req, options);
+      if (r.ok) return r.value;
+      if (!r.retryable || attempt >= maxRetries || options.signal?.aborted) throw r.error;
+      await sleep(r.wait ?? backoff(attempt), options.signal);
+    }
+  }
+  async once(req, options) {
+    const headers = {
+      authorization: `Bearer ${this.config.apiKey}`,
+      accept: "application/json",
+      "user-agent": USER_AGENT,
+      ...req.headers
+    };
+    let body;
+    if (req.body !== void 0) {
+      body = JSON.stringify(req.body);
+      headers["content-type"] = "application/json";
+    }
+    if (options.signal?.aborted) {
+      return { ok: false, error: new ConnectionError("Request was aborted", { cause: options.signal.reason }), retryable: false };
+    }
+    const timeout = options.timeout ?? this.config.timeout;
+    const ctrl = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      ctrl.abort();
+    }, timeout);
+    const onAbort = () => ctrl.abort();
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    let res;
+    let text;
+    try {
+      res = await this.config.fetch(this.url(req.path, req.query), { method: req.method, headers, body, signal: ctrl.signal });
+      text = await res.text();
+    } catch (e) {
+      if (timedOut)
+        return { ok: false, error: new TimeoutError(`Request timed out after ${timeout} ms`, { cause: e }), retryable: req.idempotent };
+      if (options.signal?.aborted) return { ok: false, error: new ConnectionError("Request was aborted", { cause: e }), retryable: false };
+      const msg = e instanceof Error ? e.message : String(e);
+      return { ok: false, error: new ConnectionError(`Connection error: ${msg}`, { cause: e }), retryable: req.idempotent };
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+    }
+    if (res.ok) {
+      if (text === "") return { ok: true, value: void 0 };
+      try {
+        return { ok: true, value: JSON.parse(text) };
+      } catch (e) {
+        const error2 = new ApiError(`Invalid JSON in response (HTTP ${res.status})`, {
+          status: res.status,
+          requestId: requestIdOf(res.headers),
+          cause: e
+        });
+        return { ok: false, error: error2, retryable: false };
+      }
+    }
+    const error = errorFromResponse(res.status, text, res.headers);
+    if (res.status === 429) {
+      const wait = rateLimitWait(res.headers);
+      if (wait !== void 0 && wait > MAX_RATE_LIMIT_WAIT_MS) return { ok: false, error, retryable: false };
+      return { ok: false, error, retryable: true, wait };
+    }
+    return { ok: false, error, retryable: res.status >= 500 && req.idempotent };
+  }
+};
+
+// src/pagination.ts
+var PagePromise = class {
+  /** @internal */
+  constructor(fetchPage, cursor) {
+    this.fetchPage = fetchPage;
+    this.cursor = cursor;
+  }
+  fetchPage;
+  cursor;
+  first;
+  firstPage() {
+    this.first ??= this.fetchPage(this.cursor);
+    return this.first;
+  }
+  // biome-ignore lint/suspicious/noThenProperty: PagePromise is intentionally awaitable
+  then(onfulfilled, onrejected) {
+    return this.firstPage().then(onfulfilled, onrejected);
+  }
+  // biome-ignore lint/suspicious/noExplicitAny: same signature as Promise
+  catch(onrejected) {
+    return this.firstPage().catch(onrejected);
+  }
+  finally(onfinally) {
+    return this.firstPage().finally(onfinally);
+  }
+  async *[Symbol.asyncIterator]() {
+    let page = await this.firstPage();
+    for (; ; ) {
+      yield* page.items;
+      if (!page.next_cursor) return;
+      page = await this.fetchPage(page.next_cursor);
+    }
+  }
+};
+
+// src/resources/consumers.ts
+var Consumers = class {
+  /** @internal */
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Creates a consumer. A duplicate `external_id` throws `ConflictError`. Requires `consumers:write`. */
+  create(params, options) {
+    return this.http.request({ method: "POST", path: "/v1/consumers", body: params, idempotent: false }, options);
+  }
+  /** Lists consumers. Requires `logs:read`. */
+  list(params = {}, options) {
+    const { cursor, ...query } = params;
+    return new PagePromise(
+      (c) => this.http.request(
+        { method: "GET", path: "/v1/consumers", query: { ...query, cursor: c }, idempotent: true },
+        options
+      ),
+      cursor
+    );
+  }
+};
+
+// src/resources/deliveries.ts
+var Deliveries = class {
+  /** @internal */
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Sends a finished delivery again. A delivery still being sent throws `ConflictError`.
+   * Requires `messages:retry`.
+   */
+  async retry(deliveryId, options) {
+    await this.http.request({ method: "POST", path: `/v1/deliveries/${encodeURIComponent(deliveryId)}/retry`, idempotent: false }, options);
+  }
+};
+
+// src/resources/endpoints.ts
+var path = (endpointId, rest = "") => `/v1/endpoints/${encodeURIComponent(endpointId)}${rest}`;
+var Endpoints = class {
+  /** @internal */
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Creates an endpoint. The signing secret is returned only here. Requires `endpoints:write`. */
+  create(params, options) {
+    return this.http.request({ method: "POST", path: "/v1/endpoints", body: params, idempotent: false }, options);
+  }
+  /** Lists endpoints, optionally for one consumer. All endpoints come in one page. Requires `logs:read`. */
+  list(params = {}, options) {
+    return new PagePromise(async (cursor) => {
+      const r = await this.http.request(
+        { method: "GET", path: "/v1/endpoints", query: { ...params, cursor }, idempotent: true },
+        options
+      );
+      return { items: r.items, next_cursor: r.next_cursor ?? null };
+    }, void 0);
+  }
+  /** Gets an endpoint with its latest attempts. Requires `logs:read`. */
+  get(endpointId, options) {
+    return this.http.request({ method: "GET", path: path(endpointId), idempotent: true }, options);
+  }
+  /** Updates an endpoint. Set `status: 'active'` to resume a paused or disabled endpoint. Requires `endpoints:write`. */
+  update(endpointId, params, options) {
+    return this.http.request({ method: "PATCH", path: path(endpointId), body: params, idempotent: true }, options);
+  }
+  /** Deletes an endpoint. Requires `endpoints:write`. */
+  async delete(endpointId, options) {
+    await this.http.request({ method: "DELETE", path: path(endpointId), idempotent: true }, options);
+  }
+  /** Issues a new signing secret. The previous one keeps signing for 24 hours. Requires `endpoints:write`. */
+  rotateSecret(endpointId, options) {
+    return this.http.request({ method: "POST", path: path(endpointId, "/rotate-secret"), idempotent: false }, options);
+  }
+  /** Sends a test message to this endpoint only. Not counted in usage. Requires `messages:send`. */
+  sendTest(endpointId, params = {}, options) {
+    return this.http.request({ method: "POST", path: path(endpointId, "/test"), body: params, idempotent: false }, options);
+  }
+};
+
+// src/runtime.ts
+var NODE_CRYPTO = "node:crypto";
+var nodeCrypto;
+function webCrypto() {
+  const g = globalThis.crypto;
+  if (g?.subtle) return Promise.resolve(g);
+  nodeCrypto ??= import(
+    /* webpackIgnore: true */
+    /* @vite-ignore */
+    NODE_CRYPTO
+  ).then((m) => m.webcrypto);
+  return nodeCrypto;
+}
+function readEnv(name) {
+  const g = globalThis;
+  try {
+    const v = g.process?.env?.[name] ?? g.Deno?.env?.get(name);
+    return v?.trim() || void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function uuid() {
+  const b = (await webCrypto()).getRandomValues(new Uint8Array(16));
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  const h = [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+
+// src/resources/messages.ts
+var id = (v) => encodeURIComponent(v);
+var Messages = class {
+  /** @internal */
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Sends a message to every active endpoint of the consumer that accepts the event type.
+   * Requires the `messages:send` scope.
+   */
+  async send(params, options = {}) {
+    const { idempotencyKey, ...rest } = options;
+    const key = idempotencyKey ?? `webhookadmin-node-${await uuid()}`;
+    return this.http.request(
+      { method: "POST", path: "/v1/messages", body: params, headers: { "idempotency-key": key }, idempotent: true },
+      rest
+    );
+  }
+  /** Lists messages, newest first. Requires `logs:read`. */
+  list(params = {}, options) {
+    const { cursor, ...query } = params;
+    return new PagePromise(
+      (c) => this.http.request(
+        { method: "GET", path: "/v1/messages", query: { ...query, cursor: c }, idempotent: true },
+        options
+      ),
+      cursor
+    );
+  }
+  /** Gets a message with its deliveries and attempts. Requires `logs:read`. */
+  get(messageId, options) {
+    return this.http.request({ method: "GET", path: `/v1/messages/${id(messageId)}`, idempotent: true }, options);
+  }
+};
+
+// src/resources/portal.ts
+var Portal = class {
+  /** @internal */
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Creates a 15-minute link to the consumer portal, where your customer manages their own endpoints.
+   * Starter plan or above. Requires `endpoints:write`.
+   */
+  createLink(consumerId, params = {}, options) {
+    return this.http.request(
+      { method: "POST", path: `/v1/consumers/${encodeURIComponent(consumerId)}/portal`, body: params, idempotent: true },
+      options
+    );
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.webhookadmin.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var API_KEY_ENV = "WEBHOOK_ADMIN_API_KEY";
+var WebhookAdmin = class {
+  messages;
+  consumers;
+  endpoints;
+  deliveries;
+  portal;
+  baseUrl;
+  /**
+   * @param apiKey `sk_live_…` or `sk_test_…`. Defaults to the `WEBHOOK_ADMIN_API_KEY` environment variable.
+   */
+  constructor(apiKey, options = {}) {
+    const key = apiKey ?? readEnv(API_KEY_ENV);
+    if (!key) {
+      throw new WebhookAdminError(`Missing API key. Pass it to new WebhookAdmin('sk_\u2026') or set ${API_KEY_ENV}.`);
+    }
+    const f = options.fetch ?? globalThis.fetch;
+    if (!f) throw new WebhookAdminError("fetch is not available. Use Node.js 18 or later, or pass options.fetch.");
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const http = new Http({
+      apiKey: key,
+      baseUrl: this.baseUrl,
+      timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      // 素の fetch を this なしで呼ぶと Workers などで Illegal invocation になる
+      fetch: options.fetch ?? ((input, init) => f(input, init))
+    });
+    this.messages = new Messages(http);
+    this.consumers = new Consumers(http);
+    this.endpoints = new Endpoints(http);
+    this.deliveries = new Deliveries(http);
+    this.portal = new Portal(http);
+  }
+};
+
+// src/webhook.ts
+var PREFIX = "whsec_";
+var enc = new TextEncoder();
+var dec = new TextDecoder();
+function base64Decode(s) {
+  const bin = atob(s);
+  const out = new Uint8Array(new ArrayBuffer(bin.length));
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function base64Encode(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+function header(headers, name) {
+  if (typeof headers.get === "function") return headers.get(name) ?? void 0;
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === name) return Array.isArray(v) ? v[0] : v;
+  }
+  return void 0;
+}
+function bytesOf(payload) {
+  if (typeof payload === "string") return enc.encode(payload);
+  if (payload instanceof Uint8Array) return payload;
+  if (payload instanceof ArrayBuffer) return new Uint8Array(payload);
+  throw new WebhookVerificationError(
+    "Payload must be the raw request body (string, Buffer, Uint8Array or ArrayBuffer), not a parsed object"
+  );
+}
+function concat(a, b) {
+  const out = new Uint8Array(new ArrayBuffer(a.length + b.length));
+  out.set(a);
+  out.set(b, a.length);
+  return out;
+}
+var Webhook = class {
+  key;
+  tolerance;
+  cryptoKey;
+  /** @param secret The endpoint's signing secret (`whsec_…`). */
+  constructor(secret, options = {}) {
+    if (typeof secret !== "string" || secret === "") throw new WebhookAdminError("Webhook secret is required");
+    try {
+      this.key = base64Decode(secret.startsWith(PREFIX) ? secret.slice(PREFIX.length) : secret);
+    } catch (e) {
+      throw new WebhookAdminError("Webhook secret is not valid base64 (expected whsec_\u2026)", { cause: e });
+    }
+    this.tolerance = options.tolerance ?? 300;
+  }
+  importKey() {
+    this.cryptoKey ??= webCrypto().then(
+      (c) => c.subtle.importKey("raw", this.key, { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"])
+    );
+    return this.cryptoKey;
+  }
+  /**
+   * Verifies the signature and timestamp, then returns the parsed body.
+   * Throws `WebhookVerificationError` when verification fails.
+   * @param payload The raw request body, exactly as received.
+   */
+  async verify(payload, headers) {
+    const id2 = header(headers, "webhook-id");
+    const timestamp = header(headers, "webhook-timestamp");
+    const signature = header(headers, "webhook-signature");
+    if (!id2 || !timestamp || !signature) throw new WebhookVerificationError("Missing required headers");
+    const ts = Number(timestamp);
+    if (!/^\d+$/.test(timestamp) || !Number.isSafeInteger(ts)) throw new WebhookVerificationError("Invalid webhook-timestamp header");
+    const now = Math.floor(Date.now() / 1e3);
+    if (now - ts > this.tolerance) throw new WebhookVerificationError("Message timestamp too old");
+    if (ts - now > this.tolerance) throw new WebhookVerificationError("Message timestamp too new");
+    const body = bytesOf(payload);
+    const signed = concat(enc.encode(`${id2}.${timestamp}.`), body);
+    const key = await this.importKey();
+    const subtle = (await webCrypto()).subtle;
+    for (const part of signature.split(" ")) {
+      const [version, sig] = part.split(",");
+      if (version !== "v1" || !sig) continue;
+      let expected;
+      try {
+        expected = base64Decode(sig);
+      } catch {
+        continue;
+      }
+      if (await subtle.verify("HMAC", key, expected, signed)) {
+        try {
+          return JSON.parse(dec.decode(body));
+        } catch (e) {
+          throw new WebhookVerificationError("Payload is not valid JSON", { cause: e });
+        }
+      }
+    }
+    throw new WebhookVerificationError("No matching signature found");
+  }
+  /**
+   * Computes the `webhook-signature` value (`v1,<base64>`). Useful for tests.
+   * @param timestamp A `Date` or Unix seconds.
+   */
+  async sign(msgId, timestamp, payload) {
+    const ts = timestamp instanceof Date ? Math.floor(timestamp.getTime() / 1e3) : timestamp;
+    const signed = concat(enc.encode(`${msgId}.${ts}.`), bytesOf(payload));
+    const sig = await (await webCrypto()).subtle.sign("HMAC", await this.importKey(), signed);
+    return `v1,${base64Encode(new Uint8Array(sig))}`;
+  }
+};
+
+exports.ApiError = ApiError;
+exports.AuthenticationError = AuthenticationError;
+exports.ConflictError = ConflictError;
+exports.ConnectionError = ConnectionError;
+exports.NotFoundError = NotFoundError;
+exports.PagePromise = PagePromise;
+exports.PermissionError = PermissionError;
+exports.PlanLimitError = PlanLimitError;
+exports.RateLimitError = RateLimitError;
+exports.TimeoutError = TimeoutError;
+exports.VERSION = VERSION;
+exports.ValidationError = ValidationError;
+exports.Webhook = Webhook;
+exports.WebhookAdmin = WebhookAdmin;
+exports.WebhookAdminError = WebhookAdminError;
+exports.WebhookVerificationError = WebhookVerificationError;