@legalize-dev/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1063 @@
+import * as os from 'os';
+import { createHmac, timingSafeEqual } from 'crypto';
+
+// src/client.ts
+
+// src/retry.ts
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_INITIAL_DELAY = 0.5;
+var DEFAULT_MAX_DELAY = 30;
+var DEFAULT_BACKOFF_FACTOR = 2;
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "HEAD",
+  "OPTIONS",
+  "PUT",
+  "DELETE"
+]);
+var RetryPolicy = class {
+  maxRetries;
+  initialDelay;
+  maxDelay;
+  backoffFactor;
+  retryNonIdempotent;
+  constructor(options = {}) {
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.initialDelay = options.initialDelay ?? DEFAULT_INITIAL_DELAY;
+    this.maxDelay = options.maxDelay ?? DEFAULT_MAX_DELAY;
+    this.backoffFactor = options.backoffFactor ?? DEFAULT_BACKOFF_FACTOR;
+    this.retryNonIdempotent = options.retryNonIdempotent ?? false;
+  }
+  /**
+   * Decide whether to retry given attempt index, HTTP status, and method.
+   *
+   * `status` is undefined when the failure was a transport error before
+   * the server returned a status. Transport errors are retried for any
+   * method (the request never hit the server, so the "don't duplicate
+   * mutations" concern doesn't apply).
+   */
+  shouldRetry(attempt, options) {
+    if (attempt >= this.maxRetries) return false;
+    const method = (options.method ?? "GET").toUpperCase();
+    if (options.status === void 0) {
+      return true;
+    }
+    if (!RETRY_STATUSES.has(options.status)) return false;
+    if (this.retryNonIdempotent) return true;
+    return IDEMPOTENT_METHODS.has(method);
+  }
+  /**
+   * Seconds to wait before retry `attempt` (0-indexed).
+   *
+   * `Retry-After` wins unambiguously when present and non-negative: the
+   * server is telling us exactly how long to wait. Otherwise we use
+   * exponential backoff with full jitter:
+   *
+   *     delay = random.uniform(0, min(maxDelay, initial * factor^attempt))
+   *
+   * Full jitter beats "equal jitter" and "decorrelated jitter" for
+   * preventing thundering-herd recovery spikes.
+   */
+  computeDelay(attempt, options) {
+    if (options.retryAfter !== void 0 && options.retryAfter >= 0) {
+      return Math.min(options.retryAfter, this.maxDelay);
+    }
+    const base = this.initialDelay * Math.pow(this.backoffFactor, attempt);
+    const capped = Math.min(base, this.maxDelay);
+    return Math.random() * capped;
+  }
+};
+function parseRetryAfter(header) {
+  if (header === null || header === void 0) return void 0;
+  const trimmed = header.trim();
+  if (!trimmed) return void 0;
+  if (/^-?\d+$/.test(trimmed)) {
+    const n = parseInt(trimmed, 10);
+    return Math.max(0, n);
+  }
+  const parsed = Date.parse(trimmed);
+  if (Number.isNaN(parsed)) return void 0;
+  const nowMs = Date.now();
+  const delta = (parsed - nowMs) / 1e3;
+  return Math.max(0, delta);
+}
+function sleep(seconds) {
+  if (seconds <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+}
+
+// src/errors.ts
+var LegalizeError = class extends Error {
+  name = "LegalizeError";
+  constructor(message, options) {
+    super(message);
+    if (options?.cause !== void 0) {
+      this.cause = options.cause;
+    }
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var APIError = class extends LegalizeError {
+  name = "APIError";
+  statusCode;
+  code;
+  body;
+  data;
+  requestId;
+  response;
+  constructor(options) {
+    super(options.message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.statusCode = options.statusCode;
+    this.code = options.code;
+    this.body = options.body;
+    this.data = options.data;
+    this.requestId = options.requestId;
+    this.response = options.response;
+  }
+  toString() {
+    const parts = [];
+    if (this.statusCode !== void 0) parts.push(`HTTP ${this.statusCode}`);
+    if (this.code) parts.push(this.code);
+    parts.push(this.message);
+    if (this.requestId) parts.push(`(request_id=${this.requestId})`);
+    return parts.join(" ");
+  }
+  /**
+   * Build the most specific APIError subclass for a response.
+   *
+   * `body` is the raw bytes of the response body (or the parsed JSON
+   * object if already consumed). `data` is the parsed JSON, which
+   * drives error-code dispatch. Reads `X-Request-Id` for support.
+   */
+  static fromResponse(response, body, data) {
+    const status = response.status;
+    const parsedData = data !== void 0 ? data : body;
+    const { code, message, extras } = parseErrorBody(parsedData, response);
+    const requestId = response.headers.get("x-request-id") ?? response.headers.get("X-Request-Id") ?? void 0;
+    const ErrorClass = pickErrorClass(status);
+    const err = new ErrorClass({
+      message,
+      statusCode: status,
+      code,
+      body,
+      data: parsedData,
+      requestId,
+      response
+    });
+    for (const [k, v] of Object.entries(extras)) {
+      err[k] = v;
+    }
+    return err;
+  }
+};
+var AuthenticationError = class extends APIError {
+  name = "AuthenticationError";
+};
+var ForbiddenError = class extends APIError {
+  name = "ForbiddenError";
+};
+var NotFoundError = class extends APIError {
+  name = "NotFoundError";
+};
+var InvalidRequestError = class extends APIError {
+  name = "InvalidRequestError";
+};
+var ValidationError = class extends APIError {
+  name = "ValidationError";
+  errors = [];
+};
+var RateLimitError = class extends APIError {
+  name = "RateLimitError";
+  retryAfter;
+  limit;
+};
+var ServerError = class extends APIError {
+  name = "ServerError";
+};
+var ServiceUnavailableError = class extends ServerError {
+  name = "ServiceUnavailableError";
+};
+var APIConnectionError = class extends LegalizeError {
+  name = "APIConnectionError";
+};
+var APITimeoutError = class extends APIConnectionError {
+  name = "APITimeoutError";
+};
+var WebhookVerificationError = class extends LegalizeError {
+  name = "WebhookVerificationError";
+  reason;
+  constructor(reason) {
+    super("Webhook signature verification failed");
+    this.reason = reason;
+  }
+};
+function parseErrorBody(data, response) {
+  const extras = {};
+  let code;
+  let message = "";
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    const dataObj = data;
+    const detailRaw = "detail" in dataObj ? dataObj.detail : dataObj;
+    if (detailRaw && typeof detailRaw === "object" && !Array.isArray(detailRaw)) {
+      const detail = detailRaw;
+      code = detail.error ?? detail.code;
+      message = detail.message ?? detail.detail ?? "";
+      for (const key of ["retry_after", "limit", "upgrade_url"]) {
+        if (key in detail) {
+          if (key === "retry_after") {
+            extras.retryAfter = detail[key];
+          } else {
+            extras[key] = detail[key];
+          }
+        }
+      }
+    } else if (Array.isArray(detailRaw)) {
+      extras.errors = detailRaw;
+      if (detailRaw.length > 0) {
+        const first = detailRaw[0];
+        message = first.msg ?? "validation error";
+      } else {
+        message = "validation error";
+      }
+    } else if (typeof detailRaw === "string") {
+      message = detailRaw;
+    }
+  }
+  if (extras.retryAfter === void 0) {
+    const parsed = parseRetryAfter(response.headers.get("retry-after"));
+    if (parsed !== void 0) {
+      extras.retryAfter = parsed;
+    }
+  }
+  if (!message) {
+    message = `HTTP ${response.status}`;
+  }
+  return { code, message, extras };
+}
+function pickErrorClass(status) {
+  if (status === 400) return InvalidRequestError;
+  if (status === 401) return AuthenticationError;
+  if (status === 403) return ForbiddenError;
+  if (status === 404) return NotFoundError;
+  if (status === 422) return ValidationError;
+  if (status === 429) return RateLimitError;
+  if (status === 503) return ServiceUnavailableError;
+  if (status >= 500 && status < 600) return ServerError;
+  return APIError;
+}
+
+// src/env.ts
+var DEFAULT_BASE_URL = "https://legalize.dev";
+var DEFAULT_API_VERSION = "v1";
+var DEFAULT_TIMEOUT = 3e4;
+var KEY_PREFIX = "leg_";
+function resolveApiKey(apiKey) {
+  let key = apiKey;
+  if (key === void 0) {
+    const envKey = process.env.LEGALIZE_API_KEY;
+    key = envKey || void 0;
+  }
+  if (!key) {
+    throw new AuthenticationError({
+      message: "Missing API key. Pass apiKey=... or set LEGALIZE_API_KEY.",
+      statusCode: 401,
+      code: "missing_api_key"
+    });
+  }
+  if (!key.startsWith(KEY_PREFIX)) {
+    throw new AuthenticationError({
+      message: `API key format unrecognized. Keys start with "${KEY_PREFIX}".`,
+      statusCode: 401,
+      code: "invalid_api_key"
+    });
+  }
+  return key;
+}
+function resolveBaseUrl(baseUrl) {
+  if (baseUrl !== void 0) {
+    return baseUrl;
+  }
+  const envUrl = process.env.LEGALIZE_BASE_URL;
+  if (envUrl && envUrl.length > 0) {
+    return envUrl;
+  }
+  return DEFAULT_BASE_URL;
+}
+function resolveApiVersion(apiVersion) {
+  if (apiVersion !== void 0) {
+    return apiVersion;
+  }
+  const envVer = process.env.LEGALIZE_API_VERSION;
+  if (envVer && envVer.length > 0) {
+    return envVer;
+  }
+  return DEFAULT_API_VERSION;
+}
+
+// src/resources/countries.ts
+var API = "/api/v1";
+var Countries = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /** Return every country the API serves, with law counts. */
+  async list(options = {}) {
+    return this.client.request("GET", `${API}/countries`, {
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+};
+
+// src/resources/jurisdictions.ts
+var API2 = "/api/v1";
+var Jurisdictions = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /** List jurisdictions for a country (e.g. Spain's comunidades). */
+  async list(country, options = {}) {
+    return this.client.request("GET", `${API2}/${country}/jurisdictions`, {
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+};
+
+// src/pagination.ts
+var PAGE_MAX = 100;
+var PageIterator = class {
+  fetchPage;
+  perPage;
+  limit;
+  page;
+  yielded;
+  buffer;
+  bufferIdx;
+  total;
+  shortPage;
+  constructor(fetchPage, options = {}) {
+    const perPage = options.perPage ?? PAGE_MAX;
+    if (perPage < 1 || perPage > PAGE_MAX) {
+      throw new RangeError(`perPage must be between 1 and ${PAGE_MAX}`);
+    }
+    if (options.limit !== void 0 && options.limit < 0) {
+      throw new RangeError("limit must be >= 0");
+    }
+    this.fetchPage = fetchPage;
+    this.perPage = perPage;
+    this.limit = options.limit;
+    this.page = options.startPage ?? 1;
+    this.yielded = 0;
+    this.buffer = [];
+    this.bufferIdx = 0;
+    this.total = 0;
+    this.shortPage = false;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  async next() {
+    while (true) {
+      if (this.limit !== void 0 && this.yielded >= this.limit) {
+        return { value: void 0, done: true };
+      }
+      if (this.bufferIdx < this.buffer.length) {
+        const item = this.buffer[this.bufferIdx];
+        this.bufferIdx += 1;
+        this.yielded += 1;
+        return { value: item, done: false };
+      }
+      if (this.yielded > 0 && this.yielded >= this.total) {
+        return { value: void 0, done: true };
+      }
+      if (this.shortPage) {
+        return { value: void 0, done: true };
+      }
+      const [items, total] = await this.fetchPage(this.page, this.perPage);
+      if (items.length === 0) {
+        return { value: void 0, done: true };
+      }
+      this.buffer = items;
+      this.bufferIdx = 0;
+      this.total = total;
+      this.shortPage = items.length < this.perPage;
+      this.page += 1;
+    }
+  }
+};
+var OffsetIterator = class {
+  fetchPage;
+  batch;
+  limit;
+  offset;
+  yielded;
+  buffer;
+  bufferIdx;
+  done;
+  constructor(fetchPage, options = {}) {
+    const batch = options.batch ?? 100;
+    if (batch < 1) {
+      throw new RangeError("batch must be >= 1");
+    }
+    if (options.limit !== void 0 && options.limit < 0) {
+      throw new RangeError("limit must be >= 0");
+    }
+    this.fetchPage = fetchPage;
+    this.batch = batch;
+    this.limit = options.limit;
+    this.offset = options.startOffset ?? 0;
+    this.yielded = 0;
+    this.buffer = [];
+    this.bufferIdx = 0;
+    this.done = false;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  async next() {
+    while (true) {
+      if (this.limit !== void 0 && this.yielded >= this.limit) {
+        return { value: void 0, done: true };
+      }
+      if (this.bufferIdx < this.buffer.length) {
+        const item = this.buffer[this.bufferIdx];
+        this.bufferIdx += 1;
+        this.yielded += 1;
+        return { value: item, done: false };
+      }
+      if (this.done) return { value: void 0, done: true };
+      const [items, total] = await this.fetchPage(this.batch, this.offset);
+      if (items.length === 0) {
+        this.done = true;
+        return { value: void 0, done: true };
+      }
+      this.buffer = items;
+      this.bufferIdx = 0;
+      this.offset += items.length;
+      if (this.offset >= total) this.done = true;
+      else if (items.length < this.batch) this.done = true;
+    }
+  }
+};
+
+// src/resources/laws.ts
+var API3 = "/api/v1";
+function buildFilterParams(opts, extras) {
+  return {
+    law_type: opts.lawType,
+    year: opts.year,
+    status: opts.status,
+    jurisdiction: opts.jurisdiction,
+    from_date: opts.fromDate,
+    to_date: opts.toDate,
+    sort: opts.sort,
+    ...extras
+  };
+}
+var Laws = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /** Return a single page of laws for a country. */
+  async list(country, options = {}) {
+    const params = buildFilterParams(options, {
+      page: options.page ?? 1,
+      per_page: options.perPage ?? 50
+    });
+    return this.client.request("GET", `${API3}/${country}/laws`, {
+      params,
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+  /** Full-text search for laws. `q` is required. */
+  async search(country, q, options = {}) {
+    if (!q || !q.trim()) {
+      throw new TypeError("q must be a non-empty search query");
+    }
+    const params = buildFilterParams(options, {
+      page: options.page ?? 1,
+      per_page: options.perPage ?? 50,
+      q
+    });
+    return this.client.request("GET", `${API3}/${country}/laws`, {
+      params,
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+  /** Auto-paginate across every matching law. */
+  iter(country, options = {}) {
+    const perPage = options.perPage ?? 100;
+    const limit = options.limit;
+    const fetchPage = async (page, per) => {
+      const listOpts = {
+        page,
+        perPage: per,
+        lawType: options.lawType,
+        year: options.year,
+        status: options.status,
+        jurisdiction: options.jurisdiction,
+        fromDate: options.fromDate,
+        toDate: options.toDate,
+        sort: options.sort
+      };
+      if (options.signal) listOpts.signal = options.signal;
+      const resp = await this.list(country, listOpts);
+      return [resp.results, resp.total];
+    };
+    return new PageIterator(fetchPage, { perPage, ...limit !== void 0 ? { limit } : {} });
+  }
+  /** Auto-paginate across every match of a full-text search. */
+  searchIter(country, q, options = {}) {
+    if (!q || !q.trim()) {
+      throw new TypeError("q must be a non-empty search query");
+    }
+    const perPage = options.perPage ?? 100;
+    const limit = options.limit;
+    const fetchPage = async (page, per) => {
+      const searchOpts = {
+        page,
+        perPage: per,
+        lawType: options.lawType,
+        year: options.year,
+        status: options.status,
+        jurisdiction: options.jurisdiction,
+        fromDate: options.fromDate,
+        toDate: options.toDate,
+        sort: options.sort
+      };
+      if (options.signal) searchOpts.signal = options.signal;
+      const resp = await this.search(country, q, searchOpts);
+      return [resp.results, resp.total];
+    };
+    return new PageIterator(fetchPage, { perPage, ...limit !== void 0 ? { limit } : {} });
+  }
+  /** Fetch the full law including Markdown content. */
+  async retrieve(country, lawId, options = {}) {
+    return this.client.request("GET", `${API3}/${country}/laws/${lawId}`, {
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+  /** Fetch only the law metadata (no content). */
+  async meta(country, lawId, options = {}) {
+    return this.client.request("GET", `${API3}/${country}/laws/${lawId}/meta`, {
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+  /** Git commit history for the law. */
+  async commits(country, lawId, options = {}) {
+    return this.client.request(
+      "GET",
+      `${API3}/${country}/laws/${lawId}/commits`,
+      { ...options.signal ? { signal: options.signal } : {} }
+    );
+  }
+  /** Return the law's full text at a specific historical version. */
+  async atCommit(country, lawId, sha, options = {}) {
+    return this.client.request(
+      "GET",
+      `${API3}/${country}/laws/${lawId}/at/${sha}`,
+      { ...options.signal ? { signal: options.signal } : {} }
+    );
+  }
+};
+
+// src/resources/lawTypes.ts
+var API4 = "/api/v1";
+var LawTypes = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /** List law type identifiers (e.g. `["constitucion", "ley", "real_decreto"]`). */
+  async list(country, options = {}) {
+    return this.client.request("GET", `${API4}/${country}/law-types`, {
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+};
+
+// src/resources/reforms.ts
+var API5 = "/api/v1";
+var Reforms = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /** Return a single page of reforms for a law. */
+  async list(country, lawId, options = {}) {
+    const params = {
+      limit: options.limit ?? 100,
+      offset: options.offset ?? 0
+    };
+    return this.client.request(
+      "GET",
+      `${API5}/${country}/laws/${lawId}/reforms`,
+      { params, ...options.signal ? { signal: options.signal } : {} }
+    );
+  }
+  /** Auto-paginate across every reform for a law. */
+  iter(country, lawId, options = {}) {
+    const batch = options.batch ?? 100;
+    const limit = options.limit;
+    const fetchPage = async (limitArg, offset) => {
+      const listOpts = {
+        limit: limitArg,
+        offset
+      };
+      if (options.signal) listOpts.signal = options.signal;
+      const resp = await this.list(country, lawId, listOpts);
+      return [resp.reforms, resp.total];
+    };
+    return new OffsetIterator(fetchPage, { batch, ...limit !== void 0 ? { limit } : {} });
+  }
+};
+
+// src/resources/stats.ts
+var API6 = "/api/v1";
+var Stats = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /** Return aggregate stats for a country (and optionally a jurisdiction). */
+  async retrieve(country, options = {}) {
+    const params = { jurisdiction: options.jurisdiction };
+    return this.client.request("GET", `${API6}/${country}/stats`, {
+      params,
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+};
+
+// src/resources/webhooks.ts
+var API7 = "/api/v1";
+var VALID_STATUSES = /* @__PURE__ */ new Set(["failed", "success", "pending"]);
+var Webhooks = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /** Create a webhook endpoint. Returns the signing secret ONCE. */
+  async create(options) {
+    const body = {
+      url: options.url,
+      event_types: options.eventTypes,
+      countries: options.countries ?? null,
+      description: options.description ?? ""
+    };
+    return this.client.request("POST", `${API7}/webhooks`, {
+      json: body,
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+  /** List all webhook endpoints for the authenticated org. */
+  async list(options = {}) {
+    return this.client.request("GET", `${API7}/webhooks`, {
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+  /** Fetch a single endpoint by id. */
+  async retrieve(endpointId, options = {}) {
+    return this.client.request("GET", `${API7}/webhooks/${endpointId}`, {
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+  /** Patch mutable fields on a webhook endpoint. */
+  async update(endpointId, options) {
+    const body = {};
+    if (options.url !== void 0) body.url = options.url;
+    if (options.eventTypes !== void 0) body.event_types = options.eventTypes;
+    if (options.countries !== void 0) body.countries = options.countries;
+    if (options.description !== void 0) body.description = options.description;
+    if (options.enabled !== void 0) body.enabled = options.enabled;
+    return this.client.request("PATCH", `${API7}/webhooks/${endpointId}`, {
+      json: body,
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  }
+  /** Delete a webhook endpoint. */
+  async delete(endpointId, options = {}) {
+    return this.client.request(
+      "DELETE",
+      `${API7}/webhooks/${endpointId}`,
+      { ...options.signal ? { signal: options.signal } : {} }
+    );
+  }
+  /** List delivery attempts for an endpoint, optionally filtered by status. */
+  async deliveries(endpointId, options = {}) {
+    if (options.status !== void 0 && !VALID_STATUSES.has(options.status)) {
+      throw new TypeError(
+        "status must be 'failed', 'success', 'pending', or omitted"
+      );
+    }
+    const params = {
+      page: options.page ?? 1,
+      status: options.status
+    };
+    return this.client.request(
+      "GET",
+      `${API7}/webhooks/${endpointId}/deliveries`,
+      { params, ...options.signal ? { signal: options.signal } : {} }
+    );
+  }
+  /** Retry a failed delivery. */
+  async retry(endpointId, deliveryId, options = {}) {
+    return this.client.request(
+      "POST",
+      `${API7}/webhooks/${endpointId}/deliveries/${deliveryId}/retry`,
+      { ...options.signal ? { signal: options.signal } : {} }
+    );
+  }
+  /** Send a `test.ping` event to verify the endpoint is reachable. */
+  async test(endpointId, options = {}) {
+    return this.client.request(
+      "POST",
+      `${API7}/webhooks/${endpointId}/test`,
+      { ...options.signal ? { signal: options.signal } : {} }
+    );
+  }
+};
+
+// src/version.ts
+var SDK_VERSION = "0.1.0";
+
+// src/client.ts
+function defaultUserAgent() {
+  return `legalize-node/${SDK_VERSION} node/${process.version} ${os.platform()}`;
+}
+function stripTrailingSlashes(s) {
+  let end = s.length;
+  while (end > 0 && s.charCodeAt(end - 1) === 47) end--;
+  return s.slice(0, end);
+}
+var Legalize = class {
+  countries;
+  jurisdictions;
+  lawTypes;
+  laws;
+  reforms;
+  stats;
+  webhooks;
+  /** Exposed for tests; treat as private otherwise. */
+  _apiKey;
+  _baseUrl;
+  _apiVersion;
+  _headers;
+  _timeout;
+  _retry;
+  _fetch;
+  _lastResponse = null;
+  constructor(options = {}) {
+    this._apiKey = resolveApiKey(options.apiKey);
+    this._baseUrl = stripTrailingSlashes(resolveBaseUrl(options.baseUrl));
+    this._apiVersion = resolveApiVersion(options.apiVersion);
+    this._timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this._retry = resolveRetryPolicy(options.retry, options.maxRetries);
+    this._fetch = options.fetch ?? globalThis.fetch;
+    this._headers = buildHeaders(this._apiKey, this._apiVersion, options.defaultHeaders);
+    this.countries = new Countries(this);
+    this.jurisdictions = new Jurisdictions(this);
+    this.lawTypes = new LawTypes(this);
+    this.laws = new Laws(this);
+    this.reforms = new Reforms(this);
+    this.stats = new Stats(this);
+    this.webhooks = new Webhooks(this);
+  }
+  /** The raw HTTP response from the most recent request, or null. */
+  get lastResponse() {
+    return this._lastResponse;
+  }
+  /**
+   * Execute a request and return the parsed JSON body (or null for 204).
+   *
+   * Throws an APIError subclass on non-2xx responses (after retries),
+   * APITimeoutError on timeout, or APIConnectionError on transport
+   * failure.
+   */
+  async request(method, path, options = {}) {
+    const upperMethod = method.toUpperCase();
+    const url = this.buildUrl(path, options.params);
+    const headers = { ...this._headers };
+    if (options.extraHeaders) Object.assign(headers, options.extraHeaders);
+    if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+    const hasJson = options.json !== void 0;
+    if (hasJson) headers["Content-Type"] = "application/json";
+    let attempt = 0;
+    while (true) {
+      let response;
+      try {
+        response = await this.sendOnce(url, upperMethod, headers, options, hasJson);
+      } catch (err) {
+        const shouldRetry2 = this._retry.shouldRetry(attempt, { method: upperMethod });
+        if (!shouldRetry2) {
+          throw wrapTransportError(err);
+        }
+        const delay2 = this._retry.computeDelay(attempt, {});
+        await sleep(delay2);
+        attempt += 1;
+        continue;
+      }
+      if (response.status >= 200 && response.status < 300) {
+        this._lastResponse = response;
+        if (response.status === 204) return null;
+        const text = await response.text();
+        if (!text) return null;
+        try {
+          return JSON.parse(text);
+        } catch (err) {
+          throw new APIError({
+            message: "Server returned non-JSON body",
+            statusCode: response.status,
+            body: text,
+            response,
+            cause: err
+          });
+        }
+      }
+      const shouldRetry = this._retry.shouldRetry(attempt, {
+        status: response.status,
+        method: upperMethod
+      });
+      if (!shouldRetry) {
+        this._lastResponse = response;
+        throw await errorFromResponse(response);
+      }
+      const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+      const delay = this._retry.computeDelay(attempt, { retryAfter });
+      try {
+        await response.text();
+      } catch {
+      }
+      await sleep(delay);
+      attempt += 1;
+    }
+  }
+  /** Release any resources held by the client. Kept for API symmetry. */
+  async close() {
+  }
+  /** TS 5.2+ `using` / `await using` support. */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  // ---- internals --------------------------------------------------------
+  buildUrl(path, params) {
+    let base;
+    if (path.startsWith("http://") || path.startsWith("https://")) {
+      base = path;
+    } else {
+      const p = path.startsWith("/") ? path : `/${path}`;
+      base = this._baseUrl + p;
+    }
+    if (!params) return base;
+    const query = buildQueryString(params);
+    if (!query) return base;
+    return base.includes("?") ? `${base}&${query}` : `${base}?${query}`;
+  }
+  async sendOnce(url, method, headers, options, hasJson) {
+    const controller = new AbortController();
+    const timeoutMs = this._timeout;
+    const timeoutHandle = setTimeout(() => controller.abort(new TimeoutSignal()), timeoutMs);
+    let externalListener;
+    if (options.signal) {
+      if (options.signal.aborted) controller.abort(options.signal.reason);
+      externalListener = () => controller.abort(options.signal.reason);
+      options.signal.addEventListener("abort", externalListener, { once: true });
+    }
+    try {
+      const init = {
+        method,
+        headers,
+        signal: controller.signal,
+        redirect: "manual"
+      };
+      if (hasJson) init.body = JSON.stringify(options.json);
+      return await this._fetch(url, init);
+    } finally {
+      clearTimeout(timeoutHandle);
+      if (options.signal && externalListener) {
+        options.signal.removeEventListener("abort", externalListener);
+      }
+    }
+  }
+};
+var TimeoutSignal = class extends Error {
+  name = "TimeoutSignal";
+  constructor() {
+    super("request timed out");
+  }
+};
+function resolveRetryPolicy(policy, maxRetries) {
+  if (policy !== void 0) return policy;
+  if (maxRetries === void 0) return new RetryPolicy();
+  return new RetryPolicy({ maxRetries });
+}
+function buildHeaders(apiKey, apiVersion, extra) {
+  const headers = {
+    Authorization: `Bearer ${apiKey}`,
+    "User-Agent": defaultUserAgent(),
+    "Legalize-API-Version": apiVersion,
+    Accept: "application/json"
+  };
+  if (extra) Object.assign(headers, extra);
+  return headers;
+}
+function buildQueryString(params) {
+  const parts = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    let serialized;
+    if (typeof value === "boolean") {
+      serialized = value ? "true" : "false";
+    } else if (Array.isArray(value)) {
+      if (value.length === 0) continue;
+      serialized = value.map((v) => String(v)).join(",");
+    } else {
+      serialized = String(value);
+    }
+    parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(serialized)}`);
+  }
+  return parts.join("&");
+}
+async function errorFromResponse(response) {
+  const text = await response.text();
+  let data = void 0;
+  if (text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = void 0;
+    }
+  }
+  return APIError.fromResponse(response, text, data);
+}
+function wrapTransportError(err) {
+  if (err instanceof Error) {
+    const isAbort = err.name === "AbortError" || err.code === "ABORT_ERR";
+    const causeName = err.cause?.name;
+    const isTimeout = isAbort && (err.message.includes("timed out") || err.message.toLowerCase().includes("timeout") || causeName === "TimeoutSignal");
+    if (isTimeout) {
+      return new APITimeoutError("request timed out", { cause: err });
+    }
+    if (isAbort) {
+      return new APIConnectionError("request aborted", { cause: err });
+    }
+    return new APIConnectionError(err.message || "transport error", { cause: err });
+  }
+  return new APIConnectionError("transport error");
+}
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var SUPPORTED_SCHEMES = ["v1"];
+var Webhook = class _Webhook {
+  /** Default anti-replay tolerance. */
+  static TOLERANCE = DEFAULT_TOLERANCE_SECONDS;
+  /** Compute the canonical `v1=<hex>` signature for (payload, timestamp). */
+  static computeSignature(secret, payload, timestamp) {
+    const payloadBuf = normalizePayload(payload);
+    const signed = Buffer.concat([
+      Buffer.from(timestamp, "utf8"),
+      Buffer.from(".", "utf8"),
+      payloadBuf
+    ]);
+    const sig = createHmac("sha256", secret).update(signed).digest("hex");
+    return `v1=${sig}`;
+  }
+  /**
+   * Verify a webhook delivery and return the parsed event.
+   *
+   * Signature verification happens BEFORE JSON parsing, to protect the
+   * process from resource-exhaustion on unauthenticated bodies.
+   *
+   * Throws WebhookVerificationError on any failure. The `.reason`
+   * field identifies which check tripped for server-side logging,
+   * while the user-facing message stays generic.
+   */
+  static verify(options) {
+    if (!options.sigHeader || !options.timestamp || !options.secret) {
+      throw new WebhookVerificationError("missing_header");
+    }
+    const payloadBuf = normalizePayload(options.payload);
+    if (!/^-?\d+$/.test(options.timestamp.trim())) {
+      throw new WebhookVerificationError("bad_timestamp");
+    }
+    const ts = parseInt(options.timestamp.trim(), 10);
+    if (Number.isNaN(ts)) {
+      throw new WebhookVerificationError("bad_timestamp");
+    }
+    const tol = options.tolerance ?? _Webhook.TOLERANCE;
+    const reference = options.now ?? Date.now() / 1e3;
+    if (Math.abs(reference - ts) > tol) {
+      throw new WebhookVerificationError("timestamp_outside_tolerance");
+    }
+    const expected = _Webhook.computeSignature(options.secret, payloadBuf, options.timestamp);
+    const expectedHex = expected.slice(expected.indexOf("=") + 1);
+    const candidates = extractSchemeHexes(options.sigHeader);
+    if (candidates.length === 0) {
+      throw new WebhookVerificationError("no_valid_signature");
+    }
+    let match = false;
+    const expectedBuf = Buffer.from(expectedHex, "hex");
+    for (const candidate of candidates) {
+      let candBuf;
+      try {
+        candBuf = Buffer.from(candidate, "hex");
+      } catch {
+        continue;
+      }
+      if (candBuf.length !== expectedBuf.length) continue;
+      if (timingSafeEqual(expectedBuf, candBuf)) {
+        match = true;
+        break;
+      }
+    }
+    if (!match) {
+      throw new WebhookVerificationError("bad_signature");
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(payloadBuf.toString("utf8"));
+    } catch {
+      throw new WebhookVerificationError("bad_signature");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new WebhookVerificationError("bad_signature");
+    }
+    return webhookEventFromPayload(parsed);
+  }
+};
+function normalizePayload(payload) {
+  if (Buffer.isBuffer(payload)) return payload;
+  if (typeof payload === "string") return Buffer.from(payload, "utf8");
+  return Buffer.from(payload);
+}
+function extractSchemeHexes(header) {
+  const out = [];
+  for (const rawPart of header.split(",")) {
+    const part = rawPart.trim();
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const scheme = part.slice(0, eq);
+    const value = part.slice(eq + 1).trim();
+    if (!value) continue;
+    if (!SUPPORTED_SCHEMES.includes(scheme)) continue;
+    if (!/^[0-9a-fA-F]+$/.test(value)) continue;
+    out.push(value);
+  }
+  return out;
+}
+function webhookEventFromPayload(payload) {
+  const eventType = payload.event_type ?? payload.type ?? "";
+  return {
+    id: String(payload.id ?? ""),
+    type: String(eventType),
+    createdAt: String(payload.created_at ?? ""),
+    data: payload.data && typeof payload.data === "object" && !Array.isArray(payload.data) ? { ...payload.data } : {},
+    raw: { ...payload }
+  };
+}
+
+export { APIConnectionError, APIError, APITimeoutError, AuthenticationError, Countries, DEFAULT_API_VERSION, DEFAULT_BACKOFF_FACTOR, DEFAULT_BASE_URL, DEFAULT_INITIAL_DELAY, DEFAULT_MAX_DELAY, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, DEFAULT_TOLERANCE_SECONDS, ForbiddenError, IDEMPOTENT_METHODS, InvalidRequestError, Jurisdictions, KEY_PREFIX, LawTypes, Laws, Legalize, LegalizeError, NotFoundError, OffsetIterator, PAGE_MAX, PageIterator, RETRY_STATUSES, RateLimitError, Reforms, RetryPolicy, SDK_VERSION, ServerError, ServiceUnavailableError, Stats, ValidationError, Webhook, WebhookVerificationError, Webhooks, buildQueryString, defaultUserAgent, parseRetryAfter, resolveApiKey, resolveApiVersion, resolveBaseUrl, sleep };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map