faxforagents 0.0.0-stage → 0.2.2

package/dist/index.js

@@ -0,0 +1,1069 @@
+// src/errors.ts
+var FaxForAgentsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var APIConnectionError = class extends FaxForAgentsError {
+};
+var APITimeoutError = class extends APIConnectionError {
+};
+var APIError = class extends FaxForAgentsError {
+  status;
+  code;
+  retryable;
+  correlationId;
+  details;
+  /** Seconds the API asked us to wait (429), when it said. */
+  retryAfter;
+  constructor(f) {
+    super(`${f.code}: ${f.message}${f.correlationId ? ` (correlation ${f.correlationId})` : ""}`);
+    this.status = f.status;
+    this.code = f.code;
+    this.retryable = f.retryable ?? false;
+    this.correlationId = f.correlationId ?? null;
+    this.details = f.details;
+    this.retryAfter = f.retryAfter ?? null;
+  }
+};
+var InvalidRequestError = class extends APIError {
+};
+var AuthenticationError = class extends APIError {
+};
+var PaymentRequiredError = class extends APIError {
+};
+var ScopeError = class extends APIError {
+};
+var NotFoundError = class extends APIError {
+};
+var ConflictError = class extends APIError {
+};
+var RateLimitedError = class extends APIError {
+};
+var ServerError = class extends APIError {
+};
+var BY_STATUS = {
+  400: InvalidRequestError,
+  401: AuthenticationError,
+  402: PaymentRequiredError,
+  403: ScopeError,
+  404: NotFoundError,
+  409: ConflictError,
+  422: InvalidRequestError,
+  429: RateLimitedError
+};
+function errorFor(status, payload, opts = {}) {
+  const body = payload && typeof payload === "object" ? payload : null;
+  let err = body && body.error && typeof body.error === "object" ? body.error : null;
+  if (!err) {
+    err = {
+      code: `http_${status}`,
+      message: (opts.text ?? "").slice(0, 200) || `HTTP ${status}`,
+      details: body?.detail
+    };
+  }
+  const Cls = status >= 500 ? ServerError : BY_STATUS[status] ?? APIError;
+  return new Cls({
+    status,
+    code: String(err.code ?? `http_${status}`),
+    message: String(err.message ?? `HTTP ${status}`),
+    retryable: typeof err.retryable === "boolean" ? err.retryable : [429, 502, 503, 504].includes(status),
+    correlationId: typeof err.correlation_id === "string" ? err.correlation_id : null,
+    details: err.details,
+    retryAfter: opts.retryAfter ?? null
+  });
+}
+
+// src/version.ts
+var VERSION = "0.2.2";
+
+// src/http.ts
+var DEFAULT_BASE_URL = "https://api.faxforagents.com";
+var MUTATING = /* @__PURE__ */ new Set(["POST", "PATCH", "DELETE"]);
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+function env(name) {
+  const g = globalThis;
+  return g.process?.env?.[name];
+}
+function resolveKey(key) {
+  const value = (key ?? env("FAXFORAGENTS_API_KEY") ?? env("FFA_API_KEY") ?? "").trim();
+  if (!value) {
+    throw new Error(
+      "no API key: pass apiKey or set FAXFORAGENTS_API_KEY. Keys are created in the Fax for Agents dashboard or with POST /v1/api-keys."
+    );
+  }
+  return value;
+}
+function retryAfterSeconds(value, cap) {
+  if (!value) return null;
+  const n = Number(value.trim());
+  if (Number.isFinite(n)) return Math.min(Math.max(n, 0), cap);
+  const at = Date.parse(value);
+  if (Number.isNaN(at)) return null;
+  return Math.max(0, Math.min((at - Date.now()) / 1e3, cap));
+}
+function cleanParams(params) {
+  if (!params) return "";
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== null && v !== void 0) q.set(k, String(v));
+  }
+  const s = q.toString();
+  return s ? `?${s}` : "";
+}
+function stripNulls(json) {
+  if (!json || typeof json !== "object" || Array.isArray(json)) return json;
+  const out = {};
+  for (const [k, v] of Object.entries(json)) {
+    if (v !== void 0 && v !== null) out[k] = v;
+  }
+  return out;
+}
+var sleep = (s) => new Promise((r) => setTimeout(r, Math.max(0, s * 1e3)));
+var Http = class {
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  maxRetries;
+  backoffBase;
+  maxRetryAfter;
+  fetchImpl;
+  extraHeaders;
+  constructor(opts = {}) {
+    this.apiKey = resolveKey(opts.apiKey);
+    this.baseUrl = (opts.baseUrl ?? env("FAXFORAGENTS_API_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? 6e4;
+    this.maxRetries = Math.max(0, opts.maxRetries ?? 3);
+    this.backoffBase = opts.backoffBase ?? 0.5;
+    this.maxRetryAfter = opts.maxRetryAfter ?? 30;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    this.extraHeaders = opts.headers ?? {};
+  }
+  waitFor(attempt, retryAfter) {
+    const explicit = retryAfterSeconds(retryAfter, this.maxRetryAfter);
+    if (explicit !== null) return explicit;
+    return Math.random() * this.backoffBase * 2 ** attempt;
+  }
+  /** The raw Response of a successful call. Throws APIError on 4xx/5xx after the retries. */
+  async send(method, path, opts = {}) {
+    const m = method.toUpperCase();
+    const url = (path.startsWith("http") ? path : this.baseUrl + path) + cleanParams(opts.params);
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "application/json",
+      "User-Agent": `faxforagents-js/${VERSION}`,
+      ...this.extraHeaders,
+      ...opts.headers ?? {}
+    };
+    let body = opts.body;
+    if (opts.json !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(stripNulls(opts.json));
+    }
+    if (MUTATING.has(m) && !("Idempotency-Key" in headers)) {
+      headers["Idempotency-Key"] = opts.idempotencyKey ?? crypto.randomUUID();
+    }
+    let attempt = 0;
+    for (; ; ) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      let resp;
+      try {
+        resp = await this.fetchImpl(url, { method: m, headers, body, signal: controller.signal });
+      } catch (err) {
+        clearTimeout(timer);
+        const timedOut = err?.name === "AbortError";
+        if (attempt >= this.maxRetries) {
+          if (timedOut) throw new APITimeoutError(`${m} ${path} timed out after ${this.timeoutMs} ms`);
+          throw new APIConnectionError(`${this.baseUrl} not reachable (${err?.message ?? err})`);
+        }
+        await sleep(this.waitFor(attempt, null));
+        attempt += 1;
+        continue;
+      }
+      clearTimeout(timer);
+      if (RETRY_STATUSES.has(resp.status) && attempt < this.maxRetries) {
+        await resp.text().catch(() => void 0);
+        await sleep(this.waitFor(attempt, resp.headers.get("retry-after")));
+        attempt += 1;
+        continue;
+      }
+      if (resp.status >= 400) {
+        const text = await resp.text();
+        let payload = null;
+        try {
+          payload = JSON.parse(text);
+        } catch {
+          payload = null;
+        }
+        throw errorFor(resp.status, payload, {
+          retryAfter: retryAfterSeconds(resp.headers.get("retry-after"), this.maxRetryAfter),
+          text
+        });
+      }
+      return resp;
+    }
+  }
+  /** The parsed JSON of a successful call, typed by the caller. */
+  async request(method, path, opts = {}) {
+    const resp = await this.send(method, path, opts);
+    const ctype = resp.headers.get("content-type") ?? "";
+    if (resp.status === 204 || !ctype.startsWith("application/json")) {
+      const text = await resp.text();
+      return text ? JSON.parse(text) : {};
+    }
+    return await resp.json();
+  }
+  /** The bytes of a successful call (signed download URLs). */
+  async bytes(method, path, opts = {}) {
+    const resp = await this.send(method, path, opts);
+    return new Uint8Array(await resp.arrayBuffer());
+  }
+};
+async function* paginate(fetchPage) {
+  let cursor;
+  for (; ; ) {
+    const page = await fetchPage(cursor);
+    for (const item of page.items ?? []) yield item;
+    if (!page.next_cursor) return;
+    cursor = page.next_cursor;
+  }
+}
+
+// src/client.ts
+var TERMINAL_STATES = /* @__PURE__ */ new Set(["delivered", "partial", "failed", "unknown"]);
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+var CONTENT_TYPES = {
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".tif": "image/tiff",
+  ".tiff": "image/tiff"
+};
+function guessContentType(filename) {
+  const dot = filename.lastIndexOf(".");
+  const suffix = dot >= 0 ? filename.slice(dot).toLowerCase() : "";
+  return CONTENT_TYPES[suffix] ?? "application/pdf";
+}
+async function sha256Hex(data) {
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+var Resource = class {
+  constructor(h) {
+    this.h = h;
+  }
+  h;
+};
+var Identity = class extends Resource {
+  /** Who the key is: organization, project, environment, scopes. Scope: any. */
+  me() {
+    return this.h.request("GET", "/v1/me");
+  }
+  /** Keys of the organization, metadata only. Scope: key:admin. */
+  listApiKeys() {
+    return this.h.request("GET", "/v1/api-keys");
+  }
+  /** Create a key. The secret is in the answer once. Scope: key:admin. */
+  createApiKey(body, o = {}) {
+    return this.h.request("POST", "/v1/api-keys", { json: body, ...o });
+  }
+  /** A new secret. The old one works 24 more hours. Scope: key:admin. */
+  rotateApiKey(keyId, o = {}) {
+    return this.h.request("POST", `/v1/api-keys/${keyId}/rotate`, o);
+  }
+  /** Revoke a key at once. Scope: key:admin. */
+  revokeApiKey(keyId, o = {}) {
+    return this.h.request("DELETE", `/v1/api-keys/${keyId}`, o);
+  }
+};
+var Documents = class extends Resource {
+  /**
+   * An immutable document from one of upload_id, text, markdown or html. HTML is rendered with scripts off
+   * and no network, at most 2 MiB. Scope: document:write.
+   */
+  create(body, o = {}) {
+    return this.h.request("POST", "/v1/documents", { json: body, ...o });
+  }
+  /**
+   * Open an upload session with a signed PUT URL (25 MB, one hour). `content_type` is application/pdf,
+   * image/png, image/jpeg or image/tiff. Scope: document:write.
+   */
+  createUpload(body, o = {}) {
+    return this.h.request("POST", "/v1/uploads", { json: body, ...o });
+  }
+  /** Send the bytes to the signed URL from createUpload. No scope, the link is the credential. */
+  putUploadContent(uploadUrl, data, contentType = "application/pdf") {
+    return this.h.request("PUT", uploadUrl, { body: data, headers: { "Content-Type": contentType } });
+  }
+  /** Finalize an upload. The size and, when given, the sha256 are checked. Scope: document:write. */
+  completeUpload(uploadId, body = {}, o = {}) {
+    return this.h.request("POST", `/v1/uploads/${uploadId}/complete`, { json: body, ...o });
+  }
+  /** Cancel an incomplete upload. Scope: document:write. */
+  cancelUpload(uploadId, o = {}) {
+    return this.h.request("DELETE", `/v1/uploads/${uploadId}`, o);
+  }
+  /**
+   * The whole upload path for a PDF or an image (PNG, JPG or TIFF): createUpload, put the bytes, complete
+   * with the sha256, create the document. The content type is read from the filename when not given. An
+   * image becomes gray letter pages.
+   */
+  async upload(data, opts = {}) {
+    const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+    const filename = opts.filename ?? "document.pdf";
+    const contentType = opts.contentType ?? guessContentType(filename);
+    const session = await this.createUpload({ filename, size_bytes: bytes.byteLength, content_type: contentType });
+    if (!session.upload_url) throw new Error("the upload session carries no upload_url");
+    await this.putUploadContent(session.upload_url, bytes, contentType);
+    await this.completeUpload(session.id, { sha256: await sha256Hex(bytes) });
+    return this.create({ upload_id: session.id, filename });
+  }
+  /** Documents, newest first. Scope: document:read. */
+  list(p = {}) {
+    return this.h.request("GET", "/v1/documents", { params: p });
+  }
+  /** Every document, following next_cursor. */
+  iter(p = {}) {
+    return paginate((cursor) => this.list({ ...p, cursor }));
+  }
+  /** Hash, pages and validation state. Scope: document:read. */
+  get(documentId) {
+    return this.h.request("GET", `/v1/documents/${documentId}`);
+  }
+  /** Delete the document, its bytes and its previews. Scope: document:write. */
+  delete(documentId, o = {}) {
+    return this.h.request("DELETE", `/v1/documents/${documentId}`, o);
+  }
+  /** Validation warnings. Scope: document:read. */
+  getValidation(documentId) {
+    return this.h.request("GET", `/v1/documents/${documentId}/validation`);
+  }
+  /** A signed download URL, valid ten minutes. Scope: document:read. */
+  getDownload(documentId) {
+    return this.h.request("GET", `/v1/documents/${documentId}/download`);
+  }
+  /** The document bytes (always a PDF), through a fresh signed URL. */
+  async download(documentId) {
+    const link = await this.getDownload(documentId);
+    return this.h.bytes("GET", link.url);
+  }
+  /** Rendered pages with signed preview URLs. Scope: document:read. */
+  listPages(documentId) {
+    return this.h.request("GET", `/v1/documents/${documentId}/pages`);
+  }
+};
+var Quotes = class extends Resource {
+  /** The exact price of one document to one E.164 destination, valid ten minutes. Scope: fax:quote. */
+  create(body, o = {}) {
+    return this.h.request("POST", "/v1/fax-quotes", { json: body, ...o });
+  }
+  /** Read a quote. Scope: fax:quote. */
+  get(quoteId) {
+    return this.h.request("GET", `/v1/fax-quotes/${quoteId}`);
+  }
+};
+var Faxes = class extends Resource {
+  /** Send a quoted fax. The answer is queued, never delivered. Poll `wait`. Scope: fax:send. */
+  create(body, o = {}) {
+    return this.h.request("POST", "/v1/faxes", { json: body, ...o });
+  }
+  /** Fax jobs, newest first. Scope: fax:read. */
+  list(p = {}) {
+    return this.h.request("GET", "/v1/faxes", { params: p });
+  }
+  /** Every fax job, following next_cursor. */
+  iter(p = {}) {
+    return paginate((cursor) => this.list({ ...p, cursor }));
+  }
+  /** The job with its evidence once delivered or partial. Scope: fax:read. */
+  get(faxId) {
+    return this.h.request("GET", `/v1/faxes/${faxId}`);
+  }
+  /** Poll until the state is delivered, partial, failed or unknown. Returns the last job read. */
+  async wait(faxId, opts = {}) {
+    const deadline = Date.now() + (opts.timeoutMs ?? 3e5);
+    let job = await this.get(faxId);
+    while (!TERMINAL_STATES.has(job.state) && Date.now() < deadline) {
+      await sleep2(opts.intervalMs ?? 2e3);
+      job = await this.get(faxId);
+    }
+    return job;
+  }
+  /** Ordered events of one fax. Scope: fax:read. */
+  listEvents(faxId) {
+    return this.h.request("GET", `/v1/faxes/${faxId}/events`);
+  }
+  /** Attempt history. Scope: fax:read. */
+  listAttempts(faxId) {
+    return this.h.request("GET", `/v1/faxes/${faxId}/attempts`);
+  }
+  /** Delivery evidence as a receipt. Scope: fax:read. */
+  getReceipt(faxId) {
+    return this.h.request("GET", `/v1/faxes/${faxId}/receipt`);
+  }
+  /** Cancel while queued, best effort once sending. Scope: fax:cancel. */
+  cancel(faxId, o = {}) {
+    return this.h.request("POST", `/v1/faxes/${faxId}/cancel`, { json: {}, ...o });
+  }
+};
+var Webhooks = class extends Resource {
+  /** Registered destinations. Scope: webhook:admin. */
+  list() {
+    return this.h.request("GET", "/v1/webhooks");
+  }
+  /** Register a destination. The secret is in the answer once. Scope: webhook:admin. */
+  create(body, o = {}) {
+    return this.h.request("POST", "/v1/webhooks", { json: body, ...o });
+  }
+  /** Change url, description, event_types or status. Scope: webhook:admin. */
+  update(webhookId, body, o = {}) {
+    return this.h.request("PATCH", `/v1/webhooks/${webhookId}`, { json: body, ...o });
+  }
+  /** Remove a destination. Scope: webhook:admin. */
+  delete(webhookId, o = {}) {
+    return this.h.request("DELETE", `/v1/webhooks/${webhookId}`, o);
+  }
+  /** A new secret. The old one signs too for 24 hours. Scope: webhook:admin. */
+  rotateSecret(webhookId, o = {}) {
+    return this.h.request("POST", `/v1/webhooks/${webhookId}/rotate-secret`, o);
+  }
+  /** Send a signed webhook.test event to the destination. Scope: webhook:admin. */
+  test(webhookId, o = {}) {
+    return this.h.request("POST", `/v1/webhooks/${webhookId}/test`, { json: {}, ...o });
+  }
+  /** Delivery attempts. Scope: webhook:admin. */
+  listDeliveries(p = {}) {
+    return this.h.request("GET", "/v1/webhook-deliveries", { params: p });
+  }
+  /** Deliver the event again with the same event id. Scope: webhook:admin. */
+  replayDelivery(deliveryId, o = {}) {
+    return this.h.request("POST", `/v1/webhook-deliveries/${deliveryId}/replay`, { json: {}, ...o });
+  }
+};
+var Events = class extends Resource {
+  /** Events for reconciliation, oldest first from the cursor. Scope: fax:read. */
+  list(p = {}) {
+    return this.h.request("GET", "/v1/events", { params: p });
+  }
+  /** Every event, following next_cursor. */
+  iter(p = {}) {
+    return paginate((cursor) => this.list({ ...p, cursor }));
+  }
+};
+var Billing = class extends Resource {
+  /** Available and held balance of this key's environment. Scope: billing:read. */
+  balance() {
+    return this.h.request("GET", "/v1/balance");
+  }
+  /** Wallet transactions, newest first. Scope: billing:read. */
+  listLedger(p = {}) {
+    return this.h.request("GET", "/v1/ledger", { params: p });
+  }
+  /** Billing settings of the organization. Scope: billing:read. */
+  getSettings() {
+    return this.h.request("GET", "/v1/billing-settings");
+  }
+  /** Change the billing email or the low-balance threshold. Scope: billing:write. */
+  patchSettings(body, o = {}) {
+    return this.h.request("PATCH", "/v1/billing-settings", { json: body, ...o });
+  }
+  /** A hosted Checkout to fund the live wallet. Scope: billing:write. */
+  createTopupSession(body, o = {}) {
+    return this.h.request("POST", "/v1/topup-sessions", { json: body, ...o });
+  }
+  /** Top-up sessions, newest first. Scope: billing:read. */
+  listTopupSessions(p = {}) {
+    return this.h.request("GET", "/v1/topup-sessions", { params: p });
+  }
+  /** Read a top-up session. Scope: billing:read. */
+  getTopupSession(topupSessionId) {
+    return this.h.request("GET", `/v1/topup-sessions/${topupSessionId}`);
+  }
+  /** Auto top-up settings. Scope: billing:read. */
+  listAutoTopups() {
+    return this.h.request("GET", "/v1/auto-topups");
+  }
+  /** Opt in to auto top-up. Scope: billing:write. */
+  createAutoTopup(body, o = {}) {
+    return this.h.request("POST", "/v1/auto-topups", { json: body, ...o });
+  }
+  /** Turn auto top-up off. Scope: billing:write. */
+  deleteAutoTopup(autoTopupId, o = {}) {
+    return this.h.request("DELETE", `/v1/auto-topups/${autoTopupId}`, o);
+  }
+  /** Spending caps of this environment. Scope: billing:read. */
+  listBudgets() {
+    return this.h.request("GET", "/v1/budgets");
+  }
+  /** A daily or monthly cap for the organization, a project or an agent. Scope: billing:write. */
+  createBudget(body, o = {}) {
+    return this.h.request("POST", "/v1/budgets", { json: body, ...o });
+  }
+  /** Change a cap's limit or status. Scope: billing:write. */
+  patchBudget(budgetId, body, o = {}) {
+    return this.h.request("PATCH", `/v1/budgets/${budgetId}`, { json: body, ...o });
+  }
+  /** Usage rollups by day, direction, destination and project. Scope: billing:read. */
+  usage(p = {}) {
+    return this.h.request("GET", "/v1/usage", { params: p });
+  }
+  /** Export usage as CSV behind a signed download. Scope: billing:read. */
+  createUsageExport(body, o = {}) {
+    return this.h.request("POST", "/v1/usage-exports", { json: body, ...o });
+  }
+  /** Read a usage export with a fresh link. Scope: billing:read. */
+  getUsageExport(exportId) {
+    return this.h.request("GET", `/v1/usage-exports/${exportId}`);
+  }
+  /** Stripe invoices and receipts as hosted links. Scope: billing:read. */
+  listInvoices(p = {}) {
+    return this.h.request("GET", "/v1/invoices", { params: p });
+  }
+  /** One invoice. Scope: billing:read. */
+  getInvoice(invoiceId) {
+    return this.h.request("GET", `/v1/invoices/${invoiceId}`);
+  }
+  /** A hosted Checkout for the Agent workspace subscription. Scope: billing:write. */
+  createSubscriptionCheckout(o = {}) {
+    return this.h.request("POST", "/v1/subscriptions/checkout", { json: {}, ...o });
+  }
+  /** Subscriptions and the workspace entitlement. Scope: billing:read. */
+  listSubscriptions() {
+    return this.h.request("GET", "/v1/subscriptions");
+  }
+  /** The Stripe customer portal. Scope: billing:write. */
+  createPortalSession(o = {}) {
+    return this.h.request("POST", "/v1/billing-portal-sessions", { json: {}, ...o });
+  }
+};
+var Platform = class extends Resource {
+  /** Limits, routes, formats, prices and scopes in force. Scope: any. */
+  capabilities() {
+    return this.h.request("GET", "/v1/capabilities");
+  }
+  /** Customer-safe availability. Scope: any. */
+  serviceStatus() {
+    return this.h.request("GET", "/v1/service-status");
+  }
+};
+var Sandbox = class extends Resource {
+  /** The scenario catalog, the destination table and active fixtures. Test keys only. */
+  listScenarios() {
+    return this.h.request("GET", "/v1/sandbox/scenarios");
+  }
+  /** Pin an outcome to a destination (or to every send) for 24 hours. Test keys only. */
+  createScenario(body, o = {}) {
+    return this.h.request("POST", "/v1/sandbox/scenarios", { json: body, ...o });
+  }
+  /** A synthetic received fax and its fax.received event. Test keys only. */
+  createInboundFax(body, o = {}) {
+    return this.h.request("POST", "/v1/sandbox/inbound-faxes", { json: body, ...o });
+  }
+  /** Delete the organization's test data and reseed the test wallet. Test keys only. */
+  reset(o = {}) {
+    return this.h.request("DELETE", "/v1/sandbox/data", o);
+  }
+};
+var Approvals = class extends Resource {
+  /** Ask a person to approve a quoted send. Grants nothing. Scope: approval:request. */
+  request(quoteId, o = {}) {
+    return this.h.request("POST", "/v1/approval-requests", { json: { kind: "send", quote_id: quoteId }, ...o });
+  }
+  /** Ask a person for help. The message is shown as data. Scope: approval:request. */
+  requestHelp(message, opts = {}) {
+    const { faxJobId, ...o } = opts;
+    return this.h.request("POST", "/v1/approval-requests", {
+      json: { kind: "help", message, fax_job_id: faxJobId },
+      ...o
+    });
+  }
+  /** Requests, pending first. Scope: approval:read. */
+  list(p = {}) {
+    return this.h.request("GET", "/v1/approval-requests", { params: p });
+  }
+  /** Every request, following next_cursor. */
+  iter(p = {}) {
+    return paginate((cursor) => this.list({ ...p, cursor }));
+  }
+  /** One request. Scope: approval:read. */
+  get(approvalId) {
+    return this.h.request("GET", `/v1/approval-requests/${approvalId}`);
+  }
+  /** Poll until the request leaves pending, or the timeout passes. */
+  async wait(approvalId, opts = {}) {
+    const deadline = Date.now() + (opts.timeoutMs ?? 6e5);
+    let req = await this.get(approvalId);
+    while (req.status === "pending" && Date.now() < deadline) {
+      await sleep2(opts.intervalMs ?? 5e3);
+      req = await this.get(approvalId);
+    }
+    return req;
+  }
+  /** Approve the bound send. Scope: approval:decide, never the key that asked, never an agent key. */
+  approve(approvalId, body = {}, o = {}) {
+    return this.h.request("POST", `/v1/approval-requests/${approvalId}/approve`, { json: body, ...o });
+  }
+  /** Reject with a reason. Scope: approval:decide. */
+  reject(approvalId, body, o = {}) {
+    return this.h.request("POST", `/v1/approval-requests/${approvalId}/reject`, { json: body, ...o });
+  }
+  /** Revoke an approval nobody has used yet. Scope: approval:decide. */
+  revoke(approvalId, body = {}, o = {}) {
+    return this.h.request("POST", `/v1/approvals/${approvalId}/revoke`, { json: body, ...o });
+  }
+};
+var Policies = class extends Resource {
+  /** The organization's policies. Scope: policy:read. */
+  list() {
+    return this.h.request("GET", "/v1/policies");
+  }
+  /** Create a delegated policy, version 1. Scope: policy:admin, never an agent key. */
+  create(body, o = {}) {
+    return this.h.request("POST", "/v1/policies", { json: body, ...o });
+  }
+  /** What this key is allowed to do alone, and whether a human is needed. Scope: policy:read. */
+  effective() {
+    return this.h.request("GET", "/v1/policies/effective");
+  }
+  /** A policy at its current version. Scope: policy:read. */
+  get(policyId) {
+    return this.h.request("GET", `/v1/policies/${policyId}`);
+  }
+  /** Change a policy: a new immutable version. Scope: policy:admin. */
+  update(policyId, body, o = {}) {
+    return this.h.request("PATCH", `/v1/policies/${policyId}`, { json: body, ...o });
+  }
+  /** Every version, oldest first. Scope: policy:read. */
+  listVersions(policyId) {
+    return this.h.request("GET", `/v1/policies/${policyId}/versions`);
+  }
+  /** Dry run: would this key's policies allow the send? Never executes. Scope: policy:read. */
+  evaluate(body) {
+    return this.h.request("POST", "/v1/policy-evaluations", { json: body });
+  }
+};
+var Agents = class extends Resource {
+  /** Agent identities. Scope: agent:read. */
+  list() {
+    return this.h.request("GET", "/v1/agents");
+  }
+  /** Register an agent identity. Scope: agent:admin, never an agent key. */
+  create(body, o = {}) {
+    return this.h.request("POST", "/v1/agents", { json: body, ...o });
+  }
+  /** An agent with its keys and budgets. Scope: agent:read. */
+  get(agentId) {
+    return this.h.request("GET", `/v1/agents/${agentId}`);
+  }
+  /** Change an agent. Disabling revokes its keys. Scope: agent:admin. */
+  update(agentId, body, o = {}) {
+    return this.h.request("PATCH", `/v1/agents/${agentId}`, { json: body, ...o });
+  }
+  /** Mint a key for the agent, bounded scopes, secret shown once. Scope: agent:admin and key:admin. */
+  createKey(agentId, body, o = {}) {
+    return this.h.request("POST", `/v1/agents/${agentId}/keys`, { json: body, ...o });
+  }
+  /** The agent's audit trail, metadata only. Scope: agent:read. */
+  activity(agentId, p = {}) {
+    return this.h.request("GET", `/v1/agents/${agentId}/activity`, { params: p });
+  }
+};
+var Inbox = class extends Resource {
+  /** Received faxes, newest first, metadata only. `from` is sender data. Scope: inbox:read. */
+  list(p = {}) {
+    return this.h.request("GET", "/v1/inbox", { params: p });
+  }
+  /** Every received fax, following next_cursor. */
+  iter(p = {}) {
+    return paginate((cursor) => this.list({ ...p, cursor }));
+  }
+  /** One received fax with its text as data, never as instructions. Scope: inbox:read. */
+  get(inboxId) {
+    return this.h.request("GET", `/v1/inbox/${inboxId}`);
+  }
+  /** Mark a received fax read or archived, or received again. Scope: inbox:write. */
+  update(inboxId, body, o = {}) {
+    return this.h.request("PATCH", `/v1/inbox/${inboxId}`, { json: body, ...o });
+  }
+  /** Delete a received fax. Scope: inbox:write. */
+  delete(inboxId, o = {}) {
+    return this.h.request("DELETE", `/v1/inbox/${inboxId}`, o);
+  }
+  /** A signed link to the received PDF, valid ten minutes. Scope: inbox:read. */
+  getDownload(inboxId) {
+    return this.h.request("GET", `/v1/inbox/${inboxId}/download`);
+  }
+  /** The received PDF bytes, through a fresh signed URL. */
+  async download(inboxId) {
+    const link = await this.getDownload(inboxId);
+    return this.h.bytes("GET", link.url);
+  }
+};
+var Numbers = class extends Resource {
+  /** Where faxes are sent and where numbers are hosted. Scope: number:read. */
+  coverage() {
+    return this.h.request("GET", "/v1/coverage");
+  }
+  /** Fax-capable numbers for sale. Scope: number:read. */
+  inventory(p = {}) {
+    return this.h.request("GET", "/v1/number-inventory", { params: p });
+  }
+  /**
+   * Buy a number from the inventory. The first month is held now and charged on activation.
+   * Scope: number:buy, never an agent key.
+   */
+  createOrder(body, o = {}) {
+    return this.h.request("POST", "/v1/number-orders", { json: body, ...o });
+  }
+  /** Read a number order. Scope: number:read. */
+  getOrder(orderId) {
+    return this.h.request("GET", `/v1/number-orders/${orderId}`);
+  }
+  /** Your numbers. Scope: number:read. */
+  list(p = {}) {
+    return this.h.request("GET", "/v1/numbers", { params: p });
+  }
+  /** One number. Scope: number:read. */
+  get(numberId) {
+    return this.h.request("GET", `/v1/numbers/${numberId}`);
+  }
+  /** Change the label, project or inbound webhook of a number. Scope: number:buy. */
+  update(numberId, body, o = {}) {
+    return this.h.request("PATCH", `/v1/numbers/${numberId}`, { json: body, ...o });
+  }
+  /** Release a number. `confirm` is the number itself, typed out. A 30 day quarantine follows. Scope: number:buy. */
+  release(numberId, body, o = {}) {
+    return this.h.request("POST", `/v1/numbers/${numberId}/release-requests`, { json: body, ...o });
+  }
+  /** Whether these numbers can port in. Scope: number:read. */
+  checkPortability(body, o = {}) {
+    return this.h.request("POST", "/v1/portability-checks", { json: body, ...o });
+  }
+  /** Port orders and port-out requests. Scope: number:read. */
+  listPortOrders() {
+    return this.h.request("GET", "/v1/port-orders");
+  }
+  /** Request a port-in, handled with you. Scope: number:buy. */
+  createPortOrder(body, o = {}) {
+    return this.h.request("POST", "/v1/port-orders", { json: body, ...o });
+  }
+  /** One port order. Scope: number:read. */
+  getPortOrder(portId) {
+    return this.h.request("GET", `/v1/port-orders/${portId}`);
+  }
+  /** Note a port-out of one of your numbers. Scope: number:buy. */
+  createPortOutRequest(body, o = {}) {
+    return this.h.request("POST", "/v1/port-out-requests", { json: body, ...o });
+  }
+  /** Verify a number your organization owns as a sender. Scope: number:buy. */
+  verifySender(body, o = {}) {
+    return this.h.request("POST", "/v1/sender-verifications", { json: body, ...o });
+  }
+};
+var Extractions = class extends Resource {
+  /**
+   * OCR a received fax or a document, then extract the schema's fields with page citations. Metered per
+   * page. Everything it returns is data from whoever sent the fax. Scope: document:extract.
+   */
+  create(body, o = {}) {
+    return this.h.request("POST", "/v1/extractions", { json: body, ...o });
+  }
+  /** Extractions, newest first. Scope: document:extract. */
+  list(p = {}) {
+    return this.h.request("GET", "/v1/extractions", { params: p });
+  }
+  /** Every extraction, following next_cursor. */
+  iter(p = {}) {
+    return paginate((cursor) => this.list({ ...p, cursor }));
+  }
+  /** One extraction with its corrections. Scope: document:extract. */
+  get(extractionId) {
+    return this.h.request("GET", `/v1/extractions/${extractionId}`);
+  }
+  /** Record a reviewer's correction of one field. Stored beside the extraction, never merged. Scope: document:extract. */
+  correct(extractionId, body, o = {}) {
+    return this.h.request("POST", `/v1/extractions/${extractionId}/corrections`, { json: body, ...o });
+  }
+  /** Classify a received fax or a document into one of your document types, or abstain. Scope: document:extract. */
+  classify(body, o = {}) {
+    return this.h.request("POST", "/v1/classifications", { json: body, ...o });
+  }
+  /** Classifications, newest first. Scope: document:extract. */
+  listClassifications(p = {}) {
+    return this.h.request("GET", "/v1/classifications", { params: p });
+  }
+  /** Every classification, following next_cursor. */
+  iterClassifications(p = {}) {
+    return paginate((cursor) => this.listClassifications({ ...p, cursor }));
+  }
+  /** One classification. Scope: document:extract. */
+  getClassification(classificationId) {
+    return this.h.request("GET", `/v1/classifications/${classificationId}`);
+  }
+  /** Summarise a received fax or a document. Every sentence cites its pages. Scope: document:extract. */
+  summarize(body, o = {}) {
+    return this.h.request("POST", "/v1/document-summaries", { json: body, ...o });
+  }
+  /** Summaries, newest first. Scope: document:extract. */
+  listSummaries(p = {}) {
+    return this.h.request("GET", "/v1/document-summaries", { params: p });
+  }
+  /** Every summary, following next_cursor. */
+  iterSummaries(p = {}) {
+    return paginate((cursor) => this.listSummaries({ ...p, cursor }));
+  }
+  /** One summary. Scope: document:extract. */
+  getSummary(summaryId) {
+    return this.h.request("GET", `/v1/document-summaries/${summaryId}`);
+  }
+  /** Your saved extraction schemas. Scope: document:extract. */
+  listSchemas() {
+    return this.h.request("GET", "/v1/extraction-schemas");
+  }
+  /** Save a versioned extraction schema. The same name again is the next version. Scope: document:extract. */
+  createSchema(body, o = {}) {
+    return this.h.request("POST", "/v1/extraction-schemas", { json: body, ...o });
+  }
+  /** One schema version. Scope: document:extract. */
+  getSchema(schemaId) {
+    return this.h.request("GET", `/v1/extraction-schemas/${schemaId}`);
+  }
+};
+var Organizations = class extends Resource {
+  /** The organizations the caller belongs to. Scope: any. */
+  list() {
+    return this.h.request("GET", "/v1/organizations");
+  }
+  /** The organization of this key. Scope: account:read. */
+  current() {
+    return this.h.request("GET", "/v1/organizations/current");
+  }
+  /** Rename the organization. Scope: member:admin, never an agent key. */
+  updateCurrent(body, o = {}) {
+    return this.h.request("PATCH", "/v1/organizations/current", { json: body, ...o });
+  }
+  /** Ask for an export of the organization's data. Scope: org:admin, never an agent key. */
+  requestDataExport(o = {}) {
+    return this.h.request("POST", "/v1/organizations/current/export-requests", { json: {}, ...o });
+  }
+  /** Ask for the organization and its data to be deleted. Scope: org:admin, never an agent key. */
+  requestDataDeletion(o = {}) {
+    return this.h.request("POST", "/v1/organizations/current/deletion-requests", { json: {}, ...o });
+  }
+};
+var Members = class extends Resource {
+  /** The organization's members. Scope: account:read. */
+  list() {
+    return this.h.request("GET", "/v1/members");
+  }
+  /** Change a member's role: owner, admin, member or viewer. Scope: member:admin, never an agent key. */
+  update(memberId, body, o = {}) {
+    return this.h.request("PATCH", `/v1/members/${memberId}`, { json: body, ...o });
+  }
+  /** Remove a member. Scope: org:admin, never an agent key. */
+  async remove(memberId, o = {}) {
+    await this.h.request("DELETE", `/v1/members/${memberId}`, o);
+  }
+  /** Open invitations. Scope: member:admin. */
+  listInvitations() {
+    return this.h.request("GET", "/v1/invitations");
+  }
+  /** Invite someone by email, a link that works for 7 days. Scope: member:admin, never an agent key. */
+  invite(body, o = {}) {
+    return this.h.request("POST", "/v1/invitations", { json: body, ...o });
+  }
+  /** Withdraw an invitation. Scope: member:admin, never an agent key. */
+  async revokeInvitation(invitationId, o = {}) {
+    await this.h.request("DELETE", `/v1/invitations/${invitationId}`, o);
+  }
+};
+var FaxForAgents = class {
+  http;
+  identity;
+  documents;
+  quotes;
+  faxes;
+  webhooks;
+  events;
+  billing;
+  platform;
+  sandbox;
+  approvals;
+  policies;
+  agents;
+  inbox;
+  numbers;
+  extractions;
+  organizations;
+  members;
+  constructor(opts = {}) {
+    this.http = new Http(opts);
+    this.identity = new Identity(this.http);
+    this.documents = new Documents(this.http);
+    this.quotes = new Quotes(this.http);
+    this.faxes = new Faxes(this.http);
+    this.webhooks = new Webhooks(this.http);
+    this.events = new Events(this.http);
+    this.billing = new Billing(this.http);
+    this.platform = new Platform(this.http);
+    this.sandbox = new Sandbox(this.http);
+    this.approvals = new Approvals(this.http);
+    this.policies = new Policies(this.http);
+    this.agents = new Agents(this.http);
+    this.inbox = new Inbox(this.http);
+    this.numbers = new Numbers(this.http);
+    this.extractions = new Extractions(this.http);
+    this.organizations = new Organizations(this.http);
+    this.members = new Members(this.http);
+  }
+  /** Shortcut for identity.me(). */
+  me() {
+    return this.identity.me();
+  }
+  /** Any operation the resources do not cover yet. Returns the parsed JSON. */
+  request(method, path, opts = {}) {
+    return this.http.request(method, path, opts);
+  }
+};
+
+// src/webhooks.ts
+var SECRET_PREFIX = "whsec_";
+var TOLERANCE_S = 300;
+var SignatureError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SignatureError";
+  }
+};
+var enc = new TextEncoder();
+function b64encode(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+function b64decode(text) {
+  const s = atob(text);
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+function keyBytes(secret) {
+  const raw = secret.startsWith(SECRET_PREFIX) ? secret.slice(SECRET_PREFIX.length) : secret;
+  return b64decode(raw);
+}
+function toBytes(body) {
+  if (typeof body === "string") return enc.encode(body);
+  if (body instanceof ArrayBuffer) return new Uint8Array(body);
+  return new Uint8Array(body);
+}
+function headerLookup(headers) {
+  if (typeof headers.get === "function") {
+    const h = headers;
+    return (name) => h.get(name) ?? "";
+  }
+  const map = /* @__PURE__ */ new Map();
+  const entries = typeof headers[Symbol.iterator] === "function" ? headers : Object.entries(headers);
+  for (const [k, v] of entries) {
+    const value = Array.isArray(v) ? v.join(" ") : v;
+    if (typeof value === "string") map.set(k.toLowerCase(), value);
+  }
+  return (name) => map.get(name) ?? "";
+}
+function timingSafeEqual(a, b) {
+  const x = enc.encode(a);
+  const y = enc.encode(b);
+  if (x.length !== y.length) return false;
+  let diff = 0;
+  for (let i = 0; i < x.length; i++) diff |= x[i] ^ y[i];
+  return diff === 0;
+}
+async function sign(secret, msgId, timestamp, body) {
+  const key = await crypto.subtle.importKey("raw", keyBytes(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign"
+  ]);
+  const prefix = enc.encode(`${msgId}.${timestamp}.`);
+  const payload = toBytes(body);
+  const toSign = new Uint8Array(prefix.length + payload.length);
+  toSign.set(prefix, 0);
+  toSign.set(payload, prefix.length);
+  const digest = await crypto.subtle.sign("HMAC", key, toSign);
+  return "v1," + b64encode(new Uint8Array(digest));
+}
+async function signatureHeaders(secrets, msgId, body, timestamp = Math.floor(Date.now() / 1e3)) {
+  const sigs = await Promise.all(secrets.map((s) => sign(s, msgId, timestamp, body)));
+  return {
+    "webhook-id": msgId,
+    "webhook-timestamp": String(timestamp),
+    "webhook-signature": sigs.join(" "),
+    "content-type": "application/json"
+  };
+}
+async function verifyWebhook(secret, headers, body, opts = {}) {
+  const get = headerLookup(headers);
+  const msgId = get("webhook-id");
+  const tsRaw = get("webhook-timestamp");
+  const sigs = get("webhook-signature");
+  if (!msgId || !tsRaw || !sigs) throw new SignatureError("missing webhook headers");
+  if (!/^\d+$/.test(tsRaw.trim())) throw new SignatureError("bad timestamp");
+  const ts = Number(tsRaw);
+  const now = opts.now ?? Date.now() / 1e3;
+  if (Math.abs(now - ts) > (opts.toleranceS ?? TOLERANCE_S)) throw new SignatureError("timestamp outside tolerance");
+  const expected = await sign(secret, msgId, ts, body);
+  for (const candidate of sigs.split(/\s+/)) {
+    if (candidate.startsWith("v1,") && timingSafeEqual(candidate, expected)) return msgId;
+  }
+  throw new SignatureError("no matching signature");
+}
+function parseEvent(body) {
+  const text = typeof body === "string" ? body : new TextDecoder().decode(toBytes(body));
+  return JSON.parse(text);
+}
+export {
+  APIConnectionError,
+  APIError,
+  APITimeoutError,
+  Agents,
+  Approvals,
+  AuthenticationError,
+  Billing,
+  CONTENT_TYPES,
+  FaxForAgents as Client,
+  ConflictError,
+  DEFAULT_BASE_URL,
+  Documents,
+  Events,
+  Extractions,
+  FaxForAgents,
+  FaxForAgentsError,
+  Faxes,
+  Http,
+  Identity,
+  Inbox,
+  InvalidRequestError,
+  Members,
+  NotFoundError,
+  Numbers,
+  Organizations,
+  PaymentRequiredError,
+  Platform,
+  Policies,
+  Quotes,
+  RateLimitedError,
+  Sandbox,
+  ScopeError,
+  ServerError,
+  SignatureError,
+  TERMINAL_STATES,
+  VERSION,
+  Webhooks,
+  guessContentType,
+  paginate,
+  parseEvent,
+  sign,
+  signatureHeaders,
+  verifyWebhook
+};
+//# sourceMappingURL=index.js.map