@legalize-dev/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1012 @@
+/**
+ * Environment-variable resolution helpers.
+ *
+ * Contract: see `sdk/ENVIRONMENT.md`. Summary:
+ *   - `LEGALIZE_API_KEY` — required (unless `apiKey` passed explicitly).
+ *   - `LEGALIZE_BASE_URL` — default "https://legalize.dev".
+ *   - `LEGALIZE_API_VERSION` — default "v1".
+ *
+ * Precedence: explicit arg > env var > default. Empty string = unset.
+ * Prefix `LEGALIZE_` is mandatory; no aliases.
+ */
+declare const DEFAULT_BASE_URL = "https://legalize.dev";
+declare const DEFAULT_API_VERSION = "v1";
+declare const DEFAULT_TIMEOUT = 30000;
+declare const KEY_PREFIX = "leg_";
+/**
+ * Resolve the API key from the explicit argument or the environment.
+ *
+ * Raises AuthenticationError synchronously if no key is available or the
+ * key prefix is unrecognized. Catching obviously-bad inputs before the
+ * first network call saves operators from debugging 401s later.
+ */
+declare function resolveApiKey(apiKey: string | undefined): string;
+/**
+ * Resolve the base URL from the explicit argument, env, or default.
+ * Empty strings are treated as unset.
+ */
+declare function resolveBaseUrl(baseUrl: string | undefined): string;
+/**
+ * Resolve the API version from the explicit argument, env, or default.
+ * Empty strings are treated as unset.
+ */
+declare function resolveApiVersion(apiVersion: string | undefined): string;
+
+/**
+ * Retry policy for transient failures.
+ *
+ * Retries happen on:
+ *   - Network errors (DNS, connect, read timeout, TLS)
+ *   - HTTP 429 (rate limit)
+ *   - HTTP 500, 502, 503, 504 (transient server issues)
+ *
+ * Retries do NOT happen on:
+ *   - 4xx other than 429 (caller error, retrying won't help)
+ *   - Non-idempotent methods by default (POST, PATCH): mutations are
+ *     never auto-retried. Only GET/HEAD/OPTIONS/PUT/DELETE are retried.
+ *     This prevents duplicate webhook creation and duplicate retry calls.
+ *
+ * The `Retry-After` header wins when present and non-negative. Otherwise
+ * exponential backoff with full jitter, capped at `maxDelay`.
+ */
+declare const DEFAULT_MAX_RETRIES = 3;
+declare const DEFAULT_INITIAL_DELAY = 0.5;
+declare const DEFAULT_MAX_DELAY = 30;
+declare const DEFAULT_BACKOFF_FACTOR = 2;
+declare const RETRY_STATUSES: ReadonlySet<number>;
+/** HTTP methods considered safe to auto-retry (idempotent). */
+declare const IDEMPOTENT_METHODS: ReadonlySet<string>;
+interface RetryPolicyOptions {
+    maxRetries?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    backoffFactor?: number;
+    /**
+     * When true, retry POST/PATCH too. Default false — the SDK never
+     * auto-retries mutations unless the caller opts in explicitly.
+     */
+    retryNonIdempotent?: boolean;
+}
+/**
+ * Configuration for automatic retries.
+ *
+ * Immutable — construct a new instance to tweak. Matches the Python
+ * `RetryPolicy` contract:
+ *   - `maxRetries`: total attempts is at most `maxRetries + 1`. 0 disables retries.
+ *   - `initialDelay`: seconds before the first retry (pre-jitter).
+ *   - `maxDelay`: cap on any single sleep in seconds.
+ *   - `backoffFactor`: multiplier applied to delay each attempt.
+ */
+declare class RetryPolicy {
+    readonly maxRetries: number;
+    readonly initialDelay: number;
+    readonly maxDelay: number;
+    readonly backoffFactor: number;
+    readonly retryNonIdempotent: boolean;
+    constructor(options?: RetryPolicyOptions);
+    /**
+     * 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: number, options: {
+        status?: number;
+        method?: string;
+    }): boolean;
+    /**
+     * 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: number, options: {
+        retryAfter?: number;
+    }): number;
+}
+/**
+ * Parse the `Retry-After` header into seconds.
+ *
+ * RFC 9110 allows two forms:
+ *   - A non-negative integer (delta-seconds): `Retry-After: 120`
+ *   - An HTTP-date: `Retry-After: Wed, 21 Oct 2025 07:28:00 GMT`
+ *
+ * Unparseable input returns `undefined` so the caller can fall back to
+ * its own backoff. HTTP-date values in the past clamp to `0`.
+ */
+declare function parseRetryAfter(header: string | null | undefined): number | undefined;
+/** Promise-based sleep — used by the client's retry loop. */
+declare function sleep(seconds: number): Promise<void>;
+
+interface components {
+    schemas: {
+        /** Commit */
+        Commit: {
+            /** Date */
+            date: string;
+            /** Message */
+            message: string;
+            /** Sha */
+            sha: string;
+        };
+        /** CommitsResponse */
+        CommitsResponse: {
+            /** Commits */
+            commits: components["schemas"]["Commit"][];
+            /** Law Id */
+            law_id: string;
+        };
+        /** CountryInfo */
+        CountryInfo: {
+            /** Count */
+            count: number;
+            /** Country */
+            country: string;
+        };
+        /** HTTPValidationError */
+        HTTPValidationError: {
+            /** Detail */
+            detail?: components["schemas"]["ValidationError"][];
+        };
+        /** JurisdictionInfo */
+        JurisdictionInfo: {
+            /** Count */
+            count: number;
+            /** Jurisdiction */
+            jurisdiction?: string | null;
+        };
+        /** LawAtCommitResponse */
+        LawAtCommitResponse: {
+            /** Content Md */
+            content_md: string;
+            /** Law Id */
+            law_id: string;
+            /** Sha */
+            sha: string;
+        };
+        /**
+         * LawDetail
+         * @description Full law with Markdown content (fetched from GitHub).
+         */
+        LawDetail: {
+            /** Article Count */
+            article_count?: number | null;
+            /** Content Md */
+            content_md?: string | null;
+            /** Country */
+            country: string;
+            /** Department */
+            department?: string | null;
+            /** Extra */
+            extra?: {
+                [key: string]: unknown;
+            } | null;
+            /** Frontmatter */
+            frontmatter?: {
+                [key: string]: unknown;
+            } | null;
+            /** Id */
+            id: string;
+            /** Jurisdiction */
+            jurisdiction?: string | null;
+            /** Last Updated */
+            last_updated?: string | null;
+            /** Law Type */
+            law_type: string;
+            /** Publication Date */
+            publication_date?: string | null;
+            /** Short Title */
+            short_title?: string | null;
+            /** Source */
+            source?: string | null;
+            /** Status */
+            status?: string | null;
+            /** Title */
+            title: string;
+        };
+        /**
+         * LawMeta
+         * @description Law metadata without content. Lightweight — no GitHub fetch.
+         */
+        LawMeta: {
+            /** Article Count */
+            article_count?: number | null;
+            /** Country */
+            country: string;
+            /** Department */
+            department?: string | null;
+            /** Extra */
+            extra?: {
+                [key: string]: unknown;
+            } | null;
+            /** Id */
+            id: string;
+            /** Jurisdiction */
+            jurisdiction?: string | null;
+            /** Last Updated */
+            last_updated?: string | null;
+            /** Law Type */
+            law_type: string;
+            /** Publication Date */
+            publication_date?: string | null;
+            /** Short Title */
+            short_title?: string | null;
+            /** Source */
+            source?: string | null;
+            /** Status */
+            status?: string | null;
+            /** Title */
+            title: string;
+        };
+        /**
+         * LawSearchResult
+         * @description Law result with search snippet.
+         */
+        LawSearchResult: {
+            /** Article Count */
+            article_count?: number | null;
+            /** Country */
+            country: string;
+            /** Id */
+            id: string;
+            /** Jurisdiction */
+            jurisdiction?: string | null;
+            /** Law Type */
+            law_type: string;
+            /** Publication Date */
+            publication_date?: string | null;
+            /** Short Title */
+            short_title?: string | null;
+            /** Status */
+            status?: string | null;
+            /** Title */
+            title: string;
+            /** Title Snippet */
+            title_snippet?: string | null;
+        };
+        /**
+         * PaginatedLaws
+         * @description Unified response for law listing and search.
+         *
+         *     When searching (query is not None), both ``total`` and ``count``
+         *     are populated with the same value for backward compatibility.
+         *     When listing, ``query`` and ``count`` are None.
+         */
+        PaginatedLaws: {
+            /** Count */
+            count?: number | null;
+            /** Country */
+            country: string;
+            /** From Date */
+            from_date?: string | null;
+            /** Jurisdiction */
+            jurisdiction?: string | null;
+            /** Page */
+            page: number;
+            /** Per Page */
+            per_page: number;
+            /** Query */
+            query?: string | null;
+            /** Results */
+            results: components["schemas"]["LawSearchResult"][];
+            /** Sort */
+            sort?: string | null;
+            /** To Date */
+            to_date?: string | null;
+            /** Total */
+            total: number;
+        };
+        /** Reform */
+        Reform: {
+            /** Articles Affected */
+            articles_affected?: string | null;
+            /** Date */
+            date: string;
+            /** Source Id */
+            source_id?: string | null;
+        };
+        /** ReformsResponse */
+        ReformsResponse: {
+            /** Law Id */
+            law_id: string;
+            /** Limit */
+            limit: number;
+            /** Offset */
+            offset: number;
+            /** Reforms */
+            reforms: components["schemas"]["Reform"][];
+            /** Total */
+            total: number;
+        };
+        /** StatsResponse */
+        StatsResponse: {
+            /** Country */
+            country: string;
+            /** Jurisdiction */
+            jurisdiction?: string | null;
+            /** Law Types */
+            law_types: string[];
+            /** Most Reformed Laws */
+            most_reformed_laws: {
+                [key: string]: unknown;
+            }[];
+            /** Reform Activity By Year */
+            reform_activity_by_year: {
+                [key: string]: unknown;
+            }[];
+        };
+        /** ValidationError */
+        ValidationError: {
+            /** Context */
+            ctx?: Record<string, never>;
+            /** Input */
+            input?: unknown;
+            /** Location */
+            loc: (string | number)[];
+            /** Message */
+            msg: string;
+            /** Error Type */
+            type: string;
+        };
+        /** WebhookEndpointCreate */
+        WebhookEndpointCreate: {
+            /** Countries */
+            countries?: string[] | null;
+            /**
+             * Description
+             * @default
+             */
+            description: string;
+            /** Event Types */
+            event_types: string[];
+            /** Url */
+            url: string;
+        };
+        /** WebhookEndpointUpdate */
+        WebhookEndpointUpdate: {
+            /** Countries */
+            countries?: string[] | null;
+            /** Description */
+            description?: string | null;
+            /** Enabled */
+            enabled?: boolean | null;
+            /** Event Types */
+            event_types?: string[] | null;
+            /** Url */
+            url?: string | null;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+/**
+ * Public response and request types.
+ *
+ * The underlying schemas live in `generated.ts` (produced by
+ * `openapi-typescript` from `../openapi-sdk.json`). This file re-exports
+ * the curated subset the SDK user interacts with, plus a few hand-written
+ * helper types where OpenAPI generation is awkward.
+ *
+ * We preserve the server's `snake_case` field names on response objects
+ * to match the wire format byte-for-byte — same philosophy as the Python
+ * SDK, which keeps Pydantic aliases and populates fields from the raw
+ * JSON directly.
+ */
+
+type CountryInfo = components["schemas"]["CountryInfo"];
+type JurisdictionInfo = components["schemas"]["JurisdictionInfo"];
+type Commit = components["schemas"]["Commit"];
+type CommitsResponse = components["schemas"]["CommitsResponse"];
+type LawAtCommitResponse = components["schemas"]["LawAtCommitResponse"];
+type LawDetail = components["schemas"]["LawDetail"];
+type LawMeta = components["schemas"]["LawMeta"];
+type LawSearchResult = components["schemas"]["LawSearchResult"];
+type PaginatedLaws = components["schemas"]["PaginatedLaws"];
+type Reform = components["schemas"]["Reform"];
+type ReformsResponse = components["schemas"]["ReformsResponse"];
+type StatsResponse = components["schemas"]["StatsResponse"];
+type ApiValidationError = components["schemas"]["ValidationError"];
+type HTTPValidationError = components["schemas"]["HTTPValidationError"];
+type WebhookEndpointCreate = components["schemas"]["WebhookEndpointCreate"];
+type WebhookEndpointUpdate = components["schemas"]["WebhookEndpointUpdate"];
+/**
+ * Law listing sort options.
+ *
+ * The OpenAPI schema types this as `string` but the server enforces a
+ * specific allowed set. We keep it open (`string`) to tolerate server
+ * additions without bumping the SDK, but document the current values.
+ */
+type LawSort = "publication_date" | "-publication_date" | "last_updated" | "-last_updated" | "title" | "-title" | (string & {});
+/** Options shared by `laws.list` and `laws.iter` filter surfaces. */
+interface LawFilterOptions {
+    lawType?: string | string[];
+    year?: number;
+    status?: string;
+    jurisdiction?: string;
+    fromDate?: string;
+    toDate?: string;
+    sort?: LawSort;
+}
+interface LawListOptions extends LawFilterOptions {
+    page?: number;
+    perPage?: number;
+}
+interface LawSearchOptions extends LawFilterOptions {
+    page?: number;
+    perPage?: number;
+}
+interface LawIterOptions extends LawFilterOptions {
+    perPage?: number;
+    limit?: number;
+}
+interface ReformListOptions {
+    limit?: number;
+    offset?: number;
+}
+interface ReformIterOptions {
+    batch?: number;
+    limit?: number;
+}
+interface StatsOptions {
+    jurisdiction?: string;
+}
+/** Webhook endpoint CRUD types — server-side response. */
+interface WebhookEndpoint {
+    id: number;
+    url: string;
+    event_types: string[];
+    countries?: string[] | null;
+    description?: string;
+    enabled?: boolean;
+    created_at?: string;
+    /** Only populated on creation, never on list/retrieve. */
+    secret?: string;
+    [key: string]: unknown;
+}
+interface WebhookDeliveriesPage {
+    total: number;
+    deliveries: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+interface WebhookDelivery {
+    id: number;
+    status: string;
+    [key: string]: unknown;
+}
+type WebhookDeliveryStatus = "failed" | "success" | "pending";
+interface WebhookCreateOptions {
+    url: string;
+    eventTypes: string[];
+    countries?: string[];
+    description?: string;
+}
+interface WebhookUpdateOptions {
+    url?: string;
+    eventTypes?: string[];
+    countries?: string[];
+    description?: string;
+    enabled?: boolean;
+}
+interface WebhookDeliveriesOptions {
+    page?: number;
+    status?: WebhookDeliveryStatus;
+}
+
+/** `/api/v1/countries` — list every country the API serves. */
+
+declare class Countries {
+    private readonly client;
+    constructor(client: Legalize);
+    /** Return every country the API serves, with law counts. */
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<CountryInfo[]>;
+}
+
+/** `/api/v1/{country}/jurisdictions` — regions/states within a country. */
+
+declare class Jurisdictions {
+    private readonly client;
+    constructor(client: Legalize);
+    /** List jurisdictions for a country (e.g. Spain's comunidades). */
+    list(country: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<JurisdictionInfo[]>;
+}
+
+/**
+ * `/api/v1/{country}/laws` and sub-resources.
+ *
+ * Covers:
+ *   - `list` / `search` — listing vs. full-text search
+ *   - `iter` / `searchIter` — auto-paginated async iterators
+ *   - `retrieve` — full law with Markdown content
+ *   - `meta` — metadata only (fast, no GitHub fetch)
+ *   - `commits` — git commit history
+ *   - `atCommit` — time-travel to a specific SHA
+ */
+
+declare class Laws {
+    private readonly client;
+    constructor(client: Legalize);
+    /** Return a single page of laws for a country. */
+    list(country: string, options?: LawListOptions & {
+        signal?: AbortSignal;
+    }): Promise<PaginatedLaws>;
+    /** Full-text search for laws. `q` is required. */
+    search(country: string, q: string, options?: LawSearchOptions & {
+        signal?: AbortSignal;
+    }): Promise<PaginatedLaws>;
+    /** Auto-paginate across every matching law. */
+    iter(country: string, options?: LawIterOptions & {
+        signal?: AbortSignal;
+    }): AsyncIterableIterator<LawSearchResult>;
+    /** Auto-paginate across every match of a full-text search. */
+    searchIter(country: string, q: string, options?: LawIterOptions & {
+        signal?: AbortSignal;
+    }): AsyncIterableIterator<LawSearchResult>;
+    /** Fetch the full law including Markdown content. */
+    retrieve(country: string, lawId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<LawDetail>;
+    /** Fetch only the law metadata (no content). */
+    meta(country: string, lawId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<LawMeta>;
+    /** Git commit history for the law. */
+    commits(country: string, lawId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<CommitsResponse>;
+    /** Return the law's full text at a specific historical version. */
+    atCommit(country: string, lawId: string, sha: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<LawAtCommitResponse>;
+}
+
+/** `/api/v1/{country}/law-types` — law types per country. */
+
+declare class LawTypes {
+    private readonly client;
+    constructor(client: Legalize);
+    /** List law type identifiers (e.g. `["constitucion", "ley", "real_decreto"]`). */
+    list(country: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<string[]>;
+}
+
+/** `/api/v1/{country}/laws/{law_id}/reforms` — reform history. */
+
+declare class Reforms {
+    private readonly client;
+    constructor(client: Legalize);
+    /** Return a single page of reforms for a law. */
+    list(country: string, lawId: string, options?: ReformListOptions & {
+        signal?: AbortSignal;
+    }): Promise<ReformsResponse>;
+    /** Auto-paginate across every reform for a law. */
+    iter(country: string, lawId: string, options?: ReformIterOptions & {
+        signal?: AbortSignal;
+    }): AsyncIterableIterator<Reform>;
+}
+
+/** `/api/v1/{country}/stats` — aggregate statistics for a country. */
+
+declare class Stats {
+    private readonly client;
+    constructor(client: Legalize);
+    /** Return aggregate stats for a country (and optionally a jurisdiction). */
+    retrieve(country: string, options?: StatsOptions & {
+        signal?: AbortSignal;
+    }): Promise<StatsResponse>;
+}
+
+/**
+ * `/api/v1/webhooks` — endpoint management + delivery history + test ping.
+ *
+ * The management endpoints (this file) require Pro+ tier. The webhook
+ * signature verification utility lives in `webhooks.ts` at the package
+ * root — it runs on the recipient's server and doesn't touch this API.
+ */
+
+declare class Webhooks {
+    private readonly client;
+    constructor(client: Legalize);
+    /** Create a webhook endpoint. Returns the signing secret ONCE. */
+    create(options: WebhookCreateOptions & {
+        signal?: AbortSignal;
+    }): Promise<WebhookEndpoint>;
+    /** List all webhook endpoints for the authenticated org. */
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<WebhookEndpoint[]>;
+    /** Fetch a single endpoint by id. */
+    retrieve(endpointId: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<WebhookEndpoint>;
+    /** Patch mutable fields on a webhook endpoint. */
+    update(endpointId: number, options: WebhookUpdateOptions & {
+        signal?: AbortSignal;
+    }): Promise<WebhookEndpoint>;
+    /** Delete a webhook endpoint. */
+    delete(endpointId: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<Record<string, unknown>>;
+    /** List delivery attempts for an endpoint, optionally filtered by status. */
+    deliveries(endpointId: number, options?: WebhookDeliveriesOptions & {
+        signal?: AbortSignal;
+    }): Promise<WebhookDeliveriesPage>;
+    /** Retry a failed delivery. */
+    retry(endpointId: number, deliveryId: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<WebhookDelivery>;
+    /** Send a `test.ping` event to verify the endpoint is reachable. */
+    test(endpointId: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<WebhookDelivery>;
+}
+
+/**
+ * HTTP client core — the `Legalize` class.
+ *
+ * Wraps the built-in `fetch` with:
+ *   - auth + identifying headers on every request
+ *   - query-param cleanup matching the Python reference
+ *   - retry policy with exponential backoff (see `retry.ts`)
+ *   - error hierarchy mapping (see `errors.ts`)
+ *   - per-request AbortSignal support
+ *   - `lastResponse` populated on success AND error, for inspecting
+ *     rate-limit headers and X-Request-Id after failures
+ *
+ * Design notes:
+ *   - No runtime deps. Node 20+ ships `fetch`, `AbortController`, and
+ *     `crypto.webcrypto` — we use only those.
+ *   - `follow_redirects` is effectively false: the server doesn't
+ *     redirect, and silently following one would hide misconfigurations.
+ *     `fetch` supports "manual" redirect mode so we use it.
+ */
+
+/** Compose the User-Agent the SDK sends with every request. */
+declare function defaultUserAgent(): string;
+/** The fetch implementation the client uses. Global by default; overridable. */
+type FetchImpl = typeof fetch;
+interface LegalizeOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    apiVersion?: string;
+    /** Timeout in milliseconds. Default 30000. */
+    timeout?: number;
+    maxRetries?: number;
+    retry?: RetryPolicy;
+    defaultHeaders?: Record<string, string>;
+    /** Override fetch — primarily for tests. */
+    fetch?: FetchImpl;
+}
+interface RequestOptions {
+    params?: Record<string, unknown>;
+    json?: unknown;
+    extraHeaders?: Record<string, string>;
+    signal?: AbortSignal;
+    /**
+     * Override the retry policy's idempotency check for this call.
+     * POST/PATCH are NOT retried by default.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Synchronous-API, promise-based client for the Legalize API.
+ *
+ * Example:
+ *
+ *   import { Legalize } from "@legalize-dev/sdk";
+ *
+ *   const client = new Legalize({ apiKey: "leg_..." });
+ *   const countries = await client.countries.list();
+ *
+ * Use `await using` (TS 5.2+) for deterministic cleanup:
+ *
+ *   await using client = new Legalize({ apiKey: "leg_..." });
+ */
+declare class Legalize {
+    readonly countries: Countries;
+    readonly jurisdictions: Jurisdictions;
+    readonly lawTypes: LawTypes;
+    readonly laws: Laws;
+    readonly reforms: Reforms;
+    readonly stats: Stats;
+    readonly webhooks: Webhooks;
+    /** Exposed for tests; treat as private otherwise. */
+    readonly _apiKey: string;
+    readonly _baseUrl: string;
+    readonly _apiVersion: string;
+    readonly _headers: Record<string, string>;
+    private readonly _timeout;
+    private readonly _retry;
+    private readonly _fetch;
+    private _lastResponse;
+    constructor(options?: LegalizeOptions);
+    /** The raw HTTP response from the most recent request, or null. */
+    get lastResponse(): Response | null;
+    /**
+     * 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.
+     */
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** Release any resources held by the client. Kept for API symmetry. */
+    close(): Promise<void>;
+    /** TS 5.2+ `using` / `await using` support. */
+    [Symbol.asyncDispose](): Promise<void>;
+    private buildUrl;
+    private sendOnce;
+}
+/**
+ * Serialize query params matching the Python reference:
+ *   - undefined/null → dropped.
+ *   - booleans → "true" / "false".
+ *   - arrays → comma-joined; empty arrays dropped.
+ *   - everything else → String(value).
+ */
+declare function buildQueryString(params: Record<string, unknown>): string;
+
+/**
+ * Error hierarchy for the Legalize SDK.
+ *
+ * The server returns three response shapes:
+ *
+ * 1. Structured dict from the API layer:
+ *    { "detail": { "error": "quota_exceeded", "message": "...", "retry_after": 3600, ... } }
+ *
+ * 2. FastAPI validation errors (422):
+ *    { "detail": [{ "loc": [...], "msg": "...", "type": "..." }, ...] }
+ *
+ * 3. Plain string detail for simple 404/400:
+ *    { "detail": "Law not found: xyz" }
+ *
+ * `APIError.fromResponse` normalizes all three into an instance of the
+ * most specific subclass, keeping the raw body on `.body` and the parsed
+ * payload on `.data`.
+ */
+/** Base error for everything the SDK raises. */
+declare class LegalizeError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+interface APIErrorOptions {
+    message: string;
+    statusCode?: number;
+    code?: string | undefined;
+    body?: unknown;
+    data?: unknown;
+    requestId?: string | undefined;
+    response?: Response | undefined;
+    cause?: unknown;
+}
+/** Any non-2xx HTTP response. */
+declare class APIError extends LegalizeError {
+    readonly name: string;
+    readonly statusCode: number | undefined;
+    readonly code: string | undefined;
+    readonly body: unknown;
+    readonly data: unknown;
+    readonly requestId: string | undefined;
+    readonly response: Response | undefined;
+    constructor(options: APIErrorOptions);
+    toString(): string;
+    /**
+     * 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: Response, body: unknown, data?: unknown): APIError;
+}
+declare class AuthenticationError extends APIError {
+    readonly name = "AuthenticationError";
+}
+declare class ForbiddenError extends APIError {
+    readonly name = "ForbiddenError";
+}
+declare class NotFoundError extends APIError {
+    readonly name = "NotFoundError";
+}
+declare class InvalidRequestError extends APIError {
+    readonly name = "InvalidRequestError";
+}
+declare class ValidationError extends APIError {
+    readonly name = "ValidationError";
+    readonly errors: Array<Record<string, unknown>>;
+}
+declare class RateLimitError extends APIError {
+    readonly name = "RateLimitError";
+    readonly retryAfter: number | undefined;
+    readonly limit: number | undefined;
+}
+declare class ServerError extends APIError {
+    readonly name: string;
+}
+declare class ServiceUnavailableError extends ServerError {
+    readonly name: string;
+}
+/** Transport failure, no response. */
+declare class APIConnectionError extends LegalizeError {
+    readonly name: string;
+}
+/** Request exceeded timeout. */
+declare class APITimeoutError extends APIConnectionError {
+    readonly name: string;
+}
+type WebhookVerificationReason = "missing_header" | "bad_timestamp" | "timestamp_outside_tolerance" | "no_valid_signature" | "bad_signature";
+/**
+ * Raised by Webhook.verify on any signature or timestamp failure.
+ *
+ * The message is intentionally generic so that an attacker probing the
+ * endpoint can't distinguish "bad signature" from "stale timestamp". The
+ * specific reason is available on `.reason` for server-side logging.
+ */
+declare class WebhookVerificationError extends LegalizeError {
+    readonly name: string;
+    readonly reason: WebhookVerificationReason;
+    constructor(reason: WebhookVerificationReason);
+}
+
+/**
+ * Pagination helpers — async iterators over page- and offset-based endpoints.
+ *
+ * The Legalize API uses two pagination styles:
+ *
+ *   - page + perPage  — laws list, webhook deliveries
+ *   - limit + offset  — reforms
+ *
+ * Each paginated response carries `total` (true match count). That lets
+ * iterators terminate without inferring end-of-stream.
+ *
+ * The iterators here are transport-agnostic: they delegate fetching to
+ * a caller-supplied async callback.
+ */
+declare const PAGE_MAX = 100;
+/** Async iterator over a page-based endpoint (page + perPage). */
+declare class PageIterator<T> implements AsyncIterableIterator<T> {
+    private readonly fetchPage;
+    private readonly perPage;
+    private readonly limit;
+    private page;
+    private yielded;
+    private buffer;
+    private bufferIdx;
+    private total;
+    private shortPage;
+    constructor(fetchPage: (page: number, perPage: number) => Promise<[T[], number]>, options?: {
+        perPage?: number;
+        limit?: number;
+        startPage?: number;
+    });
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    next(): Promise<IteratorResult<T>>;
+}
+/** Async iterator over a limit/offset-based endpoint (reforms). */
+declare class OffsetIterator<T> implements AsyncIterableIterator<T> {
+    private readonly fetchPage;
+    private readonly batch;
+    private readonly limit;
+    private offset;
+    private yielded;
+    private buffer;
+    private bufferIdx;
+    private done;
+    constructor(fetchPage: (limit: number, offset: number) => Promise<[T[], number]>, options?: {
+        batch?: number;
+        limit?: number;
+        startOffset?: number;
+    });
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    next(): Promise<IteratorResult<T>>;
+}
+
+/**
+ * Webhook signature verification.
+ *
+ * Mirrors the server-side signer in the Legalize web backend. The scheme
+ * is Stripe-shaped:
+ *
+ *   - Signed content: `${timestamp}.${rawJsonBody}` — RAW bytes, never
+ *     a re-serialized JSON string. Reserialization will break the signature.
+ *   - Algorithm: HMAC-SHA256, hex-encoded.
+ *   - Header format: `v1=<hex>`. A future v2 scheme can coexist:
+ *     `X-Legalize-Signature: v1=<sig1>,v2=<sig2>`.
+ *   - Replay protection: reject if the header timestamp is more than
+ *     `tolerance` seconds away from `now`. Default 300 seconds.
+ *
+ * Usage (Express):
+ *
+ *   import express from "express";
+ *   import { Webhook, WebhookVerificationError } from "@legalize-dev/sdk";
+ *
+ *   app.post("/webhooks/legalize",
+ *     express.raw({ type: "application/json" }),
+ *     (req, res) => {
+ *       try {
+ *         const event = Webhook.verify({
+ *           payload: req.body,  // Buffer
+ *           sigHeader: req.header("X-Legalize-Signature") ?? "",
+ *           timestamp: req.header("X-Legalize-Timestamp") ?? "",
+ *           secret: process.env.LEGALIZE_WHSEC!,
+ *         });
+ *         if (event.type === "law.updated") { ... }
+ *         res.status(204).send();
+ *       } catch (err) {
+ *         res.status(400).send();
+ *       }
+ *     });
+ */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+interface WebhookEvent {
+    /** Server-assigned event id (e.g. `evt_...`). */
+    readonly id: string;
+    /** Event type (`law.created`, `law.updated`, `law.repealed`, ...). */
+    readonly type: string;
+    /** Server-side timestamp (ISO-8601 string). */
+    readonly createdAt: string;
+    /** Event-specific payload body. */
+    readonly data: Record<string, unknown>;
+    /** The full decoded JSON body — useful for fields the SDK doesn't type. */
+    readonly raw: Record<string, unknown>;
+}
+interface WebhookVerifyOptions {
+    /** The raw request body bytes. Do NOT pass a re-serialized JSON string. */
+    payload: Buffer | Uint8Array | string;
+    /** The `X-Legalize-Signature` header value. May contain several `vN=<hex>` pairs. */
+    sigHeader: string;
+    /** The `X-Legalize-Timestamp` header value (Unix seconds, decimal string). */
+    timestamp: string;
+    /** The endpoint's signing secret. */
+    secret: string;
+    /** Seconds of clock skew accepted. Default 300. */
+    tolerance?: number;
+    /** Unit-test hook: override the reference wall clock (Unix seconds). */
+    now?: number;
+}
+declare class Webhook {
+    /** Default anti-replay tolerance. */
+    static readonly TOLERANCE = 300;
+    /** Compute the canonical `v1=<hex>` signature for (payload, timestamp). */
+    static computeSignature(secret: string, payload: Buffer | Uint8Array | string, timestamp: string): string;
+    /**
+     * 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: WebhookVerifyOptions): WebhookEvent;
+}
+
+/**
+ * SDK version — MUST be kept in sync with the "version" field in package.json.
+ *
+ * The Node runtime doesn't resolve JSON imports cleanly across ESM/CJS dual
+ * output without extra wiring, so we duplicate the literal here. The test
+ * suite asserts they match so drift is caught immediately.
+ */
+declare const SDK_VERSION = "0.1.0";
+
+export { APIConnectionError, APIError, type APIErrorOptions, APITimeoutError, type ApiValidationError, AuthenticationError, type Commit, type CommitsResponse, Countries, type CountryInfo, DEFAULT_API_VERSION, DEFAULT_BACKOFF_FACTOR, DEFAULT_BASE_URL, DEFAULT_INITIAL_DELAY, DEFAULT_MAX_DELAY, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, DEFAULT_TOLERANCE_SECONDS, type FetchImpl, ForbiddenError, type HTTPValidationError, IDEMPOTENT_METHODS, InvalidRequestError, type JurisdictionInfo, Jurisdictions, KEY_PREFIX, type LawAtCommitResponse, type LawDetail, type LawFilterOptions, type LawIterOptions, type LawListOptions, type LawMeta, type LawSearchOptions, type LawSearchResult, type LawSort, LawTypes, Laws, Legalize, LegalizeError, type LegalizeOptions, NotFoundError, OffsetIterator, PAGE_MAX, PageIterator, type PaginatedLaws, RETRY_STATUSES, RateLimitError, type Reform, type ReformIterOptions, type ReformListOptions, Reforms, type ReformsResponse, type RequestOptions, RetryPolicy, type RetryPolicyOptions, SDK_VERSION, ServerError, ServiceUnavailableError, Stats, type StatsOptions, type StatsResponse, ValidationError, Webhook, type WebhookCreateOptions, type WebhookDeliveriesOptions, type WebhookDeliveriesPage, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEndpoint, type WebhookEndpointCreate, type WebhookEndpointUpdate, type WebhookEvent, type WebhookUpdateOptions, WebhookVerificationError, type WebhookVerificationReason, type WebhookVerifyOptions, Webhooks, buildQueryString, defaultUserAgent, parseRetryAfter, resolveApiKey, resolveApiVersion, resolveBaseUrl, sleep };