@lexapi/client 0.2.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -79,15 +79,29 @@ interface ResponseHeaders {
79
79
  /**
80
80
  * API contract version the server implements (`X-LexAPI-Version`, e.g.
81
81
  * `2.1.0`). Sent on every response the LexAPI application itself produces
82
- * (lex-api ≥ API 2.1.0) — its absence on an error means a proxy answered.
82
+ * (API 2.1.0 and later) — its absence on an error means a proxy answered.
83
83
  */
84
84
  apiVersion?: string;
85
- /** Deployed build (`X-LexAPI-Release`, e.g. `2.1.0+633eb67`) — quote it in bug reports. */
85
+ /** Deployed build (`X-LexAPI-Release`, e.g. `2.1.0+abc1234`) — quote it in bug reports. */
86
86
  release?: string;
87
87
  /** Rows kept by the `/documents/recent` lenient language filter (`X-Language-Partial-Kept`). */
88
88
  languagePartialKept?: number;
89
89
  /** Age in seconds of a cached answer (`X-Cache-Age`). */
90
90
  cacheAge?: number;
91
+ /**
92
+ * National-law monthly call allowance for plans below BUSINESS
93
+ * (`X-National-Limit`/`X-National-Remaining`/`X-National-Reset`). Sent on
94
+ * the four national document/semantic endpoints for FREE/STARTER/
95
+ * PROFESSIONAL callers only — absent for BUSINESS/SCALE/ENTERPRISE and
96
+ * `getNationalCoverage`. A used-up allowance is a
97
+ * 402 `NationalAllowanceExhaustedError`, not a header you need to poll.
98
+ */
99
+ nationalAllowance?: {
100
+ limit?: number;
101
+ remaining?: number;
102
+ /** ISO date-time: start of the next UTC month. */
103
+ resetsAt?: string;
104
+ };
91
105
  }
92
106
  /** Minimal `Headers` surface (works with polyfilled / injected fetch implementations). */
93
107
  interface HeaderGetter {
@@ -99,618 +113,346 @@ declare function parseResponseHeaders(source: {
99
113
  } | HeaderGetter): ResponseHeaders;
100
114
 
101
115
  /**
102
- * Typed errors mirroring the LexAPI error envelope:
103
- *
104
- * { "success": false, "error": { "code": "NOT_FOUND", "message": "...", "details": {...} } }
116
+ * Server-directed waits (SDK contract §1.2): the grammar of `Retry-After`,
117
+ * `RateLimit-Reset` and the JSON `retryAfter` field. Anything outside it
118
+ * counts as absent.
119
+ */
120
+ /**
121
+ * Normalize a numeric retry hint. The field can carry absolute epoch values
122
+ * instead of delta-seconds: above 1e12 it is read as epoch milliseconds,
123
+ * above 1e9 as epoch seconds, and either is converted to a non-negative
124
+ * delta in seconds. A value that is not finite gives 0.
125
+ */
126
+ declare function normalizeRetryAfterSeconds(value: number): number;
127
+
128
+ /**
129
+ * Hand-curated types mirroring LexAPI's `openapi.yaml` and `docs.md`.
105
130
  *
106
- * Some legacy endpoints return a bare `{ "error": "...", "message": "..." }`
107
- * body without the typed envelope; the parser tolerates both shapes. Unknown
108
- * codes never crash the parser — the raw code string is preserved on the
109
- * base `LexAPIError` (forward compatibility).
131
+ * Conventions:
132
+ * - `type: [X, 'null']` becomes `X | null`; properties outside a `required`
133
+ * list are optional.
134
+ * - Open string enums (`"a" | "b" | (string & {})`) are used where the server
135
+ * may add values (forward compatibility) — known values still autocomplete.
136
+ * - Fields the SDK adds from response headers are documented as "SDK-added".
110
137
  */
111
138
 
112
- /** Stable error codes from the OpenAPI `ErrorResponse.error.code` enum. */
113
- type ErrorCode = "NOT_FOUND" | "INVALID_CELEX" | "INVALID_URL" | "INVALID_PARAMS" | "RATE_LIMITED" | "QUOTA_EXHAUSTED" | "TIER_FORBIDDEN" | "CREDITS_EXHAUSTED" | "UPSTREAM_ERROR" | "TIMEOUT" | "INTERNAL" | "UNAUTHORIZED" | "SERVICE_UNAVAILABLE" | "CONNECTION_ERROR" | "REQUEST_TIMEOUT" | "ABORTED" | "INVALID_RESPONSE" | "INCOMPLETE_EXPORT" | (string & {});
114
- /** Extra context attached to errors built from an HTTP response. */
115
- interface LexAPIErrorContext {
116
- /** The parsed JSON error body, verbatim (e.g. legacy `upgradeUrl`, `current`/`limit`). */
117
- body?: unknown;
118
- /** Parsed response headers (rate limits, source, …). */
119
- headers?: ResponseHeaders;
120
- }
121
- /** Base class for every error thrown by the SDK. */
122
- declare class LexAPIError extends Error {
123
- /** Stable class tag used by the cross-build `instanceof` brand check. */
124
- static readonly kind: string;
125
- static [Symbol.hasInstance](value: unknown): boolean;
126
- /** Stable machine-readable code (`error.code`, or derived from the HTTP status for legacy bodies). */
127
- readonly code: ErrorCode;
128
- /** HTTP status. `0` for client-side failures (network error, client-side timeout). */
129
- readonly status: number;
130
- /** The `error.details` object from the typed envelope, when present. */
131
- readonly details: unknown;
132
- /**
133
- * Seconds to wait before retrying, when the server said so (429).
134
- * Sourced from the `Retry-After` response HEADER first; the JSON
135
- * `retryAfter` body field is only a fallback because it historically
136
- * carried buggy epoch-seconds values (epoch-looking values are
137
- * normalized to a delta).
138
- */
139
- readonly retryAfter: number | undefined;
139
+ /** Subscription tiers. `SCALE` was added with the 2026-07 pricing. */
140
+ type SubscriptionTier = "FREE" | "STARTER" | "PROFESSIONAL" | "BUSINESS" | "SCALE" | "ENTERPRISE" | (string & {});
141
+ /** ISO 639-1 code (24 official EU languages). */
142
+ type Language = "en" | "fr" | "de" | "es" | "it" | "pl" | "nl" | "pt" | "ro" | "bg" | "cs" | "da" | "el" | "et" | "fi" | "ga" | "hr" | "hu" | "lt" | "lv" | "mt" | "sk" | "sl" | "sv";
143
+ type Domain = "EU_LAW" | "NATIONAL_LAW" | "ALL";
144
+ type Subdomain = "LEGISLATION" | "CONSLEG" | "TREATIES" | "EU_CASE_LAW" | "LEGAL_PROCEDURE" | "INTER_AGREE" | "PRE_ACTS" | "PAR_QUESTION" | "NAT_CASE_LAW";
145
+ /** User-facing document-type filter enum (request side). */
146
+ type DocumentType = "judgment" | "opinion" | "order" | "regulation" | "directive" | "decision" | "recommendation" | "communication" | "proposal" | "report" | "resolution" | "declaration" | "treaty" | "protocol" | "agreement" | "written-question" | "oral-question" | "consolidated-text" | "guideline" | "implementing" | "staff-working-document";
147
+ type Author = "commission" | "council" | "parliament" | "court-of-justice" | "general-court" | "ecb" | "eca" | "eesc" | "cor" | "ema" | "efsa";
148
+ type Procedure = "ordinary" | "codecision" | "consent" | "consultation" | "budget" | "implementing" | "delegated" | "comitology" | "appointment" | "non-legislative";
149
+ type TextScope = "title" | "text" | "title-text" | "any";
150
+ /** A single value or a list of values (the API accepts both on list filters). */
151
+ type OneOrMany<T> = T | T[];
152
+ interface SubscriptionInfo {
153
+ tier?: SubscriptionTier;
154
+ maxPages?: number;
155
+ maxBatchSize?: number;
156
+ maxWebhooks?: number;
157
+ /** Semantic endpoints only: the effective result cap for this call. */
158
+ maxResults?: number;
159
+ /** `credits` = monthly credit pool (pricing v2); `daily` = legacy daily-call model. */
160
+ pricingMode?: "credits" | "daily";
161
+ /** Legacy daily-call ceiling. `null` for credit-pool (v2) accounts. */
162
+ dailyLimit?: number | null;
163
+ /** Monthly credit allowance. `null` for legacy daily-call accounts. */
164
+ monthlyCredits?: number | null;
165
+ /** e.g. `"120 requests/minute"`. `"0 requests/minute"` means unlimited (hand-priced plans). */
166
+ rateLimit?: string;
140
167
  /**
141
- * The parsed JSON error body, verbatim. Useful for legacy-shape fields the
142
- * typed properties don't cover (`upgradeUrl` on tier gates, `current` /
143
- * `limit` on the webhook ceiling, `usage` on legacy quota 429s).
168
+ * `getInfo`: the most results one case-law semantic search returns on your
169
+ * plan (what `limit` is clamped to); `0` without semantic search (API 2.24.0).
144
170
  */
145
- readonly body: unknown;
146
- /** Parsed response headers, when the error came from an HTTP response. */
147
- readonly headers: ResponseHeaders | undefined;
148
- constructor(code: ErrorCode, message: string, status: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
171
+ maxSemanticResults?: number;
149
172
  /**
150
- * Build the most specific error subclass for a non-2xx response.
151
- * Accepts both the typed envelope and the legacy bare `{error, message}` shape.
173
+ * `getInfo`: the same for legislation semantic search, at most 50 per call;
174
+ * `0` without semantic search (API 2.24.0).
152
175
  */
153
- static fromResponse(status: number, body: unknown, headerRetryAfter?: number, headers?: ResponseHeaders): LexAPIError;
154
- }
155
- /** 404 — document or resource missing (`NOT_FOUND`). */
156
- declare class NotFoundError extends LexAPIError {
157
- static readonly kind: string;
158
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
159
- }
160
- /** 400 — CELEX failed validation (`INVALID_CELEX`). */
161
- declare class InvalidCelexError extends LexAPIError {
162
- static readonly kind: string;
163
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
164
- }
165
- /** 400 — URL had no resolvable CELEX (`INVALID_URL`). */
166
- declare class InvalidUrlError extends LexAPIError {
167
- static readonly kind: string;
168
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
169
- }
170
- /** 400 — missing or malformed params (`INVALID_PARAMS`). */
171
- declare class InvalidParamsError extends LexAPIError {
172
- static readonly kind: string;
173
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
176
+ maxSemanticLegislationResults?: number;
174
177
  }
175
- /** 401 — missing, invalid, or revoked API key. */
176
- declare class AuthenticationError extends LexAPIError {
177
- static readonly kind: string;
178
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
178
+ /**
179
+ * Caller's current usage counters at request time. Dual-mode: credits over
180
+ * the monthly window for v2 accounts, API calls for the day on legacy
181
+ * accounts. Prefer the richer `credits` block on v2 responses.
182
+ */
183
+ interface UsageInfo {
184
+ current?: number;
185
+ limit?: number;
186
+ remaining?: number;
187
+ /** Documented by the spec; not currently emitted by the server. */
188
+ unit?: "credits" | "calls";
189
+ /** When the counter resets (ISO date-time). */
190
+ resetsAt?: string | null;
191
+ /** Legacy daily-call plans only: calls this request counted (always 1). */
192
+ unitsCharged?: number;
179
193
  }
180
194
  /**
181
- * 429 — per-minute rate limit (`RATE_LIMITED`), or, on legacy daily plans,
182
- * the used-up daily / monthly-semantic quota (`QUOTA_EXHAUSTED`; `code`
183
- * tells them apart). 429s use the legacy `{error, message, retryAfter}` body
184
- * (with a top-level `code` from lex-api #304 on); the `Retry-After` header is
185
- * authoritative and is what `retryAfter` reads first.
195
+ * Pricing-v2 credit-pool state. Present on responses for credit-pool
196
+ * accounts (alongside the back-compat `usage` block); absent for legacy
197
+ * daily-call accounts.
186
198
  */
187
- declare class RateLimitedError extends LexAPIError {
188
- static readonly kind: string;
189
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext, code?: "RATE_LIMITED" | "QUOTA_EXHAUSTED");
190
- /** `RateLimit-*` headers from the 429 response (limit / remaining / reset seconds). */
191
- get rateLimit(): RateLimitInfo | undefined;
199
+ interface CreditsInfo {
192
200
  /**
193
- * `true` for a legacy-plan quota 429 (daily call quota, or the monthly
194
- * semantic quota) rather than the per-minute limiter (SDK contract §1.2):
195
- * `code` is `QUOTA_EXHAUSTED`, or — servers before lex-api #304, which
196
- * send no code — the body carries `usage.resetsAt` with neither a
197
- * `Retry-After` header nor a `retryAfter` body field. It cannot succeed
198
- * before `resetsAt`, so the SDK does not retry it and `retryAfter` is
199
- * `undefined`.
201
+ * Credits this request cost (0 for free operations such as /info). On
202
+ * operations that settle by source (document reads, searches, HyDE, asOf
203
+ * fetches) refunds are applied after the response is sent, so this can
204
+ * show the upfront charge; the next call's envelope reflects the refund.
200
205
  */
201
- get quotaExhausted(): boolean;
202
- /** When a legacy quota resets: the body's `resetsAt`, else `usage.resetsAt`. */
203
- get resetsAt(): string | undefined;
204
- }
205
- /** 403 — tier-gated endpoint (`TIER_FORBIDDEN`). Retrying cannot help; upgrade the plan. */
206
- declare class TierForbiddenError extends LexAPIError {
207
- static readonly kind: string;
208
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
209
- }
210
- /** `error.details` on a 402 `CREDITS_EXHAUSTED` envelope. */
211
- interface CreditsExhaustedDetails {
212
- /** The operation that was refused, e.g. `"semantic_case_law"`. */
213
- operation?: string;
214
- /** Its upfront credit weight (variable-priced operations are admitted against their upfront weight). */
215
- weight?: number;
216
- /** Credits left in the pool (monthly + top-up − used). `weight − available` is the shortfall. */
217
- available?: number;
218
- /** Monthly allowance. */
206
+ operation_weight?: number;
207
+ /** Credits used in the current monthly window. */
208
+ current?: number;
209
+ /** Total pool this window (included + topup). */
210
+ limit?: number;
211
+ remaining?: number;
212
+ /** Monthly credit allowance for the tier. */
219
213
  included?: number;
220
- /** Top-up credits. */
214
+ /** Purchased top-up credits, spent after the monthly allowance; never expire. */
221
215
  topup?: number;
222
- /** Credits used this window. */
223
- used?: number;
224
- /** When the monthly pool refills. */
216
+ /** When the monthly allowance resets. May be null until first set. */
225
217
  resetsAt?: string | null;
226
- [key: string]: unknown;
218
+ }
219
+ /** Shape shared by every LexAPI response that reports quota state. */
220
+ interface CreditedResponse {
221
+ subscription?: SubscriptionInfo;
222
+ usage?: UsageInfo;
223
+ credits?: CreditsInfo;
227
224
  }
228
225
  /**
229
- * 402 — monthly credit pool (incl. top-ups) cannot cover the operation
230
- * (`CREDITS_EXHAUSTED`). Not retried: wait for `resetsAt`, buy a top-up, or
231
- * upgrade. A cheaper operation may still succeed — compare `weight` to `available`.
226
+ * Parsed response headers attached by the SDK to every JSON response
227
+ * (`result.headers`). See {@link ResponseHeaders}.
232
228
  */
233
- declare class CreditsExhaustedError extends LexAPIError {
234
- static readonly kind: string;
235
- /** When the monthly credit allowance resets (ISO date-time), when the server said so. */
236
- readonly resetsAt: string | undefined;
237
- /** Typed view of `error.details` (operation, weight, available, included, topup, used, resetsAt). */
238
- readonly details: CreditsExhaustedDetails | undefined;
239
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, resetsAt?: string, context?: LexAPIErrorContext);
240
- /** The refused operation's credit weight (`details.weight`). */
241
- get weight(): number | undefined;
242
- /** Credits left in the pool (`details.available`). */
243
- get available(): number | undefined;
244
- /** The refused operation (`details.operation`). */
245
- get operation(): string | undefined;
229
+ interface WithResponseHeaders {
230
+ /** SDK-added: parsed LexAPI response headers (source, rate limits, warnings, …). */
231
+ headers?: ResponseHeaders;
246
232
  }
247
- /** 502 — EUR-Lex returned an error (`UPSTREAM_ERROR`). Retry-safe on GETs. */
248
- declare class UpstreamError extends LexAPIError {
249
- static readonly kind: string;
250
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
233
+ interface InfoSearchFilters {
234
+ textScope?: TextScope[];
235
+ domain?: Domain[];
236
+ subdomain?: Subdomain[];
237
+ documentType?: DocumentType[];
238
+ author?: Author[];
239
+ procedure?: Procedure[];
240
+ }
241
+ interface InfoResponse extends CreditedResponse, WithResponseHeaders {
242
+ service?: string;
243
+ version?: string;
244
+ description?: string;
245
+ /** Self-describing capability map (per-endpoint method, path, parameters). */
246
+ endpoints?: Record<string, unknown>;
247
+ searchFilters?: InfoSearchFilters;
248
+ supportedLanguages?: Language[];
251
249
  }
252
250
  /**
253
- * A timeout. Two cases, told apart by `code` / `status`:
254
- * - `TIMEOUT` (504, 524): the server or Cloudflare gave up on the upstream.
255
- * - `REQUEST_TIMEOUT` (`status === 0`): the SDK's own response timeout —
256
- * no bytes for `timeoutMs` (SDK contract §1.6).
251
+ * `include` / `fields` token. The spec's enum lists
252
+ * metadata/fullText/articles/recitals/sections/tables/annexes; the
253
+ * `DocumentContent` description additionally documents `paragraphs`.
257
254
  */
258
- declare class TimeoutError extends LexAPIError {
259
- static readonly kind: string;
260
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
261
- }
255
+ type IncludeToken = "metadata" | "fullText" | "articles" | "recitals" | "paragraphs" | "sections" | "tables" | "annexes";
256
+ /** Array form, or a comma-separated string like `"metadata,articles"`. */
257
+ type IncludeSelection = IncludeToken[] | string;
262
258
  /**
263
- * 503 — service temporarily unavailable (e.g. a deploy's drain window).
264
- * Derived from the status (no typed code). Retried like 502/504.
259
+ * Opt-in language fallback for documents with no text in the requested
260
+ * language: an ordered list of ISO codes the caller can consume, or `"any"`.
265
261
  */
266
- declare class ServiceUnavailableError extends LexAPIError {
267
- static readonly kind: string;
268
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
262
+ type AcceptLanguages = Language[] | "any";
263
+ /** A top-level article extracted from the document body. */
264
+ interface Article {
265
+ /** Stable id (e.g. `art_17`, `art_6a` for an inserted article). */
266
+ id?: string;
267
+ /** e.g. `"Article 17"` — the heading as published. */
268
+ number: string;
269
+ title?: string | null;
270
+ /** Plain-text body of the article (paragraphs joined). */
271
+ content: string;
269
272
  }
270
- /** 500 — unexpected server failure (`INTERNAL`). Not retried by default. */
271
- declare class InternalServerError extends LexAPIError {
272
- static readonly kind: string;
273
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
273
+ /**
274
+ * Chapter/section hierarchy node. `articleRange` is
275
+ * `[firstArticleId, lastArticleId]` when the section directly contains
276
+ * articles; `null` for chapters whose children are sub-sections.
277
+ */
278
+ interface Section {
279
+ type: "chapter" | "section";
280
+ /** `null` for an unnumbered section heading. */
281
+ number: string | null;
282
+ /** `null` when the heading has no title text. */
283
+ title: string | null;
284
+ articleRange?: [string, string] | null;
274
285
  }
275
- /** Transport-level failure: DNS, connection reset, etc. No HTTP response was received. */
276
- declare class NetworkError extends LexAPIError {
277
- static readonly kind: string;
278
- readonly cause: unknown;
279
- constructor(message: string, cause?: unknown);
286
+ /** Preamble recital — also the element type of `paragraphs[]` (numbered prose). */
287
+ interface Recital {
288
+ /** `null` when the recital's number could not be read from the markup. */
289
+ number: number | null;
290
+ text: string;
280
291
  }
281
- /** The caller's `AbortSignal` fired (status 0). Never retried. `cause` is the signal's reason. */
282
- declare class RequestAbortedError extends LexAPIError {
283
- static readonly kind: string;
284
- readonly cause: unknown;
285
- constructor(message: string, cause?: unknown);
292
+ interface Annex {
293
+ title?: string;
294
+ content?: string;
286
295
  }
287
- /**
288
- * A 2xx response whose body was not the JSON LexAPI sends (e.g. an HTML page
289
- * from a proxy). `body` holds the first 500 characters of the raw text.
290
- */
291
- declare class InvalidResponseError extends LexAPIError {
292
- static readonly kind: string;
293
- constructor(message: string, status: number, rawText?: string, context?: LexAPIErrorContext);
296
+ interface Table {
297
+ caption?: string;
298
+ headers?: string[];
299
+ rows?: string[][];
294
300
  }
295
301
  /**
296
- * An export stream ended (cleanly, at EOF) without its trailing `_done` line —
297
- * the server stopped mid-export (SDK contract §1.8). Raised after the rows
298
- * that did arrive were yielded; they are NOT a complete export.
302
+ * Structured document body. Case-law CELEXes (sector 6) emit numbered
303
+ * grounds in `paragraphs[]` with empty `recitals[]`; legislation keeps
304
+ * `recitals[]`. With `include`/`fields` selection any key can be omitted.
299
305
  */
300
- declare class IncompleteExportError extends LexAPIError {
301
- static readonly kind: string;
302
- /** Rows yielded before the stream ended. */
303
- readonly rowsRead: number;
304
- /**
305
- * @param details the server's `_error` line body (`{ code, message }`) when
306
- * one arrived; `undefined` for a missing or `complete: false` trailer.
307
- */
308
- constructor(message: string, rowsRead: number, details?: unknown);
306
+ interface DocumentContent {
307
+ fullText?: string;
308
+ articles?: Article[];
309
+ /** Legislative preamble recitals. Empty `[]` on case-law — see `paragraphs`. */
310
+ recitals?: Recital[];
311
+ /** Judgment grounds (case-law), text outside articles, or fullText splits. */
312
+ paragraphs?: Recital[];
313
+ sections?: Section[];
314
+ /** Genuine data tables only (layout-table noise is filtered out server-side). */
315
+ tables?: Table[];
316
+ annexes?: Annex[];
317
+ }
318
+ /** Why a document response carries no text. */
319
+ type TextUnavailableReason = "not_in_language" | "not_published_yet" | "no_machine_readable_rendition" | "too_large" | "unknown" | (string & {});
320
+ /** Pointer to a consolidated version (CONSLEG, CELEX sector 0) of a base act. */
321
+ interface ConsolidatedVersionHint {
322
+ /** e.g. `"02006R1907-20260622"` — pass back to `getDocument` (a normal, separately charged read). */
323
+ celex: string;
324
+ /** Consolidation date (`YYYY-MM-DD`), from the CELEX suffix. */
325
+ date: string;
326
+ /** `cellar` — Publications Office list; `corpus` — Cellar was unreachable, newest version LexAPI holds. */
327
+ source: "cellar" | "corpus" | (string & {});
328
+ /** `newestConsolidated` only — lower-case ISO codes the version exists in. */
329
+ availableLanguages?: string[];
309
330
  }
310
331
  /**
311
- * `true` for any error thrown by this SDK — from either build (ESM or
312
- * CommonJS) or another installed copy. Pass a class to narrow:
313
- * `isLexAPIError(err, NotFoundError)`.
314
- */
315
- declare function isLexAPIError<T extends LexAPIError = LexAPIError>(value: unknown, errorClass?: abstract new (...args: never[]) => T): value is T;
316
- /**
317
- * Normalize a JSON `retryAfter` body value. The field historically carried
318
- * buggy absolute epoch values instead of delta-seconds (pending server fix);
319
- * epoch-looking values are converted to a non-negative delta in seconds.
320
- */
321
- declare function normalizeRetryAfterSeconds(value: number): number;
322
-
323
- declare const DEFAULT_BASE_URL = "https://lex-api.com/api/v1";
324
- /**
325
- * 95 s per attempt: above the 90 s hard timeout the API puts on a single live
326
- * EUR-Lex fetch (so such a fetch ends in the server's typed, refunded 504
327
- * rather than a client abort that may still be billed), and below
328
- * Cloudflare's 100 s proxy timeout. A request that runs several upstream
329
- * fetches (Cellar, then the browser; a batch) can still exceed it.
332
+ * Whether a document response carries its text, and if not, why. Present on
333
+ * every document response. A text-unavailable document is a `200` with
334
+ * metadata and `content: null` (billed 1 credit), not a 404.
330
335
  */
331
- declare const DEFAULT_TIMEOUT_MS = 95000;
332
- /** Retry policy knobs (SDK contract §1.2). */
333
- interface RetryOptions {
334
- /** Max retries after the initial attempt. Default 3. Set 0 to disable retries. */
335
- maxRetries?: number;
336
- /** Exponential backoff base. Default 500 ms. */
337
- baseDelayMs?: number;
338
- /** Cap on any single wait (computed or server-directed). Default 30 000 ms. */
339
- maxDelayMs?: number;
336
+ interface TextAvailability {
337
+ available: boolean;
338
+ /** Absent when `available` is true. */
339
+ reason?: TextUnavailableReason;
340
+ retryable?: boolean;
340
341
  /**
341
- * SDK contract §1.2 opt-in (default `false`): also retry the eight
342
- * read-only POSTs (`search`, `getDocument`, `getDocumentsBatch`,
343
- * `getDocumentByUrl`, `getDocumentMetadata`, `resolve`, `semanticSearch`,
344
- * `semanticLegislationSearch`) on an **app-origin** 502/503/504 — those
345
- * are refunded in full, so the retry is billing-safe. App-origin = a
346
- * non-empty `X-LexAPI-Version` or a `RateLimit-Limit` header; anything
347
- * else is treated as a proxy answer and never retried on a billed call. Never applies to mutating calls (webhook
348
- * writes, `extractCitations`).
342
+ * ISO codes whose text could be served. `null` = unknown; `[]` = known to
343
+ * be none. Those are different facts — do not collapse them.
349
344
  */
350
- retryReadOnlyPosts?: boolean;
351
- }
352
- interface HttpClientOptions {
353
- apiKey: string;
354
- baseUrl: string;
355
- timeoutMs: number;
356
- fetchFn: typeof fetch;
357
- retry: Required<RetryOptions>;
358
- userAgentSuffix?: string | undefined;
345
+ availableLanguages?: string[] | null;
346
+ /** Where EUR-Lex itself points for the text (e.g. the European Parliament site). */
347
+ externalSource?: string;
348
+ /** e.g. `"cellar-manifestations"`, `"parse-worker"` (`too_large` verdict). */
349
+ source?: string;
350
+ checkedAt?: string;
351
+ /** Base acts only: newest consolidated version dated on or before today, in the requested language. */
352
+ latestConsolidated?: ConsolidatedVersionHint;
353
+ /** Base acts only: the next consolidated version dated after today, in the requested language. */
354
+ upcomingConsolidated?: ConsolidatedVersionHint;
355
+ /** Base acts only: the newest consolidated version when it has NO text in the requested language. */
356
+ newestConsolidated?: ConsolidatedVersionHint;
359
357
  }
360
- /** Query values; arrays are sent as repeated parameters (`?a=x&a=y`). */
361
- type QueryParams = Record<string, string | number | boolean | undefined | ReadonlyArray<string | number | boolean>>;
362
- interface RequestOptions {
363
- method: "GET" | "POST" | "PUT" | "DELETE";
364
- path: string;
365
- query?: QueryParams;
366
- body?: unknown;
367
- /** Per-call timeout override (per attempt, covering the response body). */
368
- timeoutMs?: number | undefined;
369
- /** Caller cancellation: aborts the in-flight attempt and any retry wait. */
370
- signal?: AbortSignal | undefined;
371
- /** `Accept` header override (default `application/json`). */
372
- accept?: string;
373
- /**
374
- * One of the eight read-only POSTs of SDK contract §1.2 — retried on
375
- * app-origin 502/503/504 when `retryReadOnlyPosts` is on.
376
- */
377
- idempotent?: boolean;
358
+ /** Normalized metadata for a single document. */
359
+ interface DocumentMetadata {
360
+ /** Canonical CELEX. Always present on metadata responses. */
361
+ celex?: string;
362
+ /** Legacy alias for `celex` (metadata endpoint back-compat). */
363
+ celexNumber?: string;
364
+ /** `null` when the document is genuinely sparse — never `"Unknown Title"`. */
365
+ title?: string | null;
378
366
  /**
379
- * A free operation (0 credits: `/info`, webhook reads). A retry cannot
380
- * charge, so proxy-origin 5xx/520/524 and post-send transport errors are
381
- * retried too (SDK contract §1.2).
367
+ * Present only when `title` is NOT in the requested language: the ISO
368
+ * 639-1 code of the language it is in (`en` for the English fallback).
369
+ * Absent means the title is in the requested language.
382
370
  */
383
- free?: boolean;
371
+ titleLanguage?: string;
372
+ /** Prose form of the document, e.g. `"Regulation"`. */
373
+ documentType?: string | null;
374
+ /** Stable enum slug for `documentType` (e.g. `"regulation"`). */
375
+ documentTypeCode?: DocumentTypeCode | null;
376
+ /** `null` for placeholder authors (e.g. consolidated texts' "Provisional data"). */
377
+ author?: string | null;
378
+ /** Legacy DD/MM/YYYY string as published by EUR-Lex. Prefer `dateOfDocumentISO`. */
379
+ dateOfDocument?: string | null;
380
+ /** ISO-8601 date parsed from `dateOfDocument`. */
381
+ dateOfDocumentISO?: string | null;
382
+ dateOfEffect?: string | null;
383
+ dateOfEffectISO?: string | null;
384
+ dateOfPublication?: string | null;
385
+ dateOfPublicationISO?: string | null;
386
+ /** Qualifier EUR-Lex appends to dates (e.g. `"Date of signature"`). */
387
+ dateType?: string | null;
388
+ /** European Case Law Identifier (recovered from htmlMetadata for sector-6 rows). */
389
+ ecli?: string | null;
390
+ /** European Legislation Identifier path. */
391
+ eli?: string | null;
392
+ /** Court case number; joined-case ranges come as one string (`"C-171/24 to C-177/24"`). */
393
+ caseNumber?: string | null;
394
+ /** Parsed party names from case-law titles. */
395
+ parties?: string | null;
396
+ /** EUROVOC keywords, deduplicated case-insensitively. */
397
+ keywords?: string[];
398
+ /** EUR-Lex directory codes (e.g. `"13.30.99.00 Other sectors"`). */
399
+ directoryCodes?: string[];
400
+ subject?: string[];
384
401
  }
385
- declare const INSPECT: unique symbol;
402
+ /** Canonical EUR-Lex URLs for a document. */
403
+ interface DocumentUrls {
404
+ html?: string;
405
+ metadata?: string;
406
+ pdf?: string;
407
+ xml?: string;
408
+ }
409
+ /** Why an act is not in force today (`inForce: false`). */
410
+ type NotInForceReason = "no_longer_in_force" | "not_yet_in_force" | (string & {});
386
411
  /**
387
- * Single request core used by every SDK method.
388
- *
389
- * - `x-api-key` auth + `User-Agent: lexapi-typescript/<version>` on every
390
- * request (UA omitted on browser runtimes, where it cannot be set). The key
391
- * lives in a private field and never appears in `util.inspect`,
392
- * `console.log` or `JSON.stringify` output.
393
- * - One inactivity timeout per attempt (SDK contract §1.6): it runs until
394
- * the response head arrives and restarts on every body chunk, for JSON
395
- * bodies and export streams alike.
396
- * - Caller `AbortSignal`: aborts the attempt and any retry wait; throws
397
- * `RequestAbortedError`, never retried.
398
- * - Retries follow the billing-safety rule of SDK contract §1.2 — only when
399
- * a retry cannot charge twice (see `shouldRetryStatus` and PLAN.md §1.2).
400
- * - Server-directed waits: `Retry-After` on any status; on a 429 only, then
401
- * `RateLimit-Reset` and the JSON `retryAfter` field. `X-RateLimit-*` is
402
- * never read.
412
+ * Whether an act is in force today (UTC), as recorded by the Publications
413
+ * Office (API 2.19.0). All four fields are absent when the status is unknown,
414
+ * and on documents that have no in-force status (case law, preparatory acts).
415
+ * A consolidated text carries the label of the act it consolidates, a
416
+ * corrigendum the label of the act it corrects. It does not cover amendments
417
+ * (an act amended since is still `inForce: true`) or dates of application.
403
418
  */
404
- declare class HttpClient {
405
- #private;
406
- private readonly opts;
407
- private readonly userAgent;
408
- constructor(opts: HttpClientOptions);
409
- /** API base URL. */
410
- get baseUrl(): string;
411
- /** Client-level per-attempt timeout (ms). */
412
- get timeoutMs(): number;
413
- /** Redacted view for `JSON.stringify` — never includes the API key. */
414
- toJSON(): Record<string, unknown>;
415
- /** Redacted view for `util.inspect` / `console.log`. */
416
- [INSPECT](): string;
417
- /** Perform a request and parse the JSON body (204 / empty body yields `{}`). */
418
- requestJson<T>(options: RequestOptions): Promise<T>;
419
+ interface InForceLabel {
420
+ /** In force today (UTC). */
421
+ inForce?: boolean;
419
422
  /**
420
- * Like `requestJson`, but also exposes the raw `Response` (for header
421
- * signals). The body is read inside the attempt, under its timeout.
423
+ * With `inForce: false` only. `no_longer_in_force`: past its end of
424
+ * validity (repealed or expired). `not_yet_in_force`: before its entry into force.
422
425
  */
423
- requestJsonWithResponse<T>(options: RequestOptions): Promise<{
424
- data: T;
425
- response: Response;
426
- }>;
426
+ notInForceReason?: NotInForceReason;
427
427
  /**
428
- * Perform a request and return the raw successful `Response` without
429
- * consuming the body (streaming endpoints such as `/export`). The attempt
430
- * timeout covers only the response headers; the caller applies its own
431
- * idle timeout to body reads. Non-2xx responses are parsed and thrown as
432
- * typed errors; the retry policy applies before the first body byte.
428
+ * The act's last day in force (`YYYY-MM-DD`), also a future date. Present
429
+ * only when exactly one end date is recorded for the act.
433
430
  */
434
- requestRaw(options: RequestOptions): Promise<Response>;
435
- private execute;
431
+ endOfValidity?: string;
432
+ /** With `not_yet_in_force`, the entry into force (`YYYY-MM-DD`) when it is recorded. */
433
+ entryIntoForce?: string;
436
434
  }
437
-
438
435
  /**
439
- * Hand-curated types mirroring LexAPI's `openapi.yaml` (LexAPI 2.0.0) and
440
- * `docs.md`, cross-checked against the server's controllers.
441
- *
442
- * Validated against: lex-api `main` @ 633eb67 (2026-10-26, PR #298).
443
- *
444
- * Conventions:
445
- * - `type: [X, 'null']` becomes `X | null`; properties outside a `required`
446
- * list are optional.
447
- * - Open string enums (`"a" | "b" | (string & {})`) are used where the server
448
- * may add values (forward compatibility) — known values still autocomplete.
449
- * - Fields the SDK adds from response headers are documented as "SDK-added".
436
+ * Which fields of the object are the publisher's text and which were derived
437
+ * (API 2.20.0). Each value lists paths relative to the object that carries it
438
+ * (`content.articles[].content`); only classes with a field in the response
439
+ * appear. `official_source_text` means the publisher's wording, not that the
440
+ * text is legally authentic.
450
441
  */
451
-
452
- /** Subscription tiers. `SCALE` was added with the 2026-07 pricing. */
453
- type SubscriptionTier = "FREE" | "STARTER" | "PROFESSIONAL" | "BUSINESS" | "SCALE" | "ENTERPRISE" | (string & {});
454
- /** ISO 639-1 code (24 official EU languages). */
455
- type Language = "en" | "fr" | "de" | "es" | "it" | "pl" | "nl" | "pt" | "ro" | "bg" | "cs" | "da" | "el" | "et" | "fi" | "ga" | "hr" | "hu" | "lt" | "lv" | "mt" | "sk" | "sl" | "sv";
456
- type Domain = "EU_LAW" | "NATIONAL_LAW" | "ALL";
457
- type Subdomain = "LEGISLATION" | "CONSLEG" | "TREATIES" | "EU_CASE_LAW" | "LEGAL_PROCEDURE" | "INTER_AGREE" | "PRE_ACTS" | "PAR_QUESTION" | "NAT_CASE_LAW";
458
- /** User-facing document-type filter enum (request side). */
459
- type DocumentType = "judgment" | "opinion" | "order" | "regulation" | "directive" | "decision" | "recommendation" | "communication" | "proposal" | "report" | "resolution" | "declaration" | "treaty" | "protocol" | "agreement" | "written-question" | "oral-question" | "consolidated-text" | "guideline" | "implementing" | "staff-working-document";
460
- type Author = "commission" | "council" | "parliament" | "court-of-justice" | "general-court" | "ecb" | "eca" | "eesc" | "cor" | "ema" | "efsa";
461
- type Procedure = "ordinary" | "codecision" | "consent" | "consultation" | "budget" | "implementing" | "delegated" | "comitology" | "appointment" | "non-legislative";
462
- type TextScope = "title" | "text" | "title-text" | "any";
463
- /** A single value or a list of values (the API accepts both on list filters). */
464
- type OneOrMany<T> = T | T[];
465
- interface SubscriptionInfo {
466
- tier?: SubscriptionTier;
467
- maxPages?: number;
468
- maxBatchSize?: number;
469
- maxWebhooks?: number;
470
- /** Semantic endpoints only: the effective result cap for this call. */
471
- maxResults?: number;
472
- /** `credits` = monthly credit pool (pricing v2); `daily` = legacy daily-call model. */
473
- pricingMode?: "credits" | "daily";
474
- /** Legacy daily-call ceiling. `null` for credit-pool (v2) accounts. */
475
- dailyLimit?: number | null;
476
- /** Monthly credit allowance. `null` for legacy daily-call accounts. */
477
- monthlyCredits?: number | null;
478
- /** e.g. `"120 requests/minute"`. `"0 requests/minute"` means unlimited (hand-priced plans). */
479
- rateLimit?: string;
480
- }
481
- /**
482
- * Caller's current usage counters at request time. Dual-mode: credits over
483
- * the monthly window for v2 accounts, API calls for the day on legacy
484
- * accounts. Prefer the richer `credits` block on v2 responses.
485
- */
486
- interface UsageInfo {
487
- current?: number;
488
- limit?: number;
489
- remaining?: number;
490
- /** Documented by the spec; not currently emitted by the server. */
491
- unit?: "credits" | "calls";
492
- /** When the counter resets (ISO date-time). */
493
- resetsAt?: string | null;
494
- /** Legacy daily-call plans only: calls this request counted (always 1). */
495
- unitsCharged?: number;
496
- }
497
- /**
498
- * Pricing-v2 credit-pool state. Present on responses for credit-pool
499
- * accounts (alongside the back-compat `usage` block); absent for legacy
500
- * daily-call accounts.
501
- */
502
- interface CreditsInfo {
503
- /**
504
- * Credits this request cost (0 for free operations such as /info). On
505
- * operations that settle by source (document reads, searches, HyDE, asOf
506
- * fetches) refunds are applied after the response is sent, so this can
507
- * show the upfront charge; the next call's envelope reflects the refund.
508
- */
509
- operation_weight?: number;
510
- /** Credits used in the current monthly window. */
511
- current?: number;
512
- /** Total pool this window (included + topup). */
513
- limit?: number;
514
- remaining?: number;
515
- /** Monthly credit allowance for the tier. */
516
- included?: number;
517
- /** Purchased top-up credits, spent after the monthly allowance; never expire. */
518
- topup?: number;
519
- /** When the monthly allowance resets. May be null until first set. */
520
- resetsAt?: string | null;
521
- }
522
- /** Shape shared by every LexAPI response that reports quota state. */
523
- interface CreditedResponse {
524
- subscription?: SubscriptionInfo;
525
- usage?: UsageInfo;
526
- credits?: CreditsInfo;
527
- }
528
- /**
529
- * Parsed response headers attached by the SDK to every JSON response
530
- * (`result.headers`). See {@link ResponseHeaders}.
531
- */
532
- interface WithResponseHeaders {
533
- /** SDK-added: parsed LexAPI response headers (source, rate limits, warnings, …). */
534
- headers?: ResponseHeaders;
535
- }
536
- interface InfoSearchFilters {
537
- textScope?: TextScope[];
538
- domain?: Domain[];
539
- subdomain?: Subdomain[];
540
- documentType?: DocumentType[];
541
- author?: Author[];
542
- procedure?: Procedure[];
543
- }
544
- interface InfoResponse extends CreditedResponse, WithResponseHeaders {
545
- service?: string;
546
- version?: string;
547
- description?: string;
548
- /** Self-describing capability map (per-endpoint method, path, parameters). */
549
- endpoints?: Record<string, unknown>;
550
- searchFilters?: InfoSearchFilters;
551
- supportedLanguages?: Language[];
552
- }
553
- /**
554
- * `include` / `fields` token. The spec's enum lists
555
- * metadata/fullText/articles/recitals/sections/tables/annexes; the
556
- * `DocumentContent` description additionally documents `paragraphs`.
557
- */
558
- type IncludeToken = "metadata" | "fullText" | "articles" | "recitals" | "paragraphs" | "sections" | "tables" | "annexes";
559
- /** Array form, or a comma-separated string like `"metadata,articles"`. */
560
- type IncludeSelection = IncludeToken[] | string;
561
- /**
562
- * Opt-in language fallback for documents with no text in the requested
563
- * language: an ordered list of ISO codes the caller can consume, or `"any"`.
564
- */
565
- type AcceptLanguages = Language[] | "any";
566
- /** A top-level article extracted from the document body. */
567
- interface Article {
568
- /** Stable id (e.g. `art_17`, `art_6a` for an inserted article). */
569
- id?: string;
570
- /** e.g. `"Article 17"` — the heading as published. */
571
- number: string;
572
- title?: string | null;
573
- /** Plain-text body of the article (paragraphs joined). */
574
- content: string;
575
- }
576
- /**
577
- * Chapter/section hierarchy node. `articleRange` is
578
- * `[firstArticleId, lastArticleId]` when the section directly contains
579
- * articles; `null` for chapters whose children are sub-sections.
580
- */
581
- interface Section {
582
- type: "chapter" | "section";
583
- /** `null` for an unnumbered section heading. */
584
- number: string | null;
585
- /** `null` when the heading has no title text. */
586
- title: string | null;
587
- articleRange?: [string, string] | null;
588
- }
589
- /** Preamble recital — also the element type of `paragraphs[]` (numbered prose). */
590
- interface Recital {
591
- /** `null` when the recital's number could not be read from the markup. */
592
- number: number | null;
593
- text: string;
594
- }
595
- interface Annex {
596
- title?: string;
597
- content?: string;
598
- }
599
- interface Table {
600
- caption?: string;
601
- headers?: string[];
602
- rows?: string[][];
603
- }
604
- /**
605
- * Structured document body. Case-law CELEXes (sector 6) emit numbered
606
- * grounds in `paragraphs[]` with empty `recitals[]`; legislation keeps
607
- * `recitals[]`. With `include`/`fields` selection any key can be omitted.
608
- */
609
- interface DocumentContent {
610
- fullText?: string;
611
- articles?: Article[];
612
- /** Legislative preamble recitals. Empty `[]` on case-law — see `paragraphs`. */
613
- recitals?: Recital[];
614
- /** Judgment grounds (case-law), text outside articles, or fullText splits. */
615
- paragraphs?: Recital[];
616
- sections?: Section[];
617
- /** Genuine data tables only (layout-table noise is filtered out server-side). */
618
- tables?: Table[];
619
- annexes?: Annex[];
620
- }
621
- /** Why a document response carries no text. */
622
- type TextUnavailableReason = "not_in_language" | "not_published_yet" | "no_machine_readable_rendition" | "too_large" | "unknown" | (string & {});
623
- /** Pointer to a consolidated version (CONSLEG, CELEX sector 0) of a base act. */
624
- interface ConsolidatedVersionHint {
625
- /** e.g. `"02006R1907-20260622"` — pass back to `getDocument` (a normal, separately charged read). */
626
- celex: string;
627
- /** Consolidation date (`YYYY-MM-DD`), from the CELEX suffix. */
628
- date: string;
629
- /** `cellar` — Publications Office list; `corpus` — Cellar was unreachable, newest version LexAPI holds. */
630
- source: "cellar" | "corpus" | (string & {});
631
- /** `newestConsolidated` only — lower-case ISO codes the version exists in. */
632
- availableLanguages?: string[];
633
- }
634
- /**
635
- * Whether a document response carries its text, and if not, why. Present on
636
- * every document response. A text-unavailable document is a `200` with
637
- * metadata and `content: null` (billed 1 credit), not a 404.
638
- */
639
- interface TextAvailability {
640
- available: boolean;
641
- /** Absent when `available` is true. */
642
- reason?: TextUnavailableReason;
643
- retryable?: boolean;
644
- /**
645
- * ISO codes whose text could be served. `null` = unknown; `[]` = known to
646
- * be none. Those are different facts — do not collapse them.
647
- */
648
- availableLanguages?: string[] | null;
649
- /** Where EUR-Lex itself points for the text (e.g. the European Parliament site). */
650
- externalSource?: string;
651
- /** e.g. `"cellar-manifestations"`, `"parse-worker"` (our own `too_large` verdict). */
652
- source?: string;
653
- checkedAt?: string;
654
- /** Base acts only: newest consolidated version dated on or before today, in the requested language. */
655
- latestConsolidated?: ConsolidatedVersionHint;
656
- /** Base acts only: the next consolidated version dated after today, in the requested language. */
657
- upcomingConsolidated?: ConsolidatedVersionHint;
658
- /** Base acts only: the newest consolidated version when it has NO text in the requested language. */
659
- newestConsolidated?: ConsolidatedVersionHint;
660
- }
661
- /** Normalized metadata for a single document. */
662
- interface DocumentMetadata {
663
- /** Canonical CELEX. Always present on metadata responses. */
664
- celex?: string;
665
- /** Legacy alias for `celex` (metadata endpoint back-compat). */
666
- celexNumber?: string;
667
- /** `null` when the document is genuinely sparse — never `"Unknown Title"`. */
668
- title?: string | null;
669
- /**
670
- * Present only when `title` is NOT in the requested language: the ISO
671
- * 639-1 code of the language it is in (`en` for the English fallback).
672
- * Absent means the title is in the requested language.
673
- */
674
- titleLanguage?: string;
675
- /** Prose form of the document, e.g. `"Regulation"`. */
676
- documentType?: string | null;
677
- /** Stable enum slug for `documentType` (e.g. `"regulation"`). */
678
- documentTypeCode?: DocumentTypeCode | null;
679
- /** `null` for placeholder authors (e.g. consolidated texts' "Provisional data"). */
680
- author?: string | null;
681
- /** Legacy DD/MM/YYYY string as published by EUR-Lex. Prefer `dateOfDocumentISO`. */
682
- dateOfDocument?: string | null;
683
- /** ISO-8601 date parsed from `dateOfDocument`. */
684
- dateOfDocumentISO?: string | null;
685
- dateOfEffect?: string | null;
686
- dateOfEffectISO?: string | null;
687
- dateOfPublication?: string | null;
688
- dateOfPublicationISO?: string | null;
689
- /** Qualifier EUR-Lex appends to dates (e.g. `"Date of signature"`). */
690
- dateType?: string | null;
691
- /** European Case Law Identifier (recovered from htmlMetadata for sector-6 rows). */
692
- ecli?: string | null;
693
- /** European Legislation Identifier path. */
694
- eli?: string | null;
695
- /** Court case number; joined-case ranges come as one string (`"C-171/24 to C-177/24"`). */
696
- caseNumber?: string | null;
697
- /** Parsed party names from case-law titles. */
698
- parties?: string | null;
699
- /** EUROVOC keywords, deduplicated case-insensitively. */
700
- keywords?: string[];
701
- /** EUR-Lex directory codes (e.g. `"13.30.99.00 Other sectors"`). */
702
- directoryCodes?: string[];
703
- subject?: string[];
704
- }
705
- /** Canonical EUR-Lex URLs for a document. */
706
- interface DocumentUrls {
707
- html?: string;
708
- metadata?: string;
709
- pdf?: string;
710
- xml?: string;
442
+ interface FieldProvenance {
443
+ /** The publisher's wording as extracted by LexAPI. */
444
+ official_source_text?: string[];
445
+ /** Parsed or computed by rule: metadata, identifiers, the in-force fields, the split into articles. */
446
+ machine_extracted_structure?: string[];
447
+ /** Machine-translated text. LexAPI serves none. */
448
+ machine_generated_translation?: string[];
449
+ /** Produced by a model: summaries, similarity scores, extracted outcomes. */
450
+ machine_generated_interpretation?: string[];
451
+ /** Written by LexAPI: notes and attribution statements. */
452
+ editorial_enrichment?: string[];
711
453
  }
712
454
  /** Fully-parsed document: metadata + structured content. */
713
- interface Document extends DocumentMetadata {
455
+ interface Document extends DocumentMetadata, InForceLabel {
714
456
  /** ISO code of the language rendition actually served. */
715
457
  language?: string;
716
458
  /** Present only on a fallback — the language originally requested. */
@@ -728,6 +470,10 @@ interface Document extends DocumentMetadata {
728
470
  fetchedAt?: string;
729
471
  /** Monotonic corpus version of this CELEX (corpus-served documents). */
730
472
  version?: number;
473
+ /** Where the document comes from (API 2.20.0). */
474
+ provenance?: Provenance;
475
+ /** Which fields are the publisher's text and which were derived (API 2.20.0). */
476
+ fieldProvenance?: FieldProvenance;
731
477
  }
732
478
  /**
733
479
  * Response-side document-type slug. The spec enumerates the known values,
@@ -842,7 +588,7 @@ interface SearchResponse extends CreditedResponse, WithResponseHeaders {
842
588
  partial?: boolean;
843
589
  partialReason?: string;
844
590
  /**
845
- * Comma-joined dimensions on which a controller-side post-filter dropped
591
+ * Comma-joined dimensions on which a server-side post-filter dropped
846
592
  * rows (`author`, `date`). `"date"` signals the recall-vs-pagination
847
593
  * trade-off: raise `maxPages` to widen recall on tight date filters.
848
594
  */
@@ -942,8 +688,8 @@ interface RecentDocumentsParams {
942
688
  domain?: Domain;
943
689
  /**
944
690
  * ONE subdomain. A subdomain filter sends the request to EUR-Lex result
945
- * pages, where EUR-Lex reads only the first `DTS_SUBDOM` value
946
- * (lex-api `server/utils/urlBuilder.js`), so the SDK accepts a single value.
691
+ * pages, where EUR-Lex reads only the first `DTS_SUBDOM` value,
692
+ * so the SDK accepts a single value.
947
693
  */
948
694
  subdomain?: Subdomain;
949
695
  /** Result language (default `en`). */
@@ -1004,9 +750,16 @@ interface DocumentMetadataRequest {
1004
750
  interface DocumentMetadataResponse extends CreditedResponse, WithResponseHeaders {
1005
751
  success: boolean;
1006
752
  /** Metadata-only — no `content`. Includes the canonical EUR-Lex URLs. */
1007
- metadata: DocumentMetadata & {
753
+ metadata: DocumentMetadata & InForceLabel & {
1008
754
  /**
1009
- * Sector-3 base acts only, and only when a recent document read already
755
+ * Where the document comes from (API 2.20.0). The response carries no
756
+ * text: `contentHash` is `null`.
757
+ */
758
+ provenance?: Provenance;
759
+ /** Which fields are the publisher's text and which were derived (API 2.20.0). */
760
+ fieldProvenance?: FieldProvenance;
761
+ /**
762
+ * Sector-3 base acts only, and only when a recent document read already
1010
763
  * looked it up (cached ~24 h). Absent means "not looked up", not "none exists".
1011
764
  */
1012
765
  latestConsolidated?: ConsolidatedVersionHint;
@@ -1017,24 +770,143 @@ interface DocumentMetadataResponse extends CreditedResponse, WithResponseHeaders
1017
770
  }
1018
771
  type IdentifierType = "celex" | "url" | "eli" | "ecli";
1019
772
  /**
1020
- * Which resolution path matched. `celex`/`url`/`eli` resolve purely from the
1021
- * identifier; `ecli-corpus` / `eli-corpus` mean a corpus lookup answered.
773
+ * Which resolution path matched. `celex`/`url` resolve purely from the
774
+ * identifier; `ecli-corpus` / `eli-corpus` mean a corpus lookup answered;
775
+ * `eli-cellar` means the ELI was looked up in the Publications Office's
776
+ * Cellar register. `eli` means the CELEX was derived from the ELI's pattern
777
+ * alone (`verified: false` on servers that send `verified`).
1022
778
  */
1023
- type ResolvedVia = "celex" | "url" | "eli" | "ecli-corpus" | "eli-corpus" | (string & {});
779
+ type ResolvedVia = "celex" | "url" | "eli" | "ecli-corpus" | "eli-corpus" | "eli-cellar" | (string & {});
1024
780
  interface ResolveResponse extends CreditedResponse, WithResponseHeaders {
1025
781
  success: boolean;
1026
782
  /** Echo of the caller's input. */
1027
783
  identifier: string;
1028
784
  identifierType: IdentifierType;
1029
785
  resolvedVia: ResolvedVia;
786
+ /**
787
+ * `true` when the corpus or Cellar confirmed the identifier → CELEX mapping.
788
+ * `false` when the CELEX was read off the identifier without a lookup:
789
+ * CELEX and URL inputs (resolve does not check that the document exists),
790
+ * and an ELI resolved from its pattern while Cellar was unreachable — that
791
+ * last kind may name a CELEX that does not exist, so resolve it again later.
792
+ * Absent on servers older than the field.
793
+ */
794
+ verified?: boolean;
1030
795
  celex: string;
1031
796
  urls: DocumentUrls;
1032
797
  }
1033
798
  /**
1034
799
  * Classification of a citation edge. `amendment`, `repeal` and
1035
800
  * `corrigendum` are structural relations (from Cellar for legislation).
801
+ * `transposition` (API 2.11.0): a member-state measure → the EU act it was
802
+ * notified for or records that it transposes. A notified measure is a
803
+ * notification, not a finding that the measure transposes the act, or
804
+ * transposes it completely.
805
+ */
806
+ type CitationType = "reference" | "amendment" | "repeal" | "corrigendum" | "implementation" | "legal-basis" | "proposal" | "transposition";
807
+ /** Every {@link CitationType} value, for building filters or validating input. */
808
+ declare const CITATION_TYPES: readonly ["reference", "amendment", "repeal", "corrigendum", "implementation", "legal-basis", "proposal", "transposition"];
809
+ /**
810
+ * Where an edge comes from (API 2.11.0): `notice` — the EUR-Lex notice page
811
+ * of the citing document; `cellar` — a relation recorded in the Publications
812
+ * Office's Cellar repository; `notice+cellar` — both; `cellar-nim` — a
813
+ * measure a member state notified to the Commission for an EU act (a
814
+ * notification, not a finding that the measure transposes the act);
815
+ * `source` — the national source itself records the relation; `resolver` —
816
+ * the national source records a textual reference that LexAPI's
817
+ * deterministic resolver matched (see {@link CitationResolution}).
818
+ */
819
+ type CitationProvenance = "notice" | "cellar" | "notice+cellar" | "cellar-nim" | "source" | "resolver";
820
+ /** Every {@link CitationProvenance} value. */
821
+ declare const CITATION_PROVENANCES: readonly ["notice", "cellar", "notice+cellar", "cellar-nim", "source", "resolver"];
822
+ /**
823
+ * How the target of a national edge was identified (API 2.11.0): `id` — the
824
+ * source names it by its id or a one-to-one native id; `key` — a unique
825
+ * native key (an official number, a gazette position); `abbreviation` — a
826
+ * code abbreviation matched to its act (filter it out with
827
+ * `resolution: ["id", "key"]` if you need only id and key matches);
828
+ * `text-pattern` — an EU act number with its EU marker found in running
829
+ * text. Edges read from EUR-Lex or Cellar have no resolution (`null`).
830
+ */
831
+ type CitationResolution = "id" | "key" | "abbreviation" | "text-pattern";
832
+ /** Every {@link CitationResolution} value. */
833
+ declare const CITATION_RESOLUTIONS: readonly ["id", "key", "abbreviation", "text-pattern"];
834
+ /**
835
+ * A graph node's kind (API 2.11.0): `act` for an EU act (CELEX sector 3) or a
836
+ * national act, `decision` for an EU court decision (sector 6) or a national
837
+ * decision; `null` for every other CELEX sector.
838
+ */
839
+ type CitationDocumentKind = "act" | "decision";
840
+ /**
841
+ * Where `totalCitations` / `totalEdges` (and the network's paging totals)
842
+ * come from (API 2.10.0): `stats` — the per-node counts the graph maintains
843
+ * with every write; `counted` — counted over the matching edge rows for this
844
+ * request. Both are exact for the request; the totals mean the same either way.
845
+ */
846
+ type CountsSource = "stats" | "counted";
847
+ /**
848
+ * The identity of a graph node (API 2.11.0), on every `citedBy[]` /
849
+ * `cites[]` group, network neighbour, `path[]` node and `related[]` entry.
850
+ * `celexNumber` is unchanged and carries the same id.
851
+ */
852
+ interface CitationNode {
853
+ /** The CELEX number of an EU document; a national document's LexAPI id (`AT-NOR-10001597`). */
854
+ id?: string | null;
855
+ /** `EU` for an EU document, otherwise the upper-case national code (`AT`, `DE`, …). */
856
+ jurisdiction?: string | null;
857
+ documentKind?: CitationDocumentKind | null;
858
+ }
859
+ /**
860
+ * Edge filters shared by `getCites`, `getCitedBy`, `getCitationNetwork`,
861
+ * `getCitationPath` and `getRelatedDocuments` (API 2.11.0). Each takes one
862
+ * value or a list, sent comma-separated. An unknown value is a `400`
863
+ * `InvalidParamsError` naming the parameter (`err.param`) and its allowed
864
+ * values (`err.allowed`), refunded in full.
865
+ */
866
+ interface CitationFilterParams {
867
+ /** Keep only edges of these types (one value or a list). */
868
+ citationType?: OneOrMany<CitationType>;
869
+ /**
870
+ * Keep only edges with these provenances. `cellar-nim`, `source` and
871
+ * `resolver` are accepted only while a national jurisdiction is open to you.
872
+ */
873
+ provenance?: OneOrMany<CitationProvenance>;
874
+ /**
875
+ * Keep only neighbours in these jurisdictions: `eu` and the lower-case
876
+ * codes of the national jurisdictions open to you (`["eu", "at"]`). A
877
+ * national code asks for national documents exactly like
878
+ * `includeNational: true`, with the same plan gate (BUSINESS, SCALE and
879
+ * ENTERPRISE; `403 TierForbiddenError` below). Any other code is a `400`.
880
+ */
881
+ jurisdictions?: OneOrMany<string>;
882
+ /**
883
+ * Keep only edges whose target was identified by one of these methods
884
+ * (national edges only — EU edges never match). While no national
885
+ * jurisdiction is open to you every value is a `400`.
886
+ */
887
+ resolution?: OneOrMany<CitationResolution>;
888
+ }
889
+ /**
890
+ * A reference a national document records that LexAPI could not turn into
891
+ * an edge (API 2.11.0) — `unresolved: true` on `getCites` /
892
+ * `getCitationNetwork` for a national document id.
1036
893
  */
1037
- type CitationType = "reference" | "amendment" | "repeal" | "corrigendum" | "implementation" | "legal-basis" | "proposal";
894
+ interface UnresolvedReference {
895
+ /** What the source recorded: a cited norm, an EU act, a relation field, a notified measure. */
896
+ kind: "norm" | "eu-act" | "relation" | "nim" | (string & {});
897
+ /** The source's own string (at most 500 characters). */
898
+ text: string;
899
+ /** What the resolver understood of `text`; `null` when nothing. */
900
+ parsedKey: Record<string, unknown> | null;
901
+ /**
902
+ * `unresolved` — not matched; `not-held` — identified, but LexAPI does not
903
+ * hold it; `ambiguous` — more than one candidate; `out-of-scope` — a target
904
+ * outside the graph.
905
+ */
906
+ status: "unresolved" | "not-held" | "ambiguous" | "out-of-scope" | (string & {});
907
+ /** The id the target would have, when it could be built and is visible to you. */
908
+ targetId: string | null;
909
+ }
1038
910
  /**
1039
911
  * Where a neighbour's title came from: the corpus (in the requested
1040
912
  * language, or another language), a citation row, the edge itself, or
@@ -1090,9 +962,13 @@ interface CitationEdgeDetail {
1090
962
  citationType?: CitationType;
1091
963
  contextSnippet?: string | null;
1092
964
  extractedAt?: string;
965
+ /** Where the edge comes from (API 2.11.0); `null` on a national edge not yet classified. */
966
+ provenance?: CitationProvenance | null;
967
+ /** How the target was identified (API 2.11.0); `null` on every EUR-Lex / Cellar edge. */
968
+ resolution?: CitationResolution | null;
1093
969
  }
1094
970
  /** All edges from one source document into the target (cited-by grouping). */
1095
- interface CitingDocumentGroup {
971
+ interface CitingDocumentGroup extends CitationNode {
1096
972
  celexNumber?: string;
1097
973
  title?: string | null;
1098
974
  titleSource?: TitleSource;
@@ -1105,50 +981,90 @@ interface CitingDocumentGroup {
1105
981
  citations?: CitationEdgeDetail[];
1106
982
  }
1107
983
  /** All edges from the source document into one target (cites grouping). */
1108
- interface CitedDocumentGroup {
984
+ interface CitedDocumentGroup extends CitationNode {
1109
985
  celexNumber?: string;
1110
986
  title?: string | null;
1111
987
  titleSource?: TitleSource;
1112
988
  citationCount?: number;
1113
989
  citations?: CitationEdgeDetail[];
1114
990
  }
1115
- /** Pagination filters shared by the cites / cited-by endpoints. */
1116
- interface CitationEdgeParams {
1117
- /** Filter to a single citation type. */
1118
- citationType?: CitationType;
991
+ /** Pagination and filters shared by the cites / cited-by endpoints. */
992
+ interface CitationEdgeParams extends CitationFilterParams {
1119
993
  /** Max edges to return per page. Default 100. */
1120
994
  limit?: number;
1121
995
  /** Pagination offset (in edges, not documents). Default 0. */
1122
996
  offset?: number;
1123
997
  /** Language preferred for neighbour titles (default `en`). */
1124
998
  language?: Language;
999
+ /**
1000
+ * Also return national documents of live jurisdictions as neighbours
1001
+ * (national acts/decisions that cite, implement or are cited by the EU
1002
+ * graph, where the national source records the link). BUSINESS, SCALE
1003
+ * and ENTERPRISE only — `403 TierForbiddenError` below that. A `celexNumber`
1004
+ * that is itself a national id (`AT-…`) includes national neighbours
1005
+ * without this flag.
1006
+ */
1007
+ includeNational?: boolean;
1008
+ }
1009
+ /** Params for {@link getCites}: the shared edge params plus `unresolved`. */
1010
+ interface CitesParams extends CitationEdgeParams {
1011
+ /**
1012
+ * `true` on a national document id adds `unresolved` /
1013
+ * `unresolvedTruncated` to the response — the references the document
1014
+ * records that could not be turned into an edge. Ignored on an EU id. No
1015
+ * extra credits.
1016
+ */
1017
+ unresolved?: boolean;
1125
1018
  }
1126
1019
  interface CitedByResponse extends CreditedResponse, WithResponseHeaders {
1127
1020
  success: boolean;
1128
1021
  /** The CELEX whose inbound edges are being listed. */
1129
1022
  targetDocument: string;
1130
- /** Total inbound edges matching the filter (across all pages). */
1023
+ /** Distinct citing→cited document pairs matching the filter (across all pages). */
1131
1024
  totalCitations?: number;
1025
+ /** Edge rows matching the filter — what `offset` / `limit` page over. */
1026
+ totalEdges?: number;
1027
+ /** Where the totals come from (API 2.10.0). */
1028
+ countsSource?: CountsSource;
1132
1029
  /** Citing documents in THIS page (not the global distinct total). */
1133
1030
  uniqueDocuments?: number;
1134
1031
  limit?: number;
1135
1032
  offset?: number;
1136
1033
  citedBy: CitingDocumentGroup[];
1137
1034
  relationSync?: RelationSync;
1035
+ /** Whether national documents were included (see `includeNational`). Absent while no national jurisdiction is live. */
1036
+ includeNational?: boolean;
1138
1037
  }
1139
1038
  interface CitesResponse extends CreditedResponse, WithResponseHeaders {
1140
1039
  success: boolean;
1141
1040
  /** The CELEX whose outbound edges are being listed. */
1142
1041
  sourceDocument: string;
1042
+ /** Distinct citing→cited document pairs matching the filter (across all pages). */
1143
1043
  totalCitations?: number;
1044
+ /** Edge rows matching the filter — what `offset` / `limit` page over. */
1045
+ totalEdges?: number;
1046
+ /** Where the totals come from (API 2.10.0). */
1047
+ countsSource?: CountsSource;
1144
1048
  /** Cited documents in THIS page (not the global distinct total). */
1145
1049
  uniqueDocuments?: number;
1146
1050
  limit?: number;
1147
1051
  offset?: number;
1148
1052
  cites: CitedDocumentGroup[];
1053
+ /** Whether national documents were included (see `includeNational`). Absent while no national jurisdiction is live. */
1054
+ includeNational?: boolean;
1055
+ /** With `unresolved: true` on a national document id: references that did not become an edge (at most 500). */
1056
+ unresolved?: UnresolvedReference[];
1057
+ /** `true` when the document has more than 500 such references. With `unresolved` only. */
1058
+ unresolvedTruncated?: boolean;
1059
+ }
1060
+ /** One distinct (`citationType`, `provenance`, `resolution`) combination of a neighbour's edges (API 2.11.0). */
1061
+ interface CitationEdgeKind {
1062
+ citationType: CitationType;
1063
+ provenance: CitationProvenance | null;
1064
+ resolution: CitationResolution | null;
1149
1065
  }
1150
1066
  /** A neighbour in the citation graph, deduplicated across edge types. */
1151
- interface CitationNeighbour {
1067
+ interface CitationNeighbour extends CitationNode {
1152
1068
  celexNumber?: string;
1153
1069
  title?: string | null;
1154
1070
  titleSource?: TitleSource;
@@ -1156,16 +1072,20 @@ interface CitationNeighbour {
1156
1072
  count?: number;
1157
1073
  /** Union of `citationType` values across all edges to/from it. */
1158
1074
  types?: CitationType[];
1075
+ /** The distinct type / provenance / resolution of this page's edges to/from the neighbour (API 2.11.0). */
1076
+ edgeDetails?: CitationEdgeKind[];
1159
1077
  }
1160
- interface CitationNetworkParams {
1161
- /** Filter both directions to a single citation type. */
1162
- citationType?: CitationType;
1078
+ interface CitationNetworkParams extends CitationFilterParams {
1163
1079
  /** Max edges to fetch per direction (default 100, max 500). */
1164
1080
  limit?: number;
1165
1081
  /** Pagination offset (in edges, applied to both directions). */
1166
1082
  offset?: number;
1167
1083
  /** Language preferred for neighbour titles (default `en`). */
1168
1084
  language?: Language;
1085
+ /** Also include national neighbours of live jurisdictions. BUSINESS+ only — `403 TierForbiddenError` below that. */
1086
+ includeNational?: boolean;
1087
+ /** `true` on a national document id adds `unresolved` / `unresolvedTruncated` (not on a partial response). No extra credits. */
1088
+ unresolved?: boolean;
1169
1089
  }
1170
1090
  interface CitationNetworkResponse extends CreditedResponse, WithResponseHeaders {
1171
1091
  success: boolean;
@@ -1188,6 +1108,12 @@ interface CitationNetworkResponse extends CreditedResponse, WithResponseHeaders
1188
1108
  citesTotal: number | null;
1189
1109
  /** Total inbound edges matching the query. `null` when the response is partial. */
1190
1110
  citedByTotal: number | null;
1111
+ /** Outbound edge ROWS — what `offset` pages over. `null` when partial. */
1112
+ citesEdgeTotal?: number | null;
1113
+ /** Inbound edge ROWS — what `offset` pages over. `null` when partial. */
1114
+ citedByEdgeTotal?: number | null;
1115
+ /** Where the totals come from (API 2.10.0); `null` when partial. */
1116
+ countsSource?: CountsSource | null;
1191
1117
  };
1192
1118
  /**
1193
1119
  * Present and `true` when the server-side wall-clock budget expired —
@@ -1200,6 +1126,12 @@ interface CitationNetworkResponse extends CreditedResponse, WithResponseHeaders
1200
1126
  /** The server-side budget that expired (only on partial responses). */
1201
1127
  timeoutMs?: number;
1202
1128
  relationSync?: RelationSync;
1129
+ /** Whether national neighbours were included (see `includeNational`). Absent while no national jurisdiction is live. */
1130
+ includeNational?: boolean;
1131
+ /** With `unresolved: true` on a national document id: references that did not become an edge (at most 500). */
1132
+ unresolved?: UnresolvedReference[];
1133
+ /** `true` when the document has more than 500 such references. With `unresolved` only. */
1134
+ unresolvedTruncated?: boolean;
1203
1135
  }
1204
1136
  interface CitationStatsTopCited {
1205
1137
  celexNumber?: string;
@@ -1211,8 +1143,15 @@ interface CitationStatsTopCiting {
1211
1143
  title?: string | null;
1212
1144
  citesCount?: number;
1213
1145
  }
1146
+ /** Params for {@link getCitationStats}. */
1147
+ interface CitationStatsParams {
1148
+ /** Also count national documents of live jurisdictions. BUSINESS+ only — `403 TierForbiddenError` below that. */
1149
+ includeNational?: boolean;
1150
+ }
1214
1151
  interface CitationStatsResponse extends CreditedResponse, WithResponseHeaders {
1215
1152
  success: boolean;
1153
+ /** Whether national documents were counted (see `includeNational`). Absent while no national jurisdiction is live. */
1154
+ includeNational?: boolean;
1216
1155
  stats: {
1217
1156
  totalCitations: number;
1218
1157
  uniqueSourceDocuments: number;
@@ -1221,23 +1160,55 @@ interface CitationStatsResponse extends CreditedResponse, WithResponseHeaders {
1221
1160
  mostCited: CitationStatsTopCited[];
1222
1161
  /** Top-10 documents with the most outbound citations. */
1223
1162
  mostCiting: CitationStatsTopCiting[];
1163
+ /**
1164
+ * With `includeNational: true` only (API 2.11.0): per jurisdiction (`EU`
1165
+ * and each live one in scope), the edges whose citing end (`asSource`) or
1166
+ * cited end (`asTarget`) is in it. Unclassified edges are counted under
1167
+ * `unstamped`, only while there are any.
1168
+ */
1169
+ byJurisdiction?: Record<string, {
1170
+ asSource?: number;
1171
+ asTarget?: number;
1172
+ }>;
1173
+ /** With `includeNational: true` only: edges per `provenance` value (`unstamped` while edges remain unclassified). */
1174
+ byProvenance?: Record<string, number>;
1175
+ /**
1176
+ * With `includeNational: true` only: the measures the in-scope member
1177
+ * states notified to the Commission that Cellar still lists, and how many
1178
+ * are matched to a document LexAPI holds — the same rule as `counts` on
1179
+ * {@link TranspositionResponse}.
1180
+ */
1181
+ transposition?: {
1182
+ measures?: number;
1183
+ resolved?: number;
1184
+ byCountry?: Record<string, {
1185
+ measures?: number;
1186
+ resolved?: number;
1187
+ }>;
1188
+ };
1224
1189
  };
1225
1190
  /** When these (cached) statistics were computed. */
1226
1191
  cachedAt?: string;
1227
1192
  /** How long the statistics are cached, in seconds. */
1228
1193
  cacheTtlSeconds?: number;
1229
1194
  }
1230
- interface CitationPathNode {
1195
+ interface CitationPathNode extends CitationNode {
1231
1196
  celexNumber: string;
1232
1197
  /** Enriched at read time from the corpus where available. */
1233
1198
  title: string | null;
1234
1199
  titleSource?: TitleSource;
1235
1200
  }
1236
- interface CitationPathParams {
1201
+ interface CitationPathParams extends CitationFilterParams {
1237
1202
  /** Hop budget (default 3, max 8). */
1238
1203
  maxDepth?: number;
1239
1204
  /** Language preferred for node titles (default `en`). */
1240
1205
  language?: Language;
1206
+ /**
1207
+ * Also follow national documents of live jurisdictions. BUSINESS+ only —
1208
+ * `403 TierForbiddenError` below that. `from`/`to` may themselves be
1209
+ * national ids (`AT-…`) regardless of this flag.
1210
+ */
1211
+ includeNational?: boolean;
1241
1212
  }
1242
1213
  interface CitationPathResponse extends CreditedResponse, WithResponseHeaders {
1243
1214
  success: boolean;
@@ -1252,8 +1223,10 @@ interface CitationPathResponse extends CreditedResponse, WithResponseHeaders {
1252
1223
  path: CitationPathNode[];
1253
1224
  /** Present when `found` is false. */
1254
1225
  message?: string;
1226
+ /** Whether national documents were followed (see `includeNational`). Absent while no national jurisdiction is live. */
1227
+ includeNational?: boolean;
1255
1228
  }
1256
- interface RelatedDocument {
1229
+ interface RelatedDocument extends CitationNode {
1257
1230
  celexNumber: string;
1258
1231
  title?: string | null;
1259
1232
  titleSource?: TitleSource;
@@ -1261,11 +1234,13 @@ interface RelatedDocument {
1261
1234
  sharedCount: number;
1262
1235
  sharedTargets?: string[];
1263
1236
  }
1264
- interface RelatedDocumentsParams {
1237
+ interface RelatedDocumentsParams extends CitationFilterParams {
1265
1238
  /** Max neighbours (default 10, max 50). */
1266
1239
  limit?: number;
1267
1240
  /** Language preferred for titles (default `en`). */
1268
1241
  language?: Language;
1242
+ /** Also consider national documents of live jurisdictions. BUSINESS+ only — `403 TierForbiddenError` below that. */
1243
+ includeNational?: boolean;
1269
1244
  }
1270
1245
  interface RelatedDocumentsResponse extends CreditedResponse, WithResponseHeaders {
1271
1246
  success: boolean;
@@ -1277,6 +1252,186 @@ interface RelatedDocumentsResponse extends CreditedResponse, WithResponseHeaders
1277
1252
  related: RelatedDocument[];
1278
1253
  /** Present when the seed has no outbound citations to couple on. */
1279
1254
  message?: string;
1255
+ /** Whether national documents were considered (see `includeNational`). Absent while no national jurisdiction is live. */
1256
+ includeNational?: boolean;
1257
+ }
1258
+ /** Params for {@link getTransposition}. */
1259
+ interface TranspositionParams {
1260
+ /**
1261
+ * Countries to list, ISO-2 codes (`["es", "cz"]`; `EL` for Greece, `UK`
1262
+ * for the United Kingdom); default all 28. `eu` is accepted and ignored;
1263
+ * an unknown code is a `400`.
1264
+ */
1265
+ jurisdictions?: OneOrMany<string>;
1266
+ /**
1267
+ * `true`: only the measures resolved to a document LexAPI holds, in live
1268
+ * jurisdictions. Does nothing when holdings are not joined (below
1269
+ * BUSINESS, or `termsRequired`).
1270
+ */
1271
+ resolvedOnly?: boolean;
1272
+ /** Language of the act's title (default `en`). */
1273
+ language?: Language;
1274
+ }
1275
+ /**
1276
+ * One notified measure for an EU act (API 2.11.0) — the same keys for every
1277
+ * country; a field the record lacks is `null`. `id`, `resolved`,
1278
+ * `resolution` and `resolutionBasis` come from LexAPI's holdings: filled on
1279
+ * BUSINESS, SCALE and ENTERPRISE for a live jurisdiction, `null` otherwise.
1280
+ */
1281
+ interface TranspositionMeasure {
1282
+ /** The LexAPI id of the document the measure resolves to, when held and not withdrawn. */
1283
+ id: string | null;
1284
+ /** Whether the measure is matched to a document LexAPI holds; `null` when holdings are not joined. */
1285
+ resolved: boolean | null;
1286
+ resolution: CitationResolution | null;
1287
+ /** What the match used (e.g. the gazette number); `null` when not resolved or not joined. */
1288
+ resolutionBasis: {
1289
+ keyKind?: string;
1290
+ key?: string;
1291
+ } | null;
1292
+ /**
1293
+ * `cellar-nim` — the Cellar record of the member state's notification;
1294
+ * `source` — the national source itself records that the document
1295
+ * transposes or implements the act (`cellar` is then `null`).
1296
+ */
1297
+ provenance: "cellar-nim" | "source" | (string & {});
1298
+ /** `transposition` when Cellar types the act as a directive or framework decision, else `implementation`. */
1299
+ citationType: "transposition" | "implementation" | (string & {});
1300
+ /** The measure's title as notified, in the member state's language. */
1301
+ title: string | null;
1302
+ /** The kind of measure as notified (`Ley Orgánica`, `Zákon`, …). */
1303
+ typeAct: string | null;
1304
+ /** Where the measure was published, as notified. */
1305
+ officialJournal: {
1306
+ name?: string | null;
1307
+ number?: string | null;
1308
+ date?: string | null;
1309
+ };
1310
+ /** The member state's own reference for the measure. */
1311
+ reference: string | null;
1312
+ eli: string | null;
1313
+ /** A link to the measure, as notified. */
1314
+ link: string | null;
1315
+ /** The Cellar record of the notification; `null` on a measure only a national source records. */
1316
+ cellar: {
1317
+ id?: string | null;
1318
+ /** The record's sector-7 CELEX number for this act; `null` when it has none (never guessed). */
1319
+ celex?: string | null;
1320
+ /** Not mirrored — always `null`. */
1321
+ commissionReference?: null;
1322
+ dateDocument?: string | null;
1323
+ dateNotification?: string | null;
1324
+ entryIntoForce?: string | null;
1325
+ } | null;
1326
+ }
1327
+ /** One country's measures for the act. */
1328
+ interface TranspositionCountry {
1329
+ /** Upper-case code of the member state (`EL` for Greece), or `UK`. */
1330
+ jurisdiction: string;
1331
+ /** Whether LexAPI serves this country's national law (the same `live` as `getNationalCoverage`). */
1332
+ live: boolean;
1333
+ counts: {
1334
+ /** Measures for the act in this country (not only those in this page). */
1335
+ measures?: number;
1336
+ /** Of those, matched to a document LexAPI holds; `null` when holdings are not joined. */
1337
+ resolved?: number | null;
1338
+ };
1339
+ measures: TranspositionMeasure[];
1340
+ }
1341
+ /** `GET /citations/transposition/{celexNumber}` (API 2.11.0). */
1342
+ interface TranspositionResponse extends CreditedResponse, WithResponseHeaders {
1343
+ success: boolean;
1344
+ /** `true` when LexAPI's holdings are joined, `false` otherwise. Absent while no national jurisdiction is live. */
1345
+ includeNational?: boolean;
1346
+ /**
1347
+ * Present (`true`) only when holdings would be joined but the account has
1348
+ * not yet accepted the national-source terms: every holdings field is
1349
+ * then `null`. Accept the terms once in the dashboard.
1350
+ */
1351
+ termsRequired?: true;
1352
+ document: {
1353
+ id?: string;
1354
+ celexNumber?: string;
1355
+ jurisdiction?: "EU" | (string & {});
1356
+ documentKind?: "act" | (string & {});
1357
+ title?: string | null;
1358
+ };
1359
+ source: {
1360
+ cellar?: {
1361
+ /** When the newest of the act's records was last read from Cellar; `null` when the act has none. */
1362
+ syncedAt?: string | null;
1363
+ /** All the act's measures across every country (not narrowed by `jurisdictions`). */
1364
+ measures?: number;
1365
+ /** The attribution the Publications Office's reuse terms require — keep it with anything you republish. */
1366
+ attribution?: string;
1367
+ };
1368
+ /** The live jurisdictions whose own sources record a transposition or implementation of this act; `null` when holdings are not joined. */
1369
+ lanes?: string[] | null;
1370
+ };
1371
+ /**
1372
+ * Always: "Measures are those the member state notified to the Commission
1373
+ * for this act. A notification is not a finding that the measure
1374
+ * transposes the act, or transposes it completely."
1375
+ */
1376
+ note: string;
1377
+ /** Per country with at least one measure (in the `jurisdictions` asked for), in code order. */
1378
+ jurisdictions: TranspositionCountry[];
1379
+ /** `true` when more than 2,000 measures matched (narrow with `jurisdictions`), or the national-source edge cap was hit. */
1380
+ truncated: boolean;
1381
+ }
1382
+ /** Params for {@link getCounterparts}. */
1383
+ interface CounterpartsParams {
1384
+ /** Jurisdictions to look in, ISO-2 codes; default every live one. Codes that are not live are left out; an unknown code is a `400`. */
1385
+ jurisdictions?: OneOrMany<string>;
1386
+ /** Language of the titles (default `en`). */
1387
+ language?: Language;
1388
+ }
1389
+ /** A measure of another live jurisdiction for the same EU act. */
1390
+ interface Counterpart {
1391
+ jurisdiction: string;
1392
+ /** The LexAPI id of the counterpart; `null` for a notified Cellar record LexAPI does not hold (rank 3). */
1393
+ id: string | null;
1394
+ resolved: boolean;
1395
+ title: string | null;
1396
+ citationType: "transposition" | "implementation" | (string & {});
1397
+ provenance: "source" | "cellar-nim" | (string & {});
1398
+ /**
1399
+ * `1` — the national source records the relation (`source`); `2` — a
1400
+ * notified measure LexAPI holds (`cellar-nim`, resolved); `3` — a notified
1401
+ * Cellar record LexAPI does not hold.
1402
+ */
1403
+ rank: 1 | 2 | 3;
1404
+ }
1405
+ /** One EU act the queried document transposes or implements, with the other jurisdictions' measures for it. */
1406
+ interface CounterpartVia {
1407
+ euAct: CitationNode & {
1408
+ title?: string | null;
1409
+ /** Measures all member states notified for the act. */
1410
+ notifiedMeasures?: number;
1411
+ };
1412
+ /** The document's own edge to the act; `null` when the queried id is the EU act itself. */
1413
+ edge: {
1414
+ citationType?: "transposition" | "implementation" | (string & {});
1415
+ provenance?: CitationProvenance | null;
1416
+ resolution?: CitationResolution | null;
1417
+ } | null;
1418
+ /** By `rank`, then jurisdiction; at most 200. Never the queried document. */
1419
+ counterparts: Counterpart[];
1420
+ /** `true` when more than 200 counterparts matched for this act. */
1421
+ truncated: boolean;
1422
+ }
1423
+ /** `GET /citations/counterparts/{id}` (API 2.11.0). */
1424
+ interface CounterpartsResponse extends CreditedResponse, WithResponseHeaders {
1425
+ success: boolean;
1426
+ /** Always `true` when present; absent while no national jurisdiction is live. */
1427
+ includeNational?: boolean;
1428
+ document: CitationNode & {
1429
+ title?: string | null;
1430
+ };
1431
+ /** One entry per EU act the document transposes or implements (CELEX order, at most 200); for an EU act as id, the act itself. */
1432
+ via: CounterpartVia[];
1433
+ /** `true` when the document implements more than 200 EU acts. */
1434
+ truncated: boolean;
1280
1435
  }
1281
1436
  /** Languages accepted by the semantic endpoints (narrower than `Language`). */
1282
1437
  type SemanticLanguage = "en" | "fr" | "de" | "es" | "it" | "sl" | "el" | "nl" | "pt" | "pl";
@@ -1337,6 +1492,43 @@ interface SemanticLegislationSearchOptions extends SemanticSearchOptions {
1337
1492
  * invalid `asOf` is a 400 (refunded in full).
1338
1493
  */
1339
1494
  asOf?: string;
1495
+ /**
1496
+ * `true`: only hits whose act is known to be in force today (UTC); hits not
1497
+ * in force and hits with unknown status are removed and counted in the
1498
+ * response's `inForceFilter`, so the page can come back shorter than
1499
+ * `limit`. With `asOf` the filter is still about today (API 2.19.0).
1500
+ */
1501
+ inForce?: boolean;
1502
+ }
1503
+ /**
1504
+ * Why a semantic case-law hit carries no `text` (API 2.30.0). Not the
1505
+ * document reasons ({@link TextUnavailableReason}): a hit never carries
1506
+ * those, and a document never carries `not_in_corpus`.
1507
+ *
1508
+ * - `not_in_corpus` — LexAPI does not hold the text of this document in the
1509
+ * hit's language. `getDocument` with `metadata.celex_id` reads it (a
1510
+ * separately charged read).
1511
+ * - `unknown` — LexAPI could not check its copy for this request; retrying
1512
+ * the search may return the text.
1513
+ *
1514
+ * Open: later API versions may add values, so do not switch on it
1515
+ * exhaustively.
1516
+ */
1517
+ type SemanticHitTextUnavailableReason = "not_in_corpus" | "unknown" | (string & {});
1518
+ /**
1519
+ * Whether a semantic case-law hit carries `text`, and if not, why
1520
+ * (`semanticSearch` with `includeText: true`, API 2.30.0). Not the
1521
+ * document {@link TextAvailability}: same name on the wire, other reasons.
1522
+ * Absent on `nationalSemanticSearch` hits.
1523
+ */
1524
+ interface SemanticHitTextAvailability {
1525
+ /**
1526
+ * `true`: the hit carries `text`. `false`: it carries `snippet` instead —
1527
+ * the head of the machine-written `summary`, not court text.
1528
+ */
1529
+ available: boolean;
1530
+ /** Absent when `available` is true. An open string: future values are possible. */
1531
+ reason?: SemanticHitTextUnavailableReason;
1340
1532
  }
1341
1533
  /** Single case-law match from `/search/semantic`. */
1342
1534
  interface SemanticCaseLawResult {
@@ -1348,10 +1540,24 @@ interface SemanticCaseLawResult {
1348
1540
  case_id?: string | null;
1349
1541
  /** Cosine similarity, 0–1. */
1350
1542
  score?: number;
1351
- /** Full matched-document text — present ONLY with `includeText: true`. */
1543
+ /**
1544
+ * Full matched-document text — present ONLY with `includeText: true`, on
1545
+ * hits that have it (`textAvailability.available: true`). A blank `text`
1546
+ * from the index is passed through and counts as no text.
1547
+ */
1352
1548
  text?: string;
1353
- /** ~600-character preview — present by default (replaced by `text` with `includeText`). */
1549
+ /**
1550
+ * ~600-character preview — present by default. With `includeText: true`,
1551
+ * present only on hits without text (API 2.30.0).
1552
+ */
1354
1553
  snippet?: string;
1554
+ /**
1555
+ * With `includeText: true` only (API 2.30.0), on every `semanticSearch`
1556
+ * hit: whether it carries `text`, and if not, why (`reason` is open — do
1557
+ * not switch on it exhaustively). Absent without `includeText`, and absent
1558
+ * on `nationalSemanticSearch` hits.
1559
+ */
1560
+ textAvailability?: SemanticHitTextAvailability;
1355
1561
  case_name?: string | null;
1356
1562
  case_number?: string | null;
1357
1563
  ecli?: string | null;
@@ -1381,6 +1587,8 @@ interface SemanticCaseLawResult {
1381
1587
  extraction_confidence?: number;
1382
1588
  extraction_model?: string;
1383
1589
  extracted_at?: string;
1590
+ /** Which fields of the hit are the publisher's text and which were derived (API 2.20.0). */
1591
+ fieldProvenance?: FieldProvenance;
1384
1592
  /** Always includes `celex_id` when available — the persistent identity key. */
1385
1593
  metadata?: {
1386
1594
  celex_id?: string;
@@ -1391,6 +1599,11 @@ interface SemanticCaseLawResult {
1391
1599
  };
1392
1600
  [key: string]: unknown;
1393
1601
  }
1602
+ /** A `semanticSearch` hit (EU case law), with the provenance of its document. */
1603
+ interface EuSemanticCaseLawResult extends SemanticCaseLawResult {
1604
+ /** Where the document comes from (API 2.20.0); `retrievedAt` and `contentHash` are `null` on hits. */
1605
+ provenance?: Provenance;
1606
+ }
1394
1607
  /** Semantic-specific quota counters (legacy daily-call plans only). */
1395
1608
  interface SemanticUsageInfo {
1396
1609
  current?: number;
@@ -1404,7 +1617,7 @@ interface SemanticCaseLawSearchResponse extends CreditedResponse, WithResponseHe
1404
1617
  searchType?: "semantic-case-law";
1405
1618
  query?: string;
1406
1619
  resultCount?: number;
1407
- results: SemanticCaseLawResult[];
1620
+ results: EuSemanticCaseLawResult[];
1408
1621
  /**
1409
1622
  * Present only on best-effort responses (low-confidence hits) — its
1410
1623
  * presence is itself the low-confidence signal. Omitted (never `null`) otherwise.
@@ -1418,6 +1631,8 @@ interface SemanticCaseLawSearchResponse extends CreditedResponse, WithResponseHe
1418
1631
  hyde?: boolean;
1419
1632
  /** Present only when HyDE ran: the LLM-drafted hypothetical judgment passage. */
1420
1633
  hypotheticalDocument?: string;
1634
+ /** Present only with `hypotheticalDocument`, which it marks as `machine_generated_interpretation` (API 2.20.0). */
1635
+ fieldProvenance?: FieldProvenance;
1421
1636
  /** Opaque upstream pass-through; shape not stable — use `tookMs` for timing. */
1422
1637
  metadata?: Record<string, unknown>;
1423
1638
  /** Server-measured wall-clock time for this request, in ms. */
@@ -1434,6 +1649,8 @@ interface SemanticCaseLawSearchResponse extends CreditedResponse, WithResponseHe
1434
1649
  * - `no_longer_in_force` — `asOf` is after the act's end of validity.
1435
1650
  * - `in_force_dates_unknown` — the act's in-force dates could not be established.
1436
1651
  * - `not_in_language` — the version in force has no text in that language.
1652
+ * - `amendment_not_consolidated` — an act amending the act may have applied on that date, and no
1653
+ * consolidated version listed for the date is known to include it.
1437
1654
  * - `text_unavailable` — the version in force has no text.
1438
1655
  * - `article_not_in_version` — that article/annex/recital does not exist in the version in force.
1439
1656
  * - `part_not_resolvable` — the match is a part that cannot be looked up by date (e.g. a table).
@@ -1448,10 +1665,13 @@ interface SemanticCaseLawSearchResponse extends CreditedResponse, WithResponseHe
1448
1665
  * - `insufficient_credits` — the credit pool could not cover that fetch.
1449
1666
  * - `credit_check_failed` — the credit check did not answer; no fetch was made.
1450
1667
  */
1451
- type AsOfReason = "not_yet_adopted" | "not_yet_in_force" | "no_longer_in_force" | "in_force_dates_unknown" | "not_in_language" | "text_unavailable" | "article_not_in_version" | "part_not_resolvable" | "article_unknown" | "version_list_unavailable" | "version_lookup_cap" | "fetch_budget_exhausted" | "fetch_pending" | "fetch_capacity" | "fetch_failed" | "fetch_timeout" | "request_deadline" | "insufficient_credits" | "credit_check_failed" | (string & {});
1452
- /** Every documented {@link AsOfReason} value, in spec order (runtime list). */
1453
- declare const AS_OF_REASONS: readonly ["not_yet_adopted", "not_yet_in_force", "no_longer_in_force", "in_force_dates_unknown", "not_in_language", "text_unavailable", "article_not_in_version", "part_not_resolvable", "article_unknown", "version_list_unavailable", "version_lookup_cap", "fetch_budget_exhausted", "fetch_pending", "fetch_capacity", "fetch_failed", "fetch_timeout", "request_deadline", "insufficient_credits", "credit_check_failed"];
1454
- /** The version an `asOf` hit's text comes from. */
1668
+ type AsOfReason = "not_yet_adopted" | "not_yet_in_force" | "no_longer_in_force" | "in_force_dates_unknown" | "not_in_language" | "amendment_not_consolidated" | "text_unavailable" | "article_not_in_version" | "part_not_resolvable" | "article_unknown" | "version_list_unavailable" | "version_lookup_cap" | "fetch_budget_exhausted" | "fetch_pending" | "fetch_capacity" | "fetch_failed" | "fetch_timeout" | "request_deadline" | "insufficient_credits" | "credit_check_failed" | (string & {});
1669
+ /**
1670
+ * Every documented {@link AsOfReason} value, in spec order (runtime list).
1671
+ * For `semanticLegislationSearch` with `asOf`; `legislationAsOf` has {@link AS_OF_LOOKUP_REASONS}.
1672
+ */
1673
+ declare const AS_OF_REASONS: readonly ["not_yet_adopted", "not_yet_in_force", "no_longer_in_force", "in_force_dates_unknown", "not_in_language", "amendment_not_consolidated", "text_unavailable", "article_not_in_version", "part_not_resolvable", "article_unknown", "version_list_unavailable", "version_lookup_cap", "fetch_budget_exhausted", "fetch_pending", "fetch_capacity", "fetch_failed", "fetch_timeout", "request_deadline", "insufficient_credits", "credit_check_failed"];
1674
+ /** The version an EU `asOf` hit's text comes from (national hits: {@link NationalAsOfVersion}). */
1455
1675
  interface AsOfVersion {
1456
1676
  celex?: string;
1457
1677
  /** Consolidation date; `null` for the act as published. */
@@ -1512,15 +1732,37 @@ interface SemanticLegislationResult {
1512
1732
  law_id?: string;
1513
1733
  consolidatedAsOf?: string | null;
1514
1734
  };
1735
+ /** Which fields of the hit are the publisher's text and which were derived (API 2.20.0). */
1736
+ fieldProvenance?: FieldProvenance;
1515
1737
  metadata?: Record<string, unknown>;
1516
1738
  [key: string]: unknown;
1517
1739
  }
1740
+ /**
1741
+ * A `semanticLegislationSearch` hit (EU legislation): the article-level match
1742
+ * plus the in-force label of its act (API 2.19.0) and its provenance.
1743
+ */
1744
+ interface EuSemanticLegislationResult extends SemanticLegislationResult, InForceLabel {
1745
+ /** Where the document comes from (API 2.20.0); `retrievedAt` and `contentHash` are `null` on hits. */
1746
+ provenance?: Provenance;
1747
+ }
1518
1748
  interface SemanticLegislationSearchResponse extends CreditedResponse, WithResponseHeaders {
1519
1749
  success: boolean;
1520
1750
  searchType?: "semantic-legislation";
1521
1751
  query?: string;
1522
1752
  resultCount?: number;
1523
- results: SemanticLegislationResult[];
1753
+ results: EuSemanticLegislationResult[];
1754
+ /**
1755
+ * Present only when the request set `inForce: true` (API 2.19.0): the hits
1756
+ * the filter removed that you would otherwise have seen. When
1757
+ * `removedUnknown` is above 0 the response also carries a `hint`: unknown
1758
+ * can be temporary.
1759
+ */
1760
+ inForceFilter?: {
1761
+ /** Removed because their act is not in force today. */
1762
+ removedNotInForce?: number;
1763
+ /** Removed because their in-force status is unknown. */
1764
+ removedUnknown?: number;
1765
+ };
1524
1766
  /** `asOf` requests only — echo of the request's `asOf`. */
1525
1767
  asOf?: string;
1526
1768
  /** `asOf` requests only. */
@@ -1538,364 +1780,1913 @@ interface SemanticLegislationSearchResponse extends CreditedResponse, WithRespon
1538
1780
  /** Legacy daily-call plans only. */
1539
1781
  semanticUsage?: SemanticUsageInfo;
1540
1782
  }
1541
- /** Operational state. `FAILED` is set automatically when one delivery fails all 7 attempts (~24 h). */
1542
- type WebhookStatus = "ACTIVE" | "PAUSED" | "FAILED";
1543
- type DeliveryStatus = "PENDING" | "SUCCESS" | "FAILED" | "RETRYING";
1783
+ /** Request for `legislationAsOf` (API 2.26.0). */
1784
+ interface LegislationAsOfRequest {
1785
+ /**
1786
+ * A CELEX number, without a `CELEX:` prefix: an EU act (`32016R0679`). A consolidated id
1787
+ * (`02016R0679-20160504`) is read as its act; the version is always chosen
1788
+ * by `asOf`. For an ELI or a URL, call `resolve` first.
1789
+ */
1790
+ document: string;
1791
+ /** The date, `YYYY-MM-DD`, from `1952-01-01` to today (UTC). */
1792
+ asOf: string;
1793
+ /**
1794
+ * A whole article (`art_17`, `17`, `Article 17`, `6a`), an annex by its
1795
+ * numeral or letter as printed (`anx_III`, `anx_A`), or recitals
1796
+ * (`rct_26`, `rct_26-28`, at most 50). Numbers match exactly: `6` is not
1797
+ * `6a`. Paragraphs and points are not addressable. Omit it to get the
1798
+ * version only.
1799
+ */
1800
+ provision?: string;
1801
+ /** Default `en`. */
1802
+ language?: Language;
1803
+ }
1544
1804
  /**
1545
- * Filters for `documents.new`, in the /search vocabulary but matched against
1546
- * document TITLES and metadata. Every filter given must match; `{}` matches
1547
- * every new EU-law document (sectors 1–6), never consolidated texts. A
1548
- * `subdomain` REPLACES that default (`"consolidated"` alone = consolidated
1549
- * texts only). Unsupported filters (`procedure`, `textScope: "text"`,
1550
- * `domain: "NATIONAL_LAW"`, boolean operators, unknown types/authors) are
1551
- * refused with 400 and a `details` list.
1805
+ * Why `asOfResolved` is false on `legislationAsOf`.
1806
+ *
1807
+ * - `not_yet_adopted` / `not_yet_in_force` / `no_longer_in_force` — the date is outside the act's dates.
1808
+ * - `in_force_dates_unknown` — the act's dates do not establish it, or could not be read.
1809
+ * - `act_type_not_supported` — the act is not a regulation, directive, decision or other act of
1810
+ * the institutions (CELEX sector 3) — for example a treaty or an international agreement.
1811
+ * - `version_list_unavailable` / `version_lookup_cap` — the list of versions, or of the acts
1812
+ * amending the act, could not be read, or a lookup limit was reached. Retry.
1813
+ * - `not_in_language` — the version for the date has no text in `language`.
1814
+ * - `amendment_not_consolidated` — an act amending this act may have applied by the date, and no
1815
+ * listed version is known to include it.
1816
+ *
1817
+ * With `provision` only:
1818
+ *
1819
+ * - `article_not_in_version` — the version has no such article, annex or recital (`asOfVersion` is present).
1820
+ * - `provision_ambiguous` — more than one part of the text answers to that id.
1821
+ * - `version_not_parsed` — the text is not split into identifiable parts of that kind.
1822
+ * - `text_unavailable` — the version has no text at the source.
1823
+ * - `fetch_failed` / `fetch_timeout` / `fetch_pending` / `fetch_capacity` /
1824
+ * `fetch_budget_exhausted` / `request_deadline` — the text could not be fetched now. Retry.
1825
+ * - `insufficient_credits` / `credit_check_failed` — the fetch was not paid for, so it was not made.
1552
1826
  */
1553
- interface WebhookCriteria {
1827
+ type AsOfLookupReason = "not_yet_adopted" | "not_yet_in_force" | "no_longer_in_force" | "in_force_dates_unknown" | "act_type_not_supported" | "version_list_unavailable" | "version_lookup_cap" | "not_in_language" | "amendment_not_consolidated" | "text_unavailable" | "article_not_in_version" | "provision_ambiguous" | "version_not_parsed" | "fetch_budget_exhausted" | "fetch_pending" | "fetch_capacity" | "fetch_failed" | "fetch_timeout" | "request_deadline" | "insufficient_credits" | "credit_check_failed" | (string & {});
1828
+ /**
1829
+ * Every documented {@link AsOfLookupReason} value, in spec order (runtime list).
1830
+ * For `legislationAsOf`; `semanticLegislationSearch` with `asOf` has {@link AS_OF_REASONS}.
1831
+ */
1832
+ declare const AS_OF_LOOKUP_REASONS: readonly ["not_yet_adopted", "not_yet_in_force", "no_longer_in_force", "in_force_dates_unknown", "act_type_not_supported", "version_list_unavailable", "version_lookup_cap", "not_in_language", "amendment_not_consolidated", "text_unavailable", "article_not_in_version", "provision_ambiguous", "version_not_parsed", "fetch_budget_exhausted", "fetch_pending", "fetch_capacity", "fetch_failed", "fetch_timeout", "request_deadline", "insufficient_credits", "credit_check_failed"];
1833
+ /** The version listed for the date. */
1834
+ interface LegislationAsOfVersion {
1835
+ /** CELEX of the version — a consolidated id, or the act itself for `as_published`. */
1836
+ celex: string;
1554
1837
  /**
1555
- * Every term (or "quoted phrase") must match whole words of the title
1556
- * (case/accent-insensitive; 4+ char terms match word starts; `tax*`
1557
- * matches word starts at any length). `OR`/`NOT`/`NEAR`/`-term` are refused.
1838
+ * `consolidated`: a consolidated version. `as_published`: the act as
1839
+ * published in the Official Journal — no consolidated version is dated on
1840
+ * or before the date.
1558
1841
  */
1559
- query?: string;
1560
- /** Same values as /search; `regulation`/`directive`/`decision` match every sub-type. */
1561
- documentType?: OneOrMany<DocumentType | (string & {})>;
1842
+ kind: "consolidated" | "as_published" | (string & {});
1562
1843
  /**
1563
- * Same values as /search (`commission`, `council`, `parliament`,
1564
- * `court-of-justice`/`cjeu`/`ecj`/`court`, `general-court`,
1565
- * `civil-service-tribunal`, `ecb`, `eca`, `eesc`, `cor`, `efsa`, or codes
1566
- * like `COM`). `member-states` and `ema` are refused.
1844
+ * Consolidated versions only — the date the consolidated version carries.
1845
+ * It can be earlier than the act's entry into force.
1567
1846
  */
1568
- author?: OneOrMany<string>;
1569
- /** Lower-case subdomain names: `treaties`, `international`, `legislation`, `preparatory`, `case-law`, `consolidated`. */
1570
- subdomain?: OneOrMany<string>;
1571
- /** Lower bound on the document date (`YYYY-MM-DD`). */
1572
- dateFrom?: string;
1573
- dateTo?: string;
1574
- year?: number | number[];
1575
- /** Accepted for compatibility — all match titles. */
1576
- textScope?: "title" | "title-text" | "any";
1577
- domain?: "EU_LAW" | "ALL";
1578
- language?: string;
1579
- }
1580
- /** Summary shape used in list responses. The `secret` is never included here. */
1581
- interface WebhookListItem {
1582
- id?: string;
1583
- name?: string;
1584
- url?: string;
1585
- status?: WebhookStatus;
1586
- searchCriteria?: WebhookCriteria | null;
1847
+ date?: string;
1587
1848
  /**
1588
- * What is wrong with the stored `searchCriteria`; empty when nothing is.
1589
- * Non-empty only for criteria saved before a validation rule existed —
1590
- * such criteria are skipped (never widened) until fixed with `update`.
1849
+ * The day before the next version listed, in any language, and never
1850
+ * later than the act's end of validity. Absent when not known.
1591
1851
  */
1592
- criteriaErrors?: string[];
1593
- /** Watched base-act CELEX numbers (`watchlist.changes`). */
1594
- watchCelex?: string[];
1595
- lastChecked?: string | null;
1596
- lastTriggered?: string | null;
1597
- consecutiveFailures?: number;
1598
- /** Total delivery attempts ever made (success and failure combined). */
1599
- deliveryCount?: number;
1600
- createdAt?: string;
1601
- }
1602
- /** A single delivery attempt. */
1603
- interface WebhookDelivery {
1604
- id?: string;
1605
- /** Present on `recentDeliveries` (raw rows); not on `/deliveries` items. */
1606
- webhookId?: string;
1607
- status?: DeliveryStatus;
1608
- /** The JSON payload that was POSTed (or queued) to the webhook URL. */
1609
- payload?: Record<string, unknown>;
1610
- /** HTTP status code returned by the webhook URL. */
1611
- responseStatus?: number | null;
1612
- /** Truncated response body (max 500 chars). */
1613
- responseBody?: string | null;
1614
- errorMessage?: string | null;
1615
- attemptCount?: number;
1616
- nextRetryAt?: string | null;
1617
- deliveredAt?: string | null;
1618
- createdAt?: string;
1619
- [key: string]: unknown;
1852
+ validUntil?: string;
1853
+ /** When the version list was read (ISO date-time), when known. */
1854
+ checkedAt?: string;
1620
1855
  }
1621
- /** Delivery retry schedule reported on `GET /webhooks/{id}`. */
1622
- interface WebhookRetryPolicy {
1623
- /** e.g. 7 */
1624
- maxAttempts?: number;
1625
- /** e.g. 24 */
1626
- windowHours?: number;
1627
- /** e.g. `[1, 5, 30, 120, 360, 900]` */
1628
- delaysMinutes?: number[];
1856
+ /** What the Publications Office records about the act; a field is absent when not known. */
1857
+ interface LegislationAsOfAct {
1858
+ celex: string;
1859
+ /** Date of the act. */
1860
+ dateOfDocument?: string;
1861
+ /** First entry into force. */
1862
+ entryIntoForce?: string;
1863
+ /** End of validity, when the act has exactly one. */
1864
+ endOfValidity?: string;
1865
+ /** Whether the act is in force **today** (UTC). It says nothing about `asOf`. */
1866
+ inForceToday?: boolean;
1867
+ }
1868
+ /** One article, annex or recital range of the version returned. */
1869
+ interface LegislationAsOfProvision {
1870
+ /** The provision as normalised: `art_17`, `anx_III`, `rct_26`, `rct_26-28`. */
1871
+ id: string;
1872
+ /** Its heading in the text, e.g. `Article 17`. */
1873
+ number?: string;
1874
+ /** Its title, when it has one. */
1875
+ title?: string;
1876
+ /** The text of the provision in the version returned. */
1877
+ text: string;
1629
1878
  }
1630
- /** Full webhook details (no `secret`). */
1631
- interface WebhookDetail {
1632
- id?: string;
1633
- name?: string;
1634
- url?: string;
1635
- status?: WebhookStatus;
1636
- searchCriteria?: WebhookCriteria | null;
1637
- criteriaErrors?: string[];
1638
- watchCelex?: string[];
1639
- lastChecked?: string | null;
1640
- lastTriggered?: string | null;
1641
- consecutiveFailures?: number;
1642
- retryPolicy?: WebhookRetryPolicy;
1643
- /** @deprecated No longer returned by the server — read `retryPolicy.maxAttempts`. */
1644
- maxRetries?: number;
1645
- createdAt?: string;
1646
- updatedAt?: string;
1647
- /** Up to 20 most recent delivery attempts, newest first. */
1648
- recentDeliveries?: WebhookDelivery[];
1879
+ /** Where a document comes from. A value LexAPI does not know is `null`. */
1880
+ interface Provenance {
1881
+ /** Who publishes the document, e.g. `Publications Office of the European Union`. */
1882
+ publisher: string | null;
1883
+ /** The document's page at its publisher. */
1884
+ sourceUrl: string | null;
1885
+ /** The publisher's identifier — for EU documents, the CELEX number. */
1886
+ sourceIdentifier: string | null;
1887
+ /** When LexAPI fetched what the response returns (ISO date-time). */
1888
+ retrievedAt: string | null;
1889
+ /** SHA-256 fingerprint of the text LexAPI holds. */
1890
+ contentHash: string | null;
1891
+ /** Which version of the text this is — for EU documents, the CELEX number of the text served. */
1892
+ versionIdentifier: string | null;
1893
+ /** Language of the text (ISO 639-1). */
1894
+ language: string | null;
1895
+ licence: string | null;
1649
1896
  }
1650
- interface WebhookListResponse extends WithResponseHeaders {
1897
+ /**
1898
+ * Answer of `legislationAsOf`. Use `asOfVersion` and `provision` only when
1899
+ * `asOfResolved` is `true`; otherwise `asOfReason` says why, and there is no
1900
+ * `provision`.
1901
+ */
1902
+ interface LegislationAsOfResponse extends CreditedResponse, WithResponseHeaders {
1651
1903
  success: boolean;
1652
- count?: number;
1653
- webhooks: WebhookListItem[];
1904
+ /** CELEX of the act (the base act when a consolidated id was sent). */
1905
+ document: string;
1906
+ language: Language;
1907
+ /** Echo of the request's `asOf`. */
1908
+ asOf: string;
1909
+ /** Whether the version for the date — and, with `provision`, its text — was established. */
1910
+ asOfResolved: boolean;
1911
+ /** Why `asOfResolved` is false. */
1912
+ asOfReason?: AsOfLookupReason;
1913
+ /** The version listed for the date. Can be present on an unresolved `provision` answer. */
1914
+ asOfVersion?: LegislationAsOfVersion;
1915
+ act: LegislationAsOfAct;
1916
+ /** Present only when `provision` was asked and `asOfResolved` is `true`. */
1917
+ provision?: LegislationAsOfProvision;
1918
+ /** Present (`true`) when the resolved version is a consolidated version. */
1919
+ consolidated?: boolean;
1920
+ /** Consolidated versions only — the consolidation date (`YYYY-MM-DD`). */
1921
+ consolidatedAsOf?: string;
1922
+ /** Consolidated versions only — the act; cite it as the authentic source. */
1923
+ baseCelex?: string;
1924
+ /** Consolidated versions only — says the text is not the authentic one. */
1925
+ consolidatedNote?: string;
1926
+ provenance: Provenance;
1654
1927
  }
1655
- /** Needs `searchCriteria`, `watchCelex`, or both. */
1656
- interface WebhookCreateRequest {
1657
- /** User-friendly label for the webhook. */
1928
+ /** Availability block shared by `legislation` and `caseLaw` on a coverage entry. */
1929
+ interface NationalCoverageAvailability {
1930
+ available: boolean;
1931
+ description?: string;
1932
+ /** Approximate document count. `null` whenever `available` is false (incl. every jurisdiction still in preparation). */
1933
+ documents?: number | null;
1934
+ /** Earliest year covered, as an integer. `null` when unknown — today, always `null` for `legislation`. */
1935
+ from?: number | null;
1936
+ }
1937
+ /** `caseLaw` adds the courts covered. */
1938
+ interface NationalCaseLawCoverageAvailability extends NationalCoverageAvailability {
1939
+ courts?: string[];
1940
+ }
1941
+ /** Whether semantic search is indexed for this jurisdiction, per domain. */
1942
+ interface NationalSemanticSearchAvailability {
1943
+ legislation: boolean;
1944
+ caseLaw: boolean;
1945
+ }
1946
+ /** One upstream data source a jurisdiction's corpus is built from. */
1947
+ interface NationalSource {
1658
1948
  name: string;
1659
- /** HTTPS endpoint to POST matching documents to. */
1660
1949
  url: string;
1950
+ licence: string;
1951
+ attribution: string;
1952
+ }
1953
+ /**
1954
+ * Reason a citation-graph rate is not measured (API 2.13.0):
1955
+ * `not-collected` — LexAPI does not hold these references for the documents
1956
+ * it already has; `source-empty` — the source leaves the field empty or
1957
+ * absent on every document LexAPI holds.
1958
+ */
1959
+ type NationalCitationGraphUnmeasuredReason = "not-collected" | "source-empty" | (string & {});
1960
+ /** A citation-graph rate key, as used by `methods.unmeasured` and `floors`. */
1961
+ type NationalCitationGraphRateKey = "decisionsToActs" | "actsToEu" | "textPattern";
1962
+ /** What a jurisdiction's citation extraction does. */
1963
+ interface NationalCitationGraphMethods {
1964
+ /** How court decisions' references to acts are resolved. */
1965
+ decisions?: CitationResolution | null;
1966
+ /** Resolution methods used for references to national acts. */
1967
+ acts?: string[];
1968
+ /** Resolution methods used for references to EU law. */
1969
+ eu?: string[];
1661
1970
  /**
1662
- * Optional HMAC-SHA256 signing secret. If omitted, the server generates
1663
- * a 32-byte hex value and returns it in the create response — the ONLY
1664
- * time it is exposed. Store it.
1971
+ * API 2.13.0 — absent when every rate is measured; otherwise rate →
1972
+ * reason code for the rates the sources do not let LexAPI measure (such a
1973
+ * rate is `null` and carries no floor), e.g. `{ decisionsToActs: "not-collected" }`.
1665
1974
  */
1666
- secret?: string;
1667
- /** New documents matching these filters trigger a `documents.new` delivery. */
1668
- searchCriteria?: WebhookCriteria;
1669
- /**
1670
- * Base-act CELEX numbers to watch — amendments, corrigenda, repeals and
1671
- * new consolidated versions trigger a `watchlist.changes` delivery. Plan
1672
- * limit per webhook: STARTER 100, PROFESSIONAL 500, BUSINESS 1000, SCALE
1673
- * 2000, ENTERPRISE 5000.
1674
- */
1675
- watchCelex?: string[];
1975
+ unmeasured?: Partial<Record<NationalCitationGraphRateKey, NationalCitationGraphUnmeasuredReason>>;
1976
+ }
1977
+ /** The labelled-sample check of one resolution method of the jurisdiction's own extraction. */
1978
+ interface NationalCitationGraphPrecision {
1979
+ resolver?: string | null;
1980
+ resolverVersion?: number | null;
1981
+ /** `source` or `resolver` (API 2.12.0). */
1982
+ provenance?: "source" | "resolver" | null;
1983
+ /** Edges checked by hand. */
1984
+ labelled?: number | null;
1985
+ /** Clopper-Pearson 95 % upper bound on the error rate; `null` with no labels. */
1986
+ errorUpperBound?: number | null;
1676
1987
  }
1677
1988
  /**
1678
- * Partial update — only the supplied fields are changed. `watchCelex`
1679
- * replaces the whole list; `searchCriteria: null` removes the criteria (one
1680
- * of the two must remain). Setting `status` to `ACTIVE` resets
1681
- * `consecutiveFailures`; moving a `FAILED`/`PAUSED` webhook to `ACTIVE`
1682
- * also re-queues its deliveries from the last 7 days that ran out of
1683
- * retries (`requeuedDeliveries`).
1989
+ * API 2.12.0 — the lowest values the rates are expected to stay at (each the
1990
+ * measured value minus 10 percentage points, never below 0, at a dated
1991
+ * measurement). A rate that does not apply, is unmeasured, or was not
1992
+ * measured when the floors were set is `null`.
1684
1993
  */
1685
- interface WebhookUpdateRequest {
1686
- name?: string;
1687
- url?: string;
1688
- searchCriteria?: WebhookCriteria | null;
1689
- watchCelex?: string[];
1690
- status?: WebhookStatus;
1691
- }
1692
- /** Returned by `POST /webhooks`. The `secret` is included here only. */
1693
- interface WebhookCreateResponse extends WithResponseHeaders {
1694
- success: boolean;
1695
- message?: string;
1696
- webhook: {
1697
- id: string;
1698
- name: string;
1699
- url: string;
1700
- /** HMAC-SHA256 signing secret. Store this — it is not returned again. */
1701
- secret?: string;
1702
- status: WebhookStatus;
1703
- searchCriteria?: WebhookCriteria | null;
1704
- watchCelex?: string[];
1705
- createdAt: string;
1994
+ interface NationalCitationGraphFloors {
1995
+ /** Floor of `decisionResolutionRate`. */
1996
+ decisionsToActs?: number | null;
1997
+ /** Floor of `actEuRate`. */
1998
+ actsToEu?: number | null;
1999
+ /** Floor of `textPatternRate`. */
2000
+ textPattern?: number | null;
2001
+ /** Floor of `nimResolvedRate`. */
2002
+ nimResolved?: number | null;
2003
+ /** When the floors were set. */
2004
+ derivedAt?: string;
2005
+ /** The measurements the floors were taken from. */
2006
+ measuredAt?: {
2007
+ rebuild?: string | null;
2008
+ nim?: string | null;
1706
2009
  };
1707
2010
  }
1708
- /** Returned by `PUT /webhooks/{id}` — summary fields only. */
1709
- interface WebhookUpdateResponse extends WithResponseHeaders {
1710
- success: boolean;
1711
- message?: string;
1712
- webhook: {
1713
- id?: string;
1714
- name?: string;
1715
- url?: string;
1716
- status?: WebhookStatus;
1717
- searchCriteria?: WebhookCriteria | null;
1718
- criteriaErrors?: string[];
1719
- watchCelex?: string[];
1720
- updatedAt?: string;
2011
+ /**
2012
+ * A jurisdiction's citation graph, as measured (API 2.11.0). Nothing is
2013
+ * estimated: a value that was not measured is `null`.
2014
+ */
2015
+ interface NationalCitationGraph {
2016
+ methods?: NationalCitationGraphMethods | null;
2017
+ /** Edges whose citing document is in this jurisdiction and whose cited document is EU law or in a live jurisdiction. */
2018
+ edges?: number;
2019
+ /** Share of decisions with at least one structured reference that got an edge; `null` when not measured. */
2020
+ decisionResolutionRate?: number | null;
2021
+ /** Share of acts with recorded EU references that got an EU edge; `null` when not measured, and for a text-pattern-only jurisdiction. */
2022
+ actEuRate?: number | null;
2023
+ /** API 2.12.0. Share of EU act numbers found in running text that produced an edge; `null` when not measured. */
2024
+ textPatternRate?: number | null;
2025
+ /** The measures this member state notified to the Commission that Cellar still lists, and how many LexAPI holds. */
2026
+ transposition?: {
2027
+ measures?: number;
2028
+ resolved?: number;
1721
2029
  };
1722
- /** Present when the request set `status: "ACTIVE"` — deliveries queued again. */
1723
- requeuedDeliveries?: number;
2030
+ precision?: NationalCitationGraphPrecision;
2031
+ /** When the rebuild rates were measured; `null` without. */
2032
+ measuredAt?: string | null;
2033
+ /** API 2.12.0. Share of the notified measures in scope for matching that were matched to a held document; `null` without a complete run. */
2034
+ nimResolvedRate?: number | null;
2035
+ /** API 2.12.0. When that matching run finished. */
2036
+ nimMeasuredAt?: string | null;
2037
+ /** API 2.12.0. `null` until LexAPI has set them. */
2038
+ floors?: NationalCitationGraphFloors | null;
2039
+ }
2040
+ /** One jurisdiction's entry on `GET /national/coverage`. */
2041
+ interface NationalJurisdictionCoverage {
2042
+ /** ISO 3166-1 alpha-2, e.g. `"AT"`. Non-EU legal orders (e.g. `"UK"`) are included too. */
2043
+ code: string;
2044
+ name: string;
2045
+ /** Whether customers can call this jurisdiction's endpoints today. */
2046
+ live: boolean;
2047
+ /** `null` before launch. */
2048
+ launchedAt?: string | null;
2049
+ legislation: NationalCoverageAvailability;
2050
+ caseLaw: NationalCaseLawCoverageAvailability;
2051
+ semanticSearch: NationalSemanticSearchAvailability;
2052
+ sources: NationalSource[];
2053
+ /** When this jurisdiction's corpus was last synced. `null` if never. */
2054
+ lastSyncAt?: string | null;
2055
+ /** The jurisdiction's citation graph as measured (API 2.11.0); `null` for one that is not live, or when its numbers could not be read. */
2056
+ citationGraph?: NationalCitationGraph | null;
1724
2057
  }
1725
- /** Returned by `GET /webhooks/{id}`. */
1726
- interface WebhookResponse extends WithResponseHeaders {
1727
- success: boolean;
1728
- webhook: WebhookDetail;
2058
+ /**
2059
+ * `GET /national/coverage` — public, free, no API key or allowance headers
2060
+ * required. Call this before `getNationalDocument` / `listNationalDocuments`
2061
+ * / `nationalSemanticSearch` / `nationalLegislationSemanticSearch` to check
2062
+ * whether a jurisdiction is live, so a 404 is never a surprise.
2063
+ */
2064
+ interface NationalCoverageResponse extends WithResponseHeaders {
2065
+ updatedAt: string;
2066
+ jurisdictions: NationalJurisdictionCoverage[];
1729
2067
  }
1730
- /** Returned by `DELETE /webhooks/{id}`. */
1731
- interface WebhookDeleteResponse extends WithResponseHeaders {
1732
- success: boolean;
1733
- message?: string;
2068
+ /** Known `NationalTextBasis.basis` wire values (snake_case). Open for forward compatibility. */
2069
+ type NationalTextBasisKind = "as_announced" | "official_consolidated" | "official_consolidated_superseded" | "none" | (string & {});
2070
+ /**
2071
+ * `NationalDocument.textBasis` — which text a source says it publishes
2072
+ * (e.g. Poland). `null` (since API 2.8.0, no longer absent) for every
2073
+ * source that does not say.
2074
+ */
2075
+ interface NationalTextBasis {
2076
+ basis: NationalTextBasisKind;
2077
+ /** The date the text speaks for (never "valid until"). */
2078
+ asOf?: string;
2079
+ newerConsolidationExists?: boolean;
2080
+ newestPdfOnlyDate?: string;
2081
+ newerPdfOnly?: string[];
2082
+ amendedSince?: boolean;
2083
+ /** ELI of the act this text was consolidated from, when applicable. */
2084
+ textFrom?: string;
1734
2085
  }
1735
2086
  /**
1736
- * Result of a synchronous test delivery. `success: true` means the
1737
- * upstream responded 2xx; non-2xx and network errors both yield
1738
- * `success: false` plus a populated `delivery.errorMessage`. Test
1739
- * deliveries are not recorded in the delivery history.
2087
+ * What a national document is, in one vocabulary for every jurisdiction
2088
+ * (API 2.8.0): `"act"` (legislation) or `"decision"` (case law). Use it —
2089
+ * not `documentType`, the source's own label — to tell them apart.
1740
2090
  */
1741
- interface WebhookTestResponse extends WithResponseHeaders {
1742
- success: boolean;
1743
- message?: string;
1744
- delivery: {
1745
- status?: "SUCCESS" | "FAILED";
1746
- responseStatus?: number | null;
1747
- /** Truncated upstream response body (max 500 chars). */
1748
- responseBody?: string | null;
1749
- errorMessage?: string | null;
1750
- };
2091
+ type NationalDocumentKind = "act" | "decision";
2092
+ /**
2093
+ * A national document's metadata, as the listing returns it — the same
2094
+ * fields, types and formats for every jurisdiction (API 2.8.0). Every field
2095
+ * is always present; one the source does not provide is `null`, never
2096
+ * absent.
2097
+ */
2098
+ interface NationalDocumentSummary {
2099
+ /** The national corpus id (e.g. `"AT-NOR-12345"`), analogous to a CELEX number. */
2100
+ id: string;
2101
+ /** ISO 3166-1 alpha-2 jurisdiction code. */
2102
+ jurisdiction: string;
2103
+ /** ISO 639-1 code of the source language. */
2104
+ language: string;
2105
+ /**
2106
+ * `"act"` | `"decision"` — see {@link NationalDocumentKind}. `null` only
2107
+ * for an id that matches no collection LexAPI knows for the jurisdiction.
2108
+ */
2109
+ documentKind: NationalDocumentKind | null;
2110
+ title: string | null;
2111
+ /**
2112
+ * The source's own type label, in its language (`"Bundesgesetz (konsolidiert)"`,
2113
+ * `"Uitspraak (NL)"`) — different in every jurisdiction. Use `documentKind`
2114
+ * for act / decision.
2115
+ */
2116
+ documentType: string | null;
2117
+ /** The decision's ECLI. `null` for acts and where the source gives none. */
2118
+ ecli: string | null;
2119
+ /** The act's ELI (a URI). `null` where the source gives none. */
2120
+ eli: string | null;
2121
+ /** The document's own date, `YYYY-MM-DD`; `null` when the source gives none. */
2122
+ dateOfDocument: string | null;
2123
+ /** LexAPI's version counter for this document (bumped when its text changes). */
2124
+ version: number;
2125
+ /** When LexAPI last stored real content for it (ISO 8601). */
2126
+ fetchedAt: string;
2127
+ /**
2128
+ * Last day in force (`YYYY-MM-DD`), set once the source confirmed the act
2129
+ * is no longer in force. `null` when there is no known end (an act in
2130
+ * force, case law, a source that does not record repeals).
2131
+ */
2132
+ validTo: string | null;
2133
+ /** `false` once `validTo` has passed (UTC), `true` while it is today or later; `null` when `validTo` is `null`. */
2134
+ inForce: boolean | null;
1751
2135
  }
1752
- interface WebhookDeliveriesParams {
1753
- /** Max deliveries to return. Default 50. */
2136
+ /** Legislation a decision cites — {@link NationalDecision.citedNorms}. */
2137
+ interface NationalCitedNorm {
2138
+ /** The source's citation string (`"§ 62 Abs 1a S 3 EStG 2009"`, `"§ 7 177/1996 Sb."`). */
2139
+ text: string;
2140
+ /**
2141
+ * LexAPI id of the cited act when the source identifies it (CZ, SI, PL,
2142
+ * SE) — whether or not LexAPI holds that act; `null` otherwise.
2143
+ */
2144
+ documentId: string | null;
2145
+ }
2146
+ /**
2147
+ * A decision's case-law metadata (`documentKind: "decision"`). Values are
2148
+ * the source's own (local language and spelling); the field set and types
2149
+ * are the same in every jurisdiction — the server reads them from whichever
2150
+ * field the source uses (Austria's `gericht`, Germany's `aktenzeichen`, …),
2151
+ * so read these, never the raw source keys under `content.details`.
2152
+ */
2153
+ interface NationalDecision {
2154
+ /** The deciding court as the source names it (`"OGH"`, `"BFH 3. Senat"`, `"Gerechtshof Amsterdam"`). */
2155
+ court: string | null;
2156
+ /**
2157
+ * The chamber, section or department, where the source names it apart
2158
+ * from the court (`"Sección Cuarta"`, `"Civilni oddelek"`). `null`
2159
+ * otherwise (Austria and Germany name the panel inside `court`).
2160
+ */
2161
+ chamber: string | null;
2162
+ /** The case (docket) numbers as the source writes them (`["III R 27/24"]`); `[]` when none. */
2163
+ caseNumbers: string[];
2164
+ /** Legislation the decision cites, where the source lists it; `[]` otherwise. */
2165
+ citedNorms: NationalCitedNorm[];
2166
+ }
2167
+ /** One unit of an act (article, section, annex) — the same fields in every jurisdiction. */
2168
+ interface NationalArticle {
2169
+ /** The source's own label (`"§ 1"`, `"Art. 1"`, `"1 kap. 1 §"`); `null` for an unnumbered unit. */
2170
+ number: string | null;
2171
+ /** The unit's heading. */
2172
+ title: string | null;
2173
+ /** The part or chapter it sits in (`"Kapitel 1 — …"`, `"1 luku"`). */
2174
+ section: string | null;
2175
+ /** The unit's text; `null` when the source has no text for it — never an empty provision. */
2176
+ text: string | null;
2177
+ /** The unit's own validity start (`YYYY-MM-DD`), where the source dates units (AT, ES, FR). */
2178
+ inForceFrom: string | null;
2179
+ inForceTo: string | null;
2180
+ /** The source's other unit fields (unit ids, kinds, notes). Source-specific. */
2181
+ details: Record<string, unknown>;
2182
+ }
2183
+ /** `content.repeal` — the source's confirmation behind `validTo`. */
2184
+ interface NationalRepeal {
2185
+ /** Last day in force (`YYYY-MM-DD`). */
2186
+ validTo: string | null;
2187
+ /** What the source says, in its words. */
2188
+ basis: string | null;
2189
+ /** When LexAPI recorded it. */
2190
+ detectedAt: string | null;
2191
+ }
2192
+ /**
2193
+ * The parsed text of a national document — a closed key set, the same in
2194
+ * every jurisdiction (API 2.8.0). What a source adds beyond these keys is
2195
+ * under `source` (provenance) and `details`, both source-specific.
2196
+ */
2197
+ interface NationalDocumentContent {
2198
+ fullText: string;
2199
+ /** The act's units in order. `[]` for decisions and for acts the source publishes without units. */
2200
+ articles: NationalArticle[];
2201
+ /**
2202
+ * The languages the text is in (ISO 639-1). Dutch treaties (`NL-BWBV…`):
2203
+ * the languages BWB publishes the treaty in, in order (`["en", "nl"]`);
2204
+ * otherwise the one language of the text.
2205
+ */
2206
+ textLanguages: string[];
2207
+ /** Set when the whole text is in one language other than the document's `language`; else `null`. */
2208
+ textLanguage: string | null;
2209
+ /** `true` when the text includes text in a language other than the document's `language`. */
2210
+ embeddedForeignText: boolean;
2211
+ /**
2212
+ * Where the text was read from (API 2.9.0): `html` (the source's web
2213
+ * rendition), `pdf-text` (the text layer of the source's PDF) or `ocr`
2214
+ * (machine-read from a scanned page — see `ocr`). `null` for jurisdictions
2215
+ * that do not label it. Treat unknown values as additive.
2216
+ */
2217
+ textSource: NationalTextSource | null;
2218
+ /** `null` unless `textSource` is `ocr` (API 2.9.0). OCR text may contain recognition errors and is never the official text. */
2219
+ ocr: NationalOcrInfo | null;
2220
+ /** The source's confirmation that the act is no longer in force (the basis of `validTo`); `null` otherwise. */
2221
+ repeal: NationalRepeal | null;
2222
+ /** Provenance from the upstream (system, its ids and URLs). Keys vary by jurisdiction. */
2223
+ source: Record<string, unknown>;
2224
+ /** Everything else the source provides, under its own field names. Keys vary by jurisdiction. */
2225
+ details: Record<string, unknown>;
2226
+ }
2227
+ /** Known `NationalDocumentContent.textSource` values. Open for forward compatibility. */
2228
+ type NationalTextSource = "html" | "pdf-text" | "ocr" | (string & {});
2229
+ /** How an OCR'd national text was recognised (API 2.9.0). */
2230
+ interface NationalOcrInfo {
2231
+ engine: string | null;
2232
+ engineVersion: string | null;
2233
+ /** The version of the engine's recognition core. */
2234
+ coreVersion: string | null;
2235
+ /** The recognition model used. */
2236
+ traineddata: string | null;
2237
+ /** Recognition confidence, 0–100, averaged over the recognised characters. */
2238
+ confidence: number | null;
2239
+ /** The lowest page's confidence, 0–100. */
2240
+ minPageConfidence: number | null;
2241
+ /** The PDF pages read by OCR. */
2242
+ pages: number[];
2243
+ /** Pages of the same document read from the PDF's text layer. */
2244
+ textLayerPages: number[];
2245
+ /** Human-readable statement that the text is machine-read and not the official text. */
2246
+ notice: string;
2247
+ }
2248
+ /** Full national document — `GET /{jurisdiction}/documents/{id}` (API 2.8.0 shape). */
2249
+ interface NationalDocument extends NationalDocumentSummary {
2250
+ /**
2251
+ * Case-law metadata when `documentKind` is `"decision"` (served also when
2252
+ * the decision has no text); `null` for acts. See {@link isNationalDecision}.
2253
+ */
2254
+ decision: NationalDecision | null;
2255
+ /** `null` when the jurisdiction's source publishes no text for this id — check `textAvailability`. */
2256
+ content: NationalDocumentContent | null;
2257
+ textAvailability: TextAvailability;
2258
+ /** The jurisdiction's source attribution — always show this to users alongside the text. */
2259
+ attribution: string;
2260
+ /** Only from sources that say which text they publish (e.g. Poland); `null` for every other source. */
2261
+ textBasis: NationalTextBasis | null;
2262
+ }
2263
+ /** A {@link NationalDocument} narrowed to a decision (`decision` is non-null). */
2264
+ type NationalDecisionDocument = NationalDocument & {
2265
+ documentKind: "decision";
2266
+ decision: NationalDecision;
2267
+ };
2268
+ /**
2269
+ * Narrow a national document to a decision: `documentKind === "decision"`
2270
+ * with its `decision` block. Works the same for every jurisdiction.
2271
+ */
2272
+ declare function isNationalDecision(document: NationalDocument): document is NationalDecisionDocument;
2273
+ /**
2274
+ * `GET /{jurisdiction}/documents/{id}`. No `success` field (unlike the EU
2275
+ * document endpoints). Credit cost: every national read is a corpus read
2276
+ * (there is no live-fetch fallback) — reserved at the `document_fetch`
2277
+ * weight (5) and settled to the corpus-hit weight (1).
2278
+ */
2279
+ interface NationalDocumentResponse extends CreditedResponse, WithResponseHeaders {
2280
+ document: NationalDocument;
2281
+ }
2282
+ interface NationalDocumentListParams {
2283
+ /**
2284
+ * 1-based page, within the first `LISTING_MAX_OFFSET` (1,000) rows only —
2285
+ * `(page - 1) * limit >= 1000` is a 400 `InvalidParamsError`. Mutually
2286
+ * exclusive with `cursor`; omit both for page 1. Beyond the first 1,000
2287
+ * rows, page through with `cursor` (each response's `nextCursor`) instead.
2288
+ */
2289
+ page?: number;
2290
+ /**
2291
+ * Opaque keyset cursor from a previous response's `nextCursor`. Works at
2292
+ * any depth (unlike `page`, which only reaches the first 1,000 rows). An
2293
+ * invalid cursor is a 400.
2294
+ */
2295
+ cursor?: string;
2296
+ /** Default 20, max 100. */
1754
2297
  limit?: number;
1755
- /** Pagination offset. Default 0. */
1756
- offset?: number;
2298
+ /** Case-insensitive title search, 3–200 characters (Unicode code points). */
2299
+ q?: string;
2300
+ /** Case-insensitive substring match on `documentType` (wire param: `type`), at most 200 characters. */
2301
+ documentType?: string;
2302
+ /** Repealed acts are hidden by default; `true` includes them. */
2303
+ includeRepealed?: boolean;
1757
2304
  }
1758
- interface WebhookDeliveriesResponse extends WithResponseHeaders {
1759
- success: boolean;
1760
- /** Total deliveries for this webhook (across all pages). */
1761
- total?: number;
2305
+ /**
2306
+ * `GET /{jurisdiction}/documents`. No `success` field. 3 credits per call
2307
+ * (flat — pagination does not multiply the price, unlike `search`).
2308
+ *
2309
+ * Results are newest-first by the document's own date (undated rows last),
2310
+ * then by id — a total order, so pages never repeat or skip a row even
2311
+ * while the corpus keeps changing underneath the walk.
2312
+ */
2313
+ interface NationalDocumentListResponse extends CreditedResponse, WithResponseHeaders {
2314
+ jurisdiction: string;
2315
+ /** Matching rows, counted up to 10,000 — see `totalExact`. */
2316
+ total: number;
2317
+ /** `false` when `total` is a lower bound (more than 10,000 rows matched, or the count timed out). */
2318
+ totalExact: boolean;
2319
+ /** Present only when the request paged with `page` (absent in cursor mode). */
2320
+ page?: number;
2321
+ limit: number;
2322
+ includeRepealed: boolean;
2323
+ /** `true` when another page follows — page with `nextCursor`. */
2324
+ hasMore: boolean;
2325
+ /** Opaque cursor for the next page (via `cursor`), or `null` on the last page. */
2326
+ nextCursor: string | null;
2327
+ results: NationalDocumentSummary[];
2328
+ }
2329
+ /**
2330
+ * Filters honoured by `POST /{jurisdiction}/search/semantic` — deliberately
2331
+ * an EXACT interface (no index signature): the server 400s any unsupported
2332
+ * key (`"Unsupported filter"`), so a typo here should be a compile error,
2333
+ * not a silent 400 at runtime. `jurisdiction` must equal the path's
2334
+ * jurisdiction, or be omitted.
2335
+ */
2336
+ interface NationalCaseLawFilters {
2337
+ court?: string;
2338
+ date_from?: string;
2339
+ date_to?: string;
2340
+ ecli?: string;
2341
+ language?: string;
2342
+ jurisdiction?: string;
2343
+ }
2344
+ /**
2345
+ * Filters honoured by `POST /{jurisdiction}/legislation/semantic` — exact,
2346
+ * like {@link NationalCaseLawFilters}. `law_id`/`in_force`/`law_type` are
2347
+ * the semantic index's own names, accepted as aliases.
2348
+ */
2349
+ interface NationalLegislationFilters {
2350
+ id?: string;
2351
+ law_id?: string;
2352
+ inForce?: boolean;
2353
+ in_force?: boolean;
2354
+ documentType?: string;
2355
+ law_type?: string;
2356
+ language?: string;
2357
+ jurisdiction?: string;
2358
+ }
2359
+ /**
2360
+ * Options for `nationalSemanticSearch`. `hyde` is accepted for API
2361
+ * compatibility but is always a no-op here: the national index never
2362
+ * rewrites, so the response reports `hyde: false` (never `true`) when the
2363
+ * request set it, and billing stays the flat 5 credits (no 15-credit tier).
2364
+ *
2365
+ * Deliberately NOT `extends SemanticSearchOptions`: `language` here is a
2366
+ * plain `string` (the jurisdiction's own language — anything else is a
2367
+ * 400), not the 10-code EU `SemanticLanguage` enum, and `filters` is the
2368
+ * exact {@link NationalCaseLawFilters} rather than a free-form record.
2369
+ */
2370
+ interface NationalSemanticCaseLawOptions {
2371
+ /** Natural-language query to embed. */
2372
+ query: string;
2373
+ /** Max results. Default 10. */
1762
2374
  limit?: number;
1763
- offset?: number;
1764
- deliveries: WebhookDelivery[];
2375
+ /** Drop results below this cosine similarity (wire: `min_score`). */
2376
+ minScore?: number;
2377
+ /** Omit, or the jurisdiction's own language — any other value is a 400. */
2378
+ language?: string;
2379
+ /** Receive the full matched text per hit (wire: `include: ["text"]`) instead of a `snippet`. */
2380
+ includeText?: boolean;
2381
+ hyde?: boolean;
2382
+ filters?: NationalCaseLawFilters;
1765
2383
  }
1766
- /** A document as delivered by `documents.new` and `watchlist.changes`. */
1767
- interface WebhookChangeDocument {
1768
- celex?: string;
1769
- /** English title (another official language when no English title exists yet); null if metadata never arrived. */
1770
- title?: string | null;
1771
- url?: string;
1772
- documentType?: string | null;
1773
- documentTypeCode?: string | null;
1774
- /** Publications Office resource-type codes, e.g. `["CONS_TEXT"]`. */
1775
- resourceTypes?: string[];
1776
- author?: string | null;
1777
- authorCodes?: string[];
1778
- dateOfDocumentISO?: string | null;
1779
- /** The document date as dd/mm/yyyy. */
1780
- dateOfDocument?: string | null;
1781
- /** Consolidated versions only — the date the version applies from (may be in the future). */
1782
- consolidationDate?: string | null;
1783
- /** When the document appeared on EUR-Lex — the clock webhooks match on. */
1784
- addedAt?: string | null;
1785
- /** Upper-case ISO codes with a published expression. Check before fetching a consolidated version. */
1786
- availableLanguages?: string[];
1787
- /** Alias of `celex` (earlier payload shape). */
1788
- celexNumber?: string;
1789
- /** Alias of `documentType` (earlier payload shape). */
1790
- form?: string | null;
2384
+ /**
2385
+ * Options for `nationalLegislationSemanticSearch`. No `hyde` (no national
2386
+ * index rewrites queries). See {@link NationalSemanticCaseLawOptions} for why
2387
+ * this does not extend `SemanticSearchOptions`.
2388
+ */
2389
+ interface NationalSemanticLegislationOptions {
2390
+ query: string;
2391
+ limit?: number;
2392
+ minScore?: number;
2393
+ /** Omit, or the jurisdiction's own language — any other value is a 400. */
2394
+ language?: string;
2395
+ includeText?: boolean;
2396
+ filters?: NationalLegislationFilters;
2397
+ /**
2398
+ * Label each hit for this date (`YYYY-MM-DD`, from `1800-01-01` to today,
2399
+ * UTC; API 2.29.0), a `YYYY-MM-DD` string. The search
2400
+ * runs over today's texts only: a provision repealed or replaced since that
2401
+ * date cannot be found, and the text is never swapped for an earlier one.
2402
+ * A hit is resolved (`asOfResolved: true`) only when the publisher's dates,
2403
+ * as of LexAPI's last recorded read of the act (`asOfVersion.checkedAt`),
2404
+ * show that today's wording already applied on the date. An unresolved hit
2405
+ * keeps today's wording; it is not established as the text for the date.
2406
+ * LexAPI holds such dates for Austria and Spain; elsewhere every hit is
2407
+ * `asof_not_available`. `in_force` and the `inForce` filter stay about
2408
+ * today. No extra cost; an invalid date is a 400 `InvalidParamsError`.
2409
+ */
2410
+ asOf?: string;
1791
2411
  }
1792
- /** Fields shared by every signed delivery. */
1793
- interface WebhookDeliveryEnvelope {
1794
- /** Time of THIS attempt (re-signed on every retry) — use it for a replay window. */
1795
- timestamp: string;
1796
- webhook: {
1797
- id: string;
1798
- name: string;
2412
+ /**
2413
+ * Single hit from `nationalSemanticSearch`, same shape as
2414
+ * {@link SemanticCaseLawResult} (which index metadata fields are filled
2415
+ * depends on the national source) plus national fields. For metadata that
2416
+ * is the same in every jurisdiction, read `document` — the matched decision
2417
+ * as the listing returns it (API 2.8.0).
2418
+ */
2419
+ interface NationalSemanticCaseLawResult extends SemanticCaseLawResult {
2420
+ /** The national corpus id this hit resolved to (also mirrored into `metadata.celex_id`). */
2421
+ documentId: string;
2422
+ /** ISO 3166-1 alpha-2 jurisdiction code. */
2423
+ jurisdiction: string;
2424
+ /**
2425
+ * The matched decision as the listing returns it, from LexAPI's own
2426
+ * record — the same fields in every jurisdiction, whatever metadata the
2427
+ * index carries for it (API 2.8.0).
2428
+ */
2429
+ document: NationalDocumentSummary;
2430
+ /** When the source recorded an end of validity (also a future one). */
2431
+ validTo?: string;
2432
+ /** Only `false`, and only once `validTo` has passed. */
2433
+ inForce?: boolean;
2434
+ attribution: string;
2435
+ }
2436
+ /**
2437
+ * Why a national legislation hit is not resolved for `asOf`
2438
+ * (`asOfResolved: false`, API 2.29.0). The hit keeps today's wording, which
2439
+ * is not established as the text for that date.
2440
+ *
2441
+ * - `provision_amended_since` — the publisher dates today's wording from after `asOf`: the
2442
+ * provision was amended or added since, or the publisher's consolidated record of it starts later.
2443
+ * - `no_longer_in_force` — the provision's or the act's end of validity is before `asOf`.
2444
+ * - `provision_dates_unknown` — no usable publisher date for the provision's current wording, it
2445
+ * could not be matched to the hit, or LexAPI's copy of the act may be out of date on that date.
2446
+ * - `asof_not_available` — LexAPI holds no per-provision dates for this country.
2447
+ */
2448
+ type NationalAsOfReason = "provision_amended_since" | "no_longer_in_force" | "provision_dates_unknown" | "asof_not_available" | (string & {});
2449
+ /** Every documented {@link NationalAsOfReason} value, in spec order (runtime list). */
2450
+ declare const NATIONAL_AS_OF_REASONS: readonly ["provision_amended_since", "no_longer_in_force", "provision_dates_unknown", "asof_not_available"];
2451
+ /**
2452
+ * The publisher's dates for a national hit's current wording, on a hit with
2453
+ * `asOfResolved: true` (API 2.29.0). Not the EU {@link AsOfVersion}: `kind`
2454
+ * is always `current_unit`, and the text is today's. `validTo`, `sourceId`
2455
+ * and `checkedAt` are `null` when not known.
2456
+ */
2457
+ interface NationalAsOfVersion {
2458
+ kind: "current_unit";
2459
+ /** The publisher's start date of this wording (`YYYY-MM-DD`, on or before `asOf`). */
2460
+ validFrom: string;
2461
+ /** The publisher's end date of this wording, when given; `null` when open. */
2462
+ validTo: string | null;
2463
+ /** The publisher's id of the provision (the RIS document number in Austria, the BOE block id in Spain). */
2464
+ sourceId: string | null;
2465
+ /**
2466
+ * The day (`YYYY-MM-DD`) of the last read of the act that LexAPI recorded.
2467
+ * LexAPI may have checked the act since without finding a change. Dates
2468
+ * and wording are as of that read; a change the publisher made after it is
2469
+ * not reflected.
2470
+ */
2471
+ checkedAt: string | null;
2472
+ }
2473
+ /**
2474
+ * Tells a national {@link NationalAsOfVersion} from an EU {@link AsOfVersion}
2475
+ * by `kind` (`current_unit`). The EU `kind` is an open union, so TypeScript
2476
+ * cannot narrow on a `kind` comparison alone; this guard does. `false` for
2477
+ * `null`, `undefined` and anything that is not an object.
2478
+ */
2479
+ declare function isNationalAsOfVersion(version: AsOfVersion | NationalAsOfVersion | null | undefined | unknown): version is NationalAsOfVersion;
2480
+ /**
2481
+ * Single hit from `nationalLegislationSemanticSearch`: the fields of the
2482
+ * {@link SemanticLegislationResult} hit a national hit carries (no
2483
+ * consolidated-text fields; its own `asOf` fields) plus national fields.
2484
+ * Unlike the EU hit, a national hit always carries `law_title`,
2485
+ * `article_ref`, `section`, `language`, `in_force`, `valid_from`, `valid_to`
2486
+ * and `law_type` — `null` when the index has nothing for the unit (API
2487
+ * 2.8.0). NOTE: these index fields are deliberately snake_case — that is
2488
+ * what the server sends — do not "fix" the casing without changing the
2489
+ * server first. The act's cross-jurisdiction metadata is under `document`.
2490
+ */
2491
+ interface NationalSemanticLegislationResult {
2492
+ /** Id of the matched chunk in the index; regenerated when the index is rebuilt — key on `law_id` + `article_ref`. */
2493
+ id?: string;
2494
+ /** Cosine similarity, 0–1. */
2495
+ score?: number;
2496
+ /** The matched unit's text — present ONLY with `includeText: true`. */
2497
+ text?: string;
2498
+ /** ~600-character preview of the matched text — present by default. */
2499
+ snippet?: string;
2500
+ chapter?: string | null;
2501
+ exact_match_law_id?: boolean;
2502
+ /** Which fields of the hit are the publisher's text and which were derived (API 2.20.0). */
2503
+ fieldProvenance?: FieldProvenance;
2504
+ metadata?: Record<string, unknown>;
2505
+ /** `asOf` requests only — echo of the request's `asOf` (API 2.29.0). */
2506
+ asOf?: string;
2507
+ /**
2508
+ * `asOf` requests only — `true` when the publisher's dates show that the
2509
+ * wording returned (today's) already applied on `asOf`. The text is never swapped.
2510
+ */
2511
+ asOfResolved?: boolean;
2512
+ /** Why `asOfResolved` is false; the hit keeps today's wording. */
2513
+ asOfReason?: NationalAsOfReason;
2514
+ /** `asOfResolved: true` only — the publisher's dates for the unit's current wording. */
2515
+ asOfVersion?: NationalAsOfVersion;
2516
+ /** LexAPI id of the act. */
2517
+ law_id: string;
2518
+ /** Same as `law_id`. */
2519
+ documentId: string;
2520
+ jurisdiction: string;
2521
+ law_title: string | null;
2522
+ /** The unit's label, as in `content.articles[].number` of the document. */
2523
+ article_ref: string | null;
2524
+ section: string | null;
2525
+ language: string | null;
2526
+ /**
2527
+ * From the index, as of today; `false` (with `valid_to`) when LexAPI
2528
+ * knows the act is repealed (LexAPI only ever overrides it toward
2529
+ * `false`); `null` when unknown.
2530
+ */
2531
+ in_force: boolean | null;
2532
+ /** The unit's validity start (`YYYY-MM-DD`), where the source dates units. */
2533
+ valid_from: string | null;
2534
+ valid_to: string | null;
2535
+ /** The index's type code of the act. */
2536
+ law_type: string | null;
2537
+ /** The matched act as the listing returns it, from LexAPI's own record (API 2.8.0). */
2538
+ document: NationalDocumentSummary;
2539
+ attribution: string;
2540
+ [key: string]: unknown;
2541
+ }
2542
+ /**
2543
+ * Why a national semantic search answer is incomplete. `SEARCH_INCOMPLETE`:
2544
+ * the national index could not complete the search.
2545
+ */
2546
+ type NationalSearchPartialReason = "SEARCH_INCOMPLETE" | (string & {});
2547
+ /**
2548
+ * `POST /{jurisdiction}/search/semantic` — national case-law semantic
2549
+ * search. `credits` is present on the body, like every other credit-metered
2550
+ * route, typed optional only via the shared `CreditedResponse` shape.
2551
+ */
2552
+ interface NationalSemanticCaseLawResponse extends CreditedResponse, WithResponseHeaders {
2553
+ success: boolean;
2554
+ searchType?: "semantic-case-law";
2555
+ jurisdiction?: string;
2556
+ query?: string;
2557
+ resultCount?: number;
2558
+ results: NationalSemanticCaseLawResult[];
2559
+ /** Present only when the request set `hyde: true` — always `false` (see {@link NationalSemanticCaseLawOptions}). */
2560
+ hyde?: boolean;
2561
+ metadata?: Record<string, unknown>;
2562
+ hint?: string;
2563
+ /**
2564
+ * Present (`true`) only when the national index could not complete the
2565
+ * search but some hits are left: the results may be missing better
2566
+ * matches. `hint` says what may complete it — a retry, or a rephrased
2567
+ * query / changed filters. When nothing is left to return the call fails
2568
+ * instead: `NationalSemanticUnavailableError` (503) or
2569
+ * `NationalSemanticFilterUnreachableError` (422).
2570
+ */
2571
+ partial?: true;
2572
+ /** Present with `partial`. */
2573
+ partialReason?: NationalSearchPartialReason;
2574
+ /** The jurisdiction's source attribution — always show this to users alongside results. */
2575
+ attribution?: string;
2576
+ tookMs?: number;
2577
+ semanticUsage?: SemanticUsageInfo;
2578
+ subscription?: {
2579
+ tier?: SubscriptionTier;
2580
+ maxResults?: number;
1799
2581
  };
1800
- /** `id` is stable across retries (also `X-Webhook-Delivery`) — dedupe on it. Absent on `webhook.test`. */
1801
- delivery?: {
1802
- id: string;
1803
- attempt: number;
2582
+ }
2583
+ /** `POST /{jurisdiction}/legislation/semantic` — national legislation semantic search. */
2584
+ interface NationalSemanticLegislationResponse extends CreditedResponse, WithResponseHeaders {
2585
+ success: boolean;
2586
+ searchType?: "semantic-legislation";
2587
+ jurisdiction?: string;
2588
+ query?: string;
2589
+ resultCount?: number;
2590
+ results: NationalSemanticLegislationResult[];
2591
+ /** `asOf` requests only — echo of the request's `asOf` (API 2.29.0). */
2592
+ asOf?: string;
2593
+ /** `asOf` requests only (API 2.29.0). */
2594
+ asOfSummary?: {
2595
+ /** Always `0`: national `asOf` fetches nothing. */
2596
+ liveFetches: number;
2597
+ /** Hits returned with `asOfResolved: false`. */
2598
+ unresolved: number;
2599
+ };
2600
+ metadata?: Record<string, unknown>;
2601
+ hint?: string;
2602
+ /**
2603
+ * Present (`true`) only when the national index could not complete the
2604
+ * search but some hits are left: the results may be missing better
2605
+ * matches. `hint` says what may complete it — a retry, or a rephrased
2606
+ * query / changed filters. When nothing is left to return the call fails
2607
+ * instead: `NationalSemanticUnavailableError` (503) or
2608
+ * `NationalSemanticFilterUnreachableError` (422).
2609
+ */
2610
+ partial?: true;
2611
+ /** Present with `partial`. */
2612
+ partialReason?: NationalSearchPartialReason;
2613
+ attribution?: string;
2614
+ tookMs?: number;
2615
+ semanticUsage?: SemanticUsageInfo;
2616
+ subscription?: {
2617
+ tier?: SubscriptionTier;
2618
+ maxResults?: number;
1804
2619
  };
1805
2620
  }
1806
- interface WebhookDocumentsNewPayload extends WebhookDeliveryEnvelope {
1807
- event: "documents.new";
2621
+ /** Operational state. `FAILED` is set automatically when one delivery fails all 7 attempts (~24 h). */
2622
+ type WebhookStatus = "ACTIVE" | "PAUSED" | "FAILED";
2623
+ type DeliveryStatus = "PENDING" | "SUCCESS" | "FAILED" | "RETRYING";
2624
+ /**
2625
+ * Filters for `documents.new`, in the /search vocabulary but matched against
2626
+ * document TITLES and metadata. Every filter given must match; `{}` matches
2627
+ * every new EU-law document (sectors 1–6), never consolidated texts. A
2628
+ * `subdomain` REPLACES that default (`"consolidated"` alone = consolidated
2629
+ * texts only). Unsupported filters (`procedure`, `textScope: "text"`,
2630
+ * `domain: "NATIONAL_LAW"`, boolean operators, unknown types/authors) are
2631
+ * refused with 400 and a `details` list.
2632
+ */
2633
+ interface WebhookCriteria {
2634
+ /**
2635
+ * Every term (or "quoted phrase") must match whole words of the title
2636
+ * (case/accent-insensitive; 4+ char terms match word starts; `tax*`
2637
+ * matches word starts at any length). `OR`/`NOT`/`NEAR`/`-term` are refused.
2638
+ */
2639
+ query?: string;
2640
+ /** Same values as /search; `regulation`/`directive`/`decision` match every sub-type. */
2641
+ documentType?: OneOrMany<DocumentType | (string & {})>;
2642
+ /**
2643
+ * Same values as /search (`commission`, `council`, `parliament`,
2644
+ * `court-of-justice`/`cjeu`/`ecj`/`court`, `general-court`,
2645
+ * `civil-service-tribunal`, `ecb`, `eca`, `eesc`, `cor`, `efsa`, or codes
2646
+ * like `COM`). `member-states` and `ema` are refused.
2647
+ */
2648
+ author?: OneOrMany<string>;
2649
+ /** Lower-case subdomain names: `treaties`, `international`, `legislation`, `preparatory`, `case-law`, `consolidated`. */
2650
+ subdomain?: OneOrMany<string>;
2651
+ /** Lower bound on the document date (`YYYY-MM-DD`). */
2652
+ dateFrom?: string;
2653
+ dateTo?: string;
2654
+ year?: number | number[];
2655
+ /** Accepted for compatibility — all match titles. */
2656
+ textScope?: "title" | "title-text" | "any";
2657
+ domain?: "EU_LAW" | "ALL";
2658
+ language?: string;
2659
+ }
2660
+ /** Summary shape used in list responses. The `secret` is never included here. */
2661
+ interface WebhookListItem {
2662
+ id?: string;
2663
+ name?: string;
2664
+ url?: string;
2665
+ status?: WebhookStatus;
1808
2666
  searchCriteria?: WebhookCriteria | null;
1809
- data: {
1810
- /** Documents in this delivery (max 100). */
1811
- count: number;
1812
- /** Every new match from the same hourly check — larger than `count` when split across deliveries. */
1813
- totalAvailable?: number;
1814
- documents: WebhookChangeDocument[];
2667
+ /**
2668
+ * What is wrong with the stored `searchCriteria`; empty when nothing is.
2669
+ * Non-empty only for criteria saved before a validation rule existed —
2670
+ * such criteria are skipped (never widened) until fixed with `update`.
2671
+ */
2672
+ criteriaErrors?: string[];
2673
+ /** Watched base-act CELEX numbers (`watchlist.changes`). */
2674
+ watchCelex?: string[];
2675
+ lastChecked?: string | null;
2676
+ lastTriggered?: string | null;
2677
+ consecutiveFailures?: number;
2678
+ /** Total delivery attempts ever made (success and failure combined). */
2679
+ deliveryCount?: number;
2680
+ createdAt?: string;
2681
+ }
2682
+ /** A single delivery attempt. */
2683
+ interface WebhookDelivery {
2684
+ id?: string;
2685
+ /** Present on `recentDeliveries` (raw rows); not on `/deliveries` items. */
2686
+ webhookId?: string;
2687
+ status?: DeliveryStatus;
2688
+ /** The JSON payload that was POSTed (or queued) to the webhook URL. */
2689
+ payload?: Record<string, unknown>;
2690
+ /** HTTP status code returned by the webhook URL. */
2691
+ responseStatus?: number | null;
2692
+ /** Truncated response body (max 500 chars). */
2693
+ responseBody?: string | null;
2694
+ errorMessage?: string | null;
2695
+ attemptCount?: number;
2696
+ nextRetryAt?: string | null;
2697
+ deliveredAt?: string | null;
2698
+ createdAt?: string;
2699
+ [key: string]: unknown;
2700
+ }
2701
+ /** Delivery retry schedule reported on `GET /webhooks/{id}`. */
2702
+ interface WebhookRetryPolicy {
2703
+ /** e.g. 7 */
2704
+ maxAttempts?: number;
2705
+ /** e.g. 24 */
2706
+ windowHours?: number;
2707
+ /** e.g. `[1, 5, 30, 120, 360, 900]` */
2708
+ delaysMinutes?: number[];
2709
+ }
2710
+ /** Full webhook details (no `secret`). */
2711
+ interface WebhookDetail {
2712
+ id?: string;
2713
+ name?: string;
2714
+ url?: string;
2715
+ status?: WebhookStatus;
2716
+ searchCriteria?: WebhookCriteria | null;
2717
+ criteriaErrors?: string[];
2718
+ watchCelex?: string[];
2719
+ lastChecked?: string | null;
2720
+ lastTriggered?: string | null;
2721
+ consecutiveFailures?: number;
2722
+ retryPolicy?: WebhookRetryPolicy;
2723
+ /** @deprecated No longer returned by the server — read `retryPolicy.maxAttempts`. */
2724
+ maxRetries?: number;
2725
+ createdAt?: string;
2726
+ updatedAt?: string;
2727
+ /** Up to 20 most recent delivery attempts, newest first. */
2728
+ recentDeliveries?: WebhookDelivery[];
2729
+ }
2730
+ interface WebhookListResponse extends WithResponseHeaders {
2731
+ success: boolean;
2732
+ count?: number;
2733
+ webhooks: WebhookListItem[];
2734
+ }
2735
+ /** Needs `searchCriteria`, `watchCelex`, or both. */
2736
+ interface WebhookCreateRequest {
2737
+ /** User-friendly label for the webhook. */
2738
+ name: string;
2739
+ /** HTTPS endpoint to POST matching documents to. */
2740
+ url: string;
2741
+ /**
2742
+ * Optional HMAC-SHA256 signing secret. If omitted, the server generates
2743
+ * a 32-byte hex value and returns it in the create response — the ONLY
2744
+ * time it is exposed. Store it.
2745
+ */
2746
+ secret?: string;
2747
+ /** New documents matching these filters trigger a `documents.new` delivery. */
2748
+ searchCriteria?: WebhookCriteria;
2749
+ /**
2750
+ * Base-act CELEX numbers to watch — amendments, corrigenda, repeals and
2751
+ * new consolidated versions trigger a `watchlist.changes` delivery. Plan
2752
+ * limit per webhook: STARTER 100, PROFESSIONAL 500, BUSINESS 1000, SCALE
2753
+ * 2000, ENTERPRISE 5000.
2754
+ */
2755
+ watchCelex?: string[];
2756
+ }
2757
+ /**
2758
+ * Partial update — only the supplied fields are changed. `watchCelex`
2759
+ * replaces the whole list; `searchCriteria: null` removes the criteria (one
2760
+ * of the two must remain). Setting `status` to `ACTIVE` resets
2761
+ * `consecutiveFailures`; moving a `FAILED`/`PAUSED` webhook to `ACTIVE`
2762
+ * also re-queues its deliveries from the last 7 days that ran out of
2763
+ * retries (`requeuedDeliveries`).
2764
+ */
2765
+ interface WebhookUpdateRequest {
2766
+ name?: string;
2767
+ url?: string;
2768
+ searchCriteria?: WebhookCriteria | null;
2769
+ watchCelex?: string[];
2770
+ status?: WebhookStatus;
2771
+ }
2772
+ /** Returned by `POST /webhooks`. The `secret` is included here only. */
2773
+ interface WebhookCreateResponse extends WithResponseHeaders {
2774
+ success: boolean;
2775
+ message?: string;
2776
+ webhook: {
2777
+ id: string;
2778
+ name: string;
2779
+ url: string;
2780
+ /** HMAC-SHA256 signing secret. Store this — it is not returned again. */
2781
+ secret?: string;
2782
+ status: WebhookStatus;
2783
+ searchCriteria?: WebhookCriteria | null;
2784
+ watchCelex?: string[];
2785
+ createdAt: string;
2786
+ };
2787
+ }
2788
+ /** Returned by `PUT /webhooks/{id}` — summary fields only. */
2789
+ interface WebhookUpdateResponse extends WithResponseHeaders {
2790
+ success: boolean;
2791
+ message?: string;
2792
+ webhook: {
2793
+ id?: string;
2794
+ name?: string;
2795
+ url?: string;
2796
+ status?: WebhookStatus;
2797
+ searchCriteria?: WebhookCriteria | null;
2798
+ criteriaErrors?: string[];
2799
+ watchCelex?: string[];
2800
+ updatedAt?: string;
2801
+ };
2802
+ /** Present when the request set `status: "ACTIVE"` — deliveries queued again. */
2803
+ requeuedDeliveries?: number;
2804
+ }
2805
+ /** Returned by `GET /webhooks/{id}`. */
2806
+ interface WebhookResponse extends WithResponseHeaders {
2807
+ success: boolean;
2808
+ webhook: WebhookDetail;
2809
+ }
2810
+ /** Returned by `DELETE /webhooks/{id}`. */
2811
+ interface WebhookDeleteResponse extends WithResponseHeaders {
2812
+ success: boolean;
2813
+ message?: string;
2814
+ }
2815
+ /**
2816
+ * Result of a synchronous test delivery. `success: true` means the
2817
+ * upstream responded 2xx; non-2xx and network errors both yield
2818
+ * `success: false` plus a populated `delivery.errorMessage`. Test
2819
+ * deliveries are not recorded in the delivery history.
2820
+ */
2821
+ interface WebhookTestResponse extends WithResponseHeaders {
2822
+ success: boolean;
2823
+ message?: string;
2824
+ delivery: {
2825
+ status?: "SUCCESS" | "FAILED";
2826
+ responseStatus?: number | null;
2827
+ /** Truncated upstream response body (max 500 chars). */
2828
+ responseBody?: string | null;
2829
+ errorMessage?: string | null;
1815
2830
  };
1816
2831
  }
1817
- type WatchlistRelation = "amended_by" | "corrected_by" | "repealed_by" | "consolidated_version" | (string & {});
1818
- interface WebhookWatchlistChange {
1819
- watchedCelex: string;
1820
- relation: WatchlistRelation;
1821
- document: WebhookChangeDocument;
2832
+ interface WebhookDeliveriesParams {
2833
+ /** Max deliveries to return. Default 50. */
2834
+ limit?: number;
2835
+ /** Pagination offset. Default 0. */
2836
+ offset?: number;
2837
+ }
2838
+ interface WebhookDeliveriesResponse extends WithResponseHeaders {
2839
+ success: boolean;
2840
+ /** Total deliveries for this webhook (across all pages). */
2841
+ total?: number;
2842
+ limit?: number;
2843
+ offset?: number;
2844
+ deliveries: WebhookDelivery[];
2845
+ }
2846
+ /** A document as delivered by `documents.new` and `watchlist.changes`. */
2847
+ interface WebhookChangeDocument {
2848
+ celex?: string;
2849
+ /** English title (another official language when no English title exists yet); null if metadata never arrived. */
2850
+ title?: string | null;
2851
+ url?: string;
2852
+ documentType?: string | null;
2853
+ documentTypeCode?: string | null;
2854
+ /** Publications Office resource-type codes, e.g. `["CONS_TEXT"]`. */
2855
+ resourceTypes?: string[];
2856
+ author?: string | null;
2857
+ authorCodes?: string[];
2858
+ dateOfDocumentISO?: string | null;
2859
+ /** The document date as dd/mm/yyyy. */
2860
+ dateOfDocument?: string | null;
2861
+ /** Consolidated versions only — the date the version applies from (may be in the future). */
2862
+ consolidationDate?: string | null;
2863
+ /** When the document appeared on EUR-Lex — the clock webhooks match on. */
2864
+ addedAt?: string | null;
2865
+ /** Upper-case ISO codes with a published expression. Check before fetching a consolidated version. */
2866
+ availableLanguages?: string[];
2867
+ /** Alias of `celex` (earlier payload shape). */
2868
+ celexNumber?: string;
2869
+ /** Alias of `documentType` (earlier payload shape). */
2870
+ form?: string | null;
2871
+ }
2872
+ /** Fields shared by every signed delivery. */
2873
+ interface WebhookDeliveryEnvelope {
2874
+ /** Time of THIS attempt (re-signed on every retry) — use it for a replay window. */
2875
+ timestamp: string;
2876
+ webhook: {
2877
+ id: string;
2878
+ name: string;
2879
+ };
2880
+ /** `id` is stable across retries (also `X-Webhook-Delivery`) — dedupe on it. Absent on `webhook.test`. */
2881
+ delivery?: {
2882
+ id: string;
2883
+ attempt: number;
2884
+ };
2885
+ }
2886
+ interface WebhookDocumentsNewPayload extends WebhookDeliveryEnvelope {
2887
+ event: "documents.new";
2888
+ searchCriteria?: WebhookCriteria | null;
2889
+ data: {
2890
+ /** Documents in this delivery (max 100). */
2891
+ count: number;
2892
+ /** Every new match from the same hourly check — larger than `count` when split across deliveries. */
2893
+ totalAvailable?: number;
2894
+ documents: WebhookChangeDocument[];
2895
+ };
2896
+ }
2897
+ type WatchlistRelation = "amended_by" | "corrected_by" | "repealed_by" | "consolidated_version" | (string & {});
2898
+ interface WebhookWatchlistChange {
2899
+ watchedCelex: string;
2900
+ relation: WatchlistRelation;
2901
+ document: WebhookChangeDocument;
2902
+ }
2903
+ interface WebhookWatchlistChangesPayload extends WebhookDeliveryEnvelope {
2904
+ event: "watchlist.changes";
2905
+ data: {
2906
+ /** Changes in this delivery (max 100). */
2907
+ count: number;
2908
+ changes: WebhookWatchlistChange[];
2909
+ };
2910
+ }
2911
+ /** Sent by `webhooks.test()`. */
2912
+ interface WebhookTestPayload extends WebhookDeliveryEnvelope {
2913
+ event: "webhook.test";
2914
+ data: {
2915
+ message: string;
2916
+ searchCriteria?: WebhookCriteria | null;
2917
+ };
2918
+ }
2919
+ /** Discriminated union of every payload LexAPI delivers — switch on `event`. */
2920
+ type WebhookPayload = WebhookDocumentsNewPayload | WebhookWatchlistChangesPayload | WebhookTestPayload;
2921
+ /**
2922
+ * One entry in a document's version history.
2923
+ *
2924
+ * Versions are LexAPI's fetch snapshots (content-hash changes between
2925
+ * fetches), not the law in force on a date — for the version of an EU act
2926
+ * for a date use `legislationAsOf`.
2927
+ */
2928
+ interface VersionEntry {
2929
+ version: number;
2930
+ isCurrent: boolean;
2931
+ /**
2932
+ * Equal hashes mean no text change. A different hash usually means EUR-Lex
2933
+ * changed the text — or the current version was re-parsed in place by an
2934
+ * improved parser.
2935
+ */
2936
+ contentHash: string;
2937
+ /**
2938
+ * When this version's text arrived at LexAPI. For a version without
2939
+ * `observedFrom` (possible for snapshots stored before API 2.28.0) it is
2940
+ * the last fetch of its text, which is not when the version began.
2941
+ */
2942
+ fetchedAt: string;
2943
+ /** When the version began in LexAPI's fetch history; `null` when LexAPI has no record of it (API 2.28.0). */
2944
+ observedFrom?: string | null;
2945
+ title?: string | null;
2946
+ documentType?: string | null;
2947
+ documentTypeCode?: string | null;
2948
+ /** Present on single-snapshot responses only (not in history listings). */
2949
+ parsedContent?: Record<string, unknown> | null;
2950
+ /**
2951
+ * Single-snapshot responses only (API 2.20.0): `contentHash` and
2952
+ * `retrievedAt` are the snapshot's own; `sourceUrl` is the document's page
2953
+ * today, which can show a later text.
2954
+ */
2955
+ provenance?: Provenance;
2956
+ /** Single-snapshot responses only (API 2.20.0). */
2957
+ fieldProvenance?: FieldProvenance;
2958
+ }
2959
+ interface DocumentVersionsResponse extends CreditedResponse, WithResponseHeaders {
2960
+ success: boolean;
2961
+ celex: string;
2962
+ language: string;
2963
+ currentVersion: number;
2964
+ /** When the document first entered the corpus — history starts here. */
2965
+ trackedSince: string;
2966
+ /** Server restatement of the observation-snapshot semantics. */
2967
+ semantics: string;
2968
+ /** Newest first; the current version is included and flagged. */
2969
+ versions: VersionEntry[];
2970
+ }
2971
+ interface DocumentVersionResponse extends CreditedResponse, WithResponseHeaders {
2972
+ success: boolean;
2973
+ celex: string;
2974
+ language: string;
2975
+ /**
2976
+ * Present on `/at/{date}` responses only — the date you asked about, in
2977
+ * LexAPI's fetch history. Not a date of the law.
2978
+ */
2979
+ asOf?: string;
2980
+ semantics: string;
2981
+ document: VersionEntry;
2982
+ /** SDK-added: mirrors the `X-Corpus-Version` response header. */
2983
+ corpusVersion?: number;
2984
+ }
2985
+ /**
2986
+ * The request that answers which version of an EU act is listed for a date
2987
+ * (`legislationAsOf`). A field is absent when it is not a string.
2988
+ */
2989
+ interface InForceLookup {
2990
+ method?: "POST" | (string & {});
2991
+ path?: "/api/v1/legislation/as-of" | (string & {});
2992
+ }
2993
+ /** The snapshot returned by `getDocumentAtDate`. */
2994
+ interface DocumentAtDateSnapshot extends VersionEntry {
2995
+ /**
2996
+ * When the next version's text arrived — this snapshot was the current one
2997
+ * until then; `null` for the current version (API 2.28.0). A version is the
2998
+ * current one from `observedFrom` until `observedUntil`.
2999
+ */
3000
+ observedUntil?: string | null;
3001
+ }
3002
+ /**
3003
+ * `GET /documents/{celex}/at/{date}` — the snapshot LexAPI held as current at
3004
+ * the end of that day (UTC), from its own fetch history. It is not the law in
3005
+ * force on that date: for the version of an EU act for a date use
3006
+ * `legislationAsOf` (`inForceLookup` points to it).
3007
+ */
3008
+ interface DocumentAtDateResponse extends DocumentVersionResponse {
3009
+ /** Always `observation_snapshot`: a snapshot from LexAPI's fetch history (API 2.28.0). */
3010
+ kind?: "observation_snapshot" | (string & {});
3011
+ document: DocumentAtDateSnapshot;
3012
+ /** `true` when the date is after today (UTC): the answer is the current version; absent otherwise (API 2.28.0). */
3013
+ dateInFuture?: boolean;
3014
+ /**
3015
+ * Present for an EU act `legislationAsOf` resolves (CELEX sector 3, or a
3016
+ * consolidated version of one); absent for case law, treaties, corrigenda (API 2.28.0).
3017
+ */
3018
+ inForceLookup?: InForceLookup;
3019
+ /** SDK-added: the `X-Warning` response header (a future date), when present. */
3020
+ xWarning?: string;
3021
+ }
3022
+ /**
3023
+ * `NotFoundError.reason` (`error.details.reason` on a 404). `unknown_endpoint`
3024
+ * (API 2.27.0): no such endpoint. On `getDocumentAtDate` (API 2.28.0):
3025
+ * `before_tracking` — the date is before the document entered the corpus;
3026
+ * `boundary_unknown` — LexAPI has no record of when a version stored before
3027
+ * API 2.28.0 began, so it cannot say which snapshot it held on that date.
3028
+ */
3029
+ type NotFoundReason = "unknown_endpoint" | "before_tracking" | "boundary_unknown" | (string & {});
3030
+ /**
3031
+ * A version a `boundary_unknown` date could fall in (`NotFoundError.candidates`).
3032
+ * For these versions `fetchedAt` can be the last fetch and later than the date.
3033
+ * `fetchedAt` and `observedFrom` are `null` when the API sent no string.
3034
+ */
3035
+ interface SnapshotCandidate {
3036
+ version: number;
3037
+ fetchedAt: string | null;
3038
+ observedFrom: string | null;
3039
+ }
3040
+ /** Shared params for the version endpoints. */
3041
+ interface VersionParams {
3042
+ /** 2-letter ISO language of the tracked corpus row (default `en`). */
3043
+ language?: string;
3044
+ }
3045
+
3046
+ /**
3047
+ * Typed errors mirroring the LexAPI error envelope:
3048
+ *
3049
+ * { "success": false, "error": { "code": "NOT_FOUND", "message": "...", "details": {...} } }
3050
+ *
3051
+ * Some legacy endpoints return a bare `{ "error": "...", "message": "..." }`
3052
+ * body without the typed envelope; the parser tolerates both shapes. Unknown
3053
+ * codes never crash the parser — the raw code string is preserved on the
3054
+ * base `LexAPIError` (forward compatibility).
3055
+ */
3056
+
3057
+ /** Stable error codes from the OpenAPI `ErrorResponse.error.code` enum. */
3058
+ type ErrorCode = "NOT_FOUND" | "INVALID_CELEX" | "INVALID_URL" | "INVALID_PARAMS" | "RATE_LIMITED" | "QUOTA_EXHAUSTED" | "TIER_FORBIDDEN" | "PAYMENT_PAST_DUE" | "CREDITS_EXHAUSTED" | "UPSTREAM_ERROR" | "TIMEOUT" | "INTERNAL" | "UNAUTHORIZED" | "SERVICE_UNAVAILABLE" | "CONNECTION_ERROR" | "REQUEST_TIMEOUT" | "ABORTED" | "INVALID_RESPONSE" | "INCOMPLETE_EXPORT" | "NATIONAL_ALLOWANCE_EXHAUSTED" | "NATIONAL_SEMANTIC_NOT_ENABLED" | "NATIONAL_SEMANTIC_UNAVAILABLE" | "NATIONAL_SEMANTIC_FILTER_UNREACHABLE" | "DOCUMENT_WITHDRAWN" | (string & {});
3059
+ /** Extra context attached to errors built from an HTTP response. */
3060
+ interface LexAPIErrorContext {
3061
+ /** The parsed JSON error body, verbatim (e.g. legacy `upgradeUrl`, `current`/`limit`). */
3062
+ body?: unknown;
3063
+ /** Parsed response headers (rate limits, source, …). */
3064
+ headers?: ResponseHeaders;
3065
+ /**
3066
+ * For a body that is not JSON, its first 200 characters (code points). Raw
3067
+ * response text; may contain document text; do not show to a model or log
3068
+ * by default.
3069
+ */
3070
+ bodyExcerpt?: string;
3071
+ }
3072
+ /** Base class for every error thrown by the SDK. */
3073
+ declare class LexAPIError extends Error {
3074
+ /** Stable class tag used by the cross-build `instanceof` brand check. */
3075
+ static readonly kind: string;
3076
+ static [Symbol.hasInstance](value: unknown): boolean;
3077
+ /** Stable machine-readable code (`error.code`, or derived from the HTTP status for legacy bodies). */
3078
+ readonly code: ErrorCode;
3079
+ /** HTTP status. `0` for client-side failures (network error, client-side timeout). */
3080
+ readonly status: number;
3081
+ /** The `error.details` object from the typed envelope, when present. */
3082
+ readonly details: unknown;
3083
+ /**
3084
+ * Seconds to wait before retrying, when the server said so (429; also the
3085
+ * 503 of an incomplete national semantic search).
3086
+ * Sourced from the `Retry-After` response HEADER first; the JSON
3087
+ * `retryAfter` body field is only a fallback because it can carry
3088
+ * epoch-seconds values (epoch-looking values are
3089
+ * normalized to a delta).
3090
+ */
3091
+ readonly retryAfter: number | undefined;
3092
+ /**
3093
+ * The parsed JSON error body, verbatim. Useful for legacy-shape fields the
3094
+ * typed properties don't cover (`upgradeUrl` on tier gates, `current` /
3095
+ * `limit` on the webhook ceiling, `usage` on legacy quota 429s).
3096
+ */
3097
+ readonly body: unknown;
3098
+ /** Parsed response headers, when the error came from an HTTP response. */
3099
+ readonly headers: ResponseHeaders | undefined;
3100
+ constructor(code: ErrorCode, message: string, status: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3101
+ /**
3102
+ * For a response body that is not JSON, its first 200 characters (code
3103
+ * points); `undefined` otherwise. Raw response text; may contain document
3104
+ * text; do not show to a model or log by default. Not an own property of
3105
+ * the error, so `console.log` (also with `%o`), `util.inspect` with
3106
+ * `showHidden` or with `getters`, `JSON.stringify`, spread and
3107
+ * `structuredClone` leave it out (`util.inspect` with `showHidden` and
3108
+ * `getters` together shows it); never part of `message`. Assigning to it
3109
+ * replaces it (`undefined` clears it).
3110
+ */
3111
+ get bodyExcerpt(): string | undefined;
3112
+ set bodyExcerpt(value: string | undefined);
3113
+ /**
3114
+ * Build the most specific error subclass for a non-2xx response.
3115
+ * Accepts both the typed envelope and the legacy bare `{error, message}` shape.
3116
+ * `code` and `message` are read only when they are non-empty strings.
3117
+ */
3118
+ static fromResponse(status: number, body: unknown, headerRetryAfter?: number, headers?: ResponseHeaders, bodyExcerpt?: string): LexAPIError;
3119
+ }
3120
+ /**
3121
+ * 404 — document or resource missing (`NOT_FOUND`), or an endpoint the API
3122
+ * does not have (see {@link NotFoundError.unknownEndpoint}).
3123
+ */
3124
+ declare class NotFoundError extends LexAPIError {
3125
+ static readonly kind: string;
3126
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3127
+ /**
3128
+ * `true` when the API (2.27.0 or later) has no such endpoint
3129
+ * (`details.reason` is `"unknown_endpoint"`): a mistyped path, a method
3130
+ * newer than the API, or a national route for a country that is not
3131
+ * available. Always `false` on APIs before 2.27.0; there the message
3132
+ * contains "Unknown API endpoint". Read from `details` only, never from
3133
+ * the message.
3134
+ */
3135
+ get unknownEndpoint(): boolean;
3136
+ /**
3137
+ * `details.reason` when it is a string: `unknown_endpoint`, or on
3138
+ * `getDocumentAtDate` (API 2.28.0) `before_tracking` / `boundary_unknown`.
3139
+ * `undefined` on a 404 without one (e.g. a document not in the corpus).
3140
+ */
3141
+ get reason(): NotFoundReason | undefined;
3142
+ /**
3143
+ * `true` when `getDocumentAtDate` was asked about a date before the
3144
+ * document entered the corpus (`details.reason` is `"before_tracking"`);
3145
+ * {@link trackedSince} says when that was.
3146
+ */
3147
+ get beforeTracking(): boolean;
3148
+ /**
3149
+ * `true` when LexAPI has no record of when a version stored before API
3150
+ * 2.28.0 began, so it cannot say which snapshot it held on the date and
3151
+ * does not guess (`details.reason` is `"boundary_unknown"`). Refunded.
3152
+ * Read the {@link candidates} with `getDocumentVersion`.
3153
+ */
3154
+ get boundaryUnknown(): boolean;
3155
+ /** `before_tracking` only: when the document entered the corpus (`details.trackedSince`). */
3156
+ get trackedSince(): string | undefined;
3157
+ /**
3158
+ * On `before_tracking` for an EU act: the request that answers which
3159
+ * version is listed for a date (`legislationAsOf`).
3160
+ */
3161
+ get inForceLookup(): InForceLookup | undefined;
3162
+ /**
3163
+ * `boundary_unknown` only: the versions the date could fall in — the
3164
+ * first 10 items of `details.candidates`
3165
+ * that are objects with an integer `version` (`fetchedAt` / `observedFrom`
3166
+ * are `null` when not strings). `[]` when there are none. For these
3167
+ * versions `fetchedAt` can be the last fetch and later than the date.
3168
+ */
3169
+ get candidates(): SnapshotCandidate[];
3170
+ /**
3171
+ * `boundary_unknown` only: `true` when more versions matched than
3172
+ * {@link candidates} lists (`details.candidatesTruncated` is `true`, or
3173
+ * more than 10 usable candidates were sent).
3174
+ */
3175
+ get candidatesTruncated(): boolean;
3176
+ }
3177
+ /** 400 — CELEX failed validation (`INVALID_CELEX`). */
3178
+ declare class InvalidCelexError extends LexAPIError {
3179
+ static readonly kind: string;
3180
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3181
+ }
3182
+ /** 400 — URL had no resolvable CELEX (`INVALID_URL`). */
3183
+ declare class InvalidUrlError extends LexAPIError {
3184
+ static readonly kind: string;
3185
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3186
+ }
3187
+ /** 400 — missing or malformed params (`INVALID_PARAMS`). */
3188
+ declare class InvalidParamsError extends LexAPIError {
3189
+ static readonly kind: string;
3190
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext,
3191
+ /**
3192
+ * @internal Lets a subclass (`NationalSemanticFilterUnreachableError`)
3193
+ * keep its own `code` while still being `instanceof InvalidParamsError`.
3194
+ * Not part of the public constructor contract.
3195
+ */
3196
+ code?: ErrorCode);
3197
+ /**
3198
+ * The parameter that was refused, when the server names it — e.g. an
3199
+ * unknown citation-graph filter value (API 2.11.0). Read from `details`
3200
+ * (typed envelope) or the top level of the body (legacy shape).
3201
+ */
3202
+ get param(): string | undefined;
3203
+ /** The refused value of {@link param}, when the server echoes it. */
3204
+ get value(): unknown;
3205
+ /** The allowed values of {@link param}, when the server lists them (may be empty). */
3206
+ get allowed(): string[] | undefined;
3207
+ }
3208
+ /** 401 — missing, invalid, or revoked API key. */
3209
+ declare class AuthenticationError extends LexAPIError {
3210
+ static readonly kind: string;
3211
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3212
+ }
3213
+ /**
3214
+ * 429 — per-minute rate limit (`RATE_LIMITED`), or, on legacy daily plans,
3215
+ * the used-up daily / monthly-semantic quota (`QUOTA_EXHAUSTED`; `code`
3216
+ * tells them apart). 429s use the legacy `{error, message, retryAfter}` body
3217
+ * (with a top-level `code` from API 2.4.0 on); the `Retry-After` header is
3218
+ * authoritative and is what `retryAfter` reads first.
3219
+ */
3220
+ declare class RateLimitedError extends LexAPIError {
3221
+ static readonly kind: string;
3222
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext, code?: "RATE_LIMITED" | "QUOTA_EXHAUSTED");
3223
+ /** `RateLimit-*` headers from the 429 response (limit / remaining / reset seconds). */
3224
+ get rateLimit(): RateLimitInfo | undefined;
3225
+ /**
3226
+ * `true` for a legacy-plan quota 429 (daily call quota, or the monthly
3227
+ * semantic quota) rather than the per-minute limiter (SDK contract §1.2):
3228
+ * `code` is `QUOTA_EXHAUSTED`, or — servers before API 2.4.0, which
3229
+ * send no code — the body carries `usage.resetsAt` with neither a
3230
+ * `Retry-After` header nor a `retryAfter` body field. It cannot succeed
3231
+ * before `resetsAt`, so the SDK does not retry it and `retryAfter` is
3232
+ * `undefined`.
3233
+ */
3234
+ get quotaExhausted(): boolean;
3235
+ /** When a legacy quota resets: the body's `resetsAt`, else `usage.resetsAt`. */
3236
+ get resetsAt(): string | undefined;
3237
+ }
3238
+ /**
3239
+ * 403 — tier-gated endpoint (`TIER_FORBIDDEN`). Retrying cannot help; upgrade
3240
+ * the plan. A failed payment (`PAYMENT_PAST_DUE`) is the subclass
3241
+ * {@link PaymentPastDueError}: check for it first to tell the two apart.
3242
+ */
3243
+ declare class TierForbiddenError extends LexAPIError {
3244
+ static readonly kind: string;
3245
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext, code?: "TIER_FORBIDDEN" | "PAYMENT_PAST_DUE");
3246
+ }
3247
+ /**
3248
+ * 403 — a subscription payment failed and was not completed in time
3249
+ * (`PAYMENT_PAST_DUE`, API 2.27.0). API requests are refused until the
3250
+ * payment succeeds, so it is never retried: pay the open invoice in the
3251
+ * dashboard ({@link PaymentPastDueError.billingUrl}). Extends
3252
+ * `TierForbiddenError`, so a handler for that class also catches it; its
3253
+ * `code` is `PAYMENT_PAST_DUE`. Before API 2.27.0 a failed payment was
3254
+ * refused at once with a 403 without a code, raised as `TierForbiddenError`.
3255
+ * Legacy-shape body
3256
+ * (`{code, error, message, accessEndedAt?, billingUrl}`): the getters read
3257
+ * `details` first, then the top level of the raw `body`.
3258
+ */
3259
+ declare class PaymentPastDueError extends TierForbiddenError {
3260
+ static readonly kind: string;
3261
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3262
+ /** When API access ended (ISO date-time); `undefined` when the server does not say. */
3263
+ get accessEndedAt(): string | undefined;
3264
+ /** Where to pay the open invoice (absolute URL of the dashboard's billing page). */
3265
+ get billingUrl(): string | undefined;
3266
+ }
3267
+ /** `error.details` on a 402 `CREDITS_EXHAUSTED` envelope. */
3268
+ interface CreditsExhaustedDetails {
3269
+ /** The operation that was refused, e.g. `"semantic_case_law"`. */
3270
+ operation?: string;
3271
+ /** Its upfront credit weight (variable-priced operations are admitted against their upfront weight). */
3272
+ weight?: number;
3273
+ /** Credits left in the pool (monthly + top-up − used). `weight − available` is the shortfall. */
3274
+ available?: number;
3275
+ /** Monthly allowance. */
3276
+ included?: number;
3277
+ /** Top-up credits. */
3278
+ topup?: number;
3279
+ /** Credits used this window. */
3280
+ used?: number;
3281
+ /** When the monthly pool refills. */
3282
+ resetsAt?: string | null;
3283
+ [key: string]: unknown;
3284
+ }
3285
+ /**
3286
+ * 402 — monthly credit pool (incl. top-ups) cannot cover the operation
3287
+ * (`CREDITS_EXHAUSTED`). Not retried: wait for `resetsAt`, buy a top-up, or
3288
+ * upgrade. A cheaper operation may still succeed — compare `weight` to `available`.
3289
+ */
3290
+ declare class CreditsExhaustedError extends LexAPIError {
3291
+ static readonly kind: string;
3292
+ /** When the monthly credit allowance resets (ISO date-time), when the server said so. */
3293
+ readonly resetsAt: string | undefined;
3294
+ /** Typed view of `error.details` (operation, weight, available, included, topup, used, resetsAt). */
3295
+ readonly details: CreditsExhaustedDetails | undefined;
3296
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, resetsAt?: string, context?: LexAPIErrorContext);
3297
+ /** The refused operation's credit weight (`details.weight`). */
3298
+ get weight(): number | undefined;
3299
+ /** Credits left in the pool (`details.available`). */
3300
+ get available(): number | undefined;
3301
+ /** The refused operation (`details.operation`). */
3302
+ get operation(): string | undefined;
3303
+ }
3304
+ /** `error.details` on a 402 `NATIONAL_ALLOWANCE_EXHAUSTED` envelope. */
3305
+ interface NationalAllowanceExhaustedDetails {
3306
+ /** ISO 3166-1 alpha-2 jurisdiction code of the call that was refused. */
3307
+ jurisdiction?: string;
3308
+ /** The tier's monthly allowance of national calls. */
3309
+ limit?: number;
3310
+ /** Always `0` on this error. */
3311
+ remaining?: number;
3312
+ /** When the allowance resets (ISO date-time: start of the next UTC month). */
3313
+ resetsAt?: string;
3314
+ /** `/pricing` — upgrading to BUSINESS removes the allowance entirely. */
3315
+ upgradeUrl?: string;
3316
+ [key: string]: unknown;
3317
+ }
3318
+ /**
3319
+ * 402 — the monthly national-law call allowance of a plan below BUSINESS
3320
+ * (FREE/STARTER/PROFESSIONAL) is used up (`NATIONAL_ALLOWANCE_EXHAUSTED`).
3321
+ * A usage shortfall, not a credit shortfall: no credits
3322
+ * were charged for the refused call. Resolves at `resetsAt` (start of next
3323
+ * UTC month) or immediately on upgrading to BUSINESS/SCALE/ENTERPRISE, which
3324
+ * have no separate limit. Mirrors `X-National-Limit`/`X-National-Remaining`/
3325
+ * `X-National-Reset` on the response that triggered it.
3326
+ */
3327
+ declare class NationalAllowanceExhaustedError extends LexAPIError {
3328
+ static readonly kind: string;
3329
+ /** Typed view of `error.details` (jurisdiction, limit, remaining, resetsAt, upgradeUrl). */
3330
+ readonly details: NationalAllowanceExhaustedDetails | undefined;
3331
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3332
+ /** The jurisdiction code of the refused call (`details.jurisdiction`). */
3333
+ get jurisdiction(): string | undefined;
3334
+ /** The tier's monthly allowance of national calls (`details.limit`). */
3335
+ get limit(): number | undefined;
3336
+ /** Always `0` (`details.remaining`). */
3337
+ get remaining(): number | undefined;
3338
+ /** When the allowance resets (`details.resetsAt`, ISO date-time). */
3339
+ get resetsAt(): string | undefined;
3340
+ /** `/pricing` (`details.upgradeUrl`). */
3341
+ get upgradeUrl(): string | undefined;
3342
+ }
3343
+ /** 502 — EUR-Lex returned an error (`UPSTREAM_ERROR`). Retry-safe on GETs. */
3344
+ declare class UpstreamError extends LexAPIError {
3345
+ static readonly kind: string;
3346
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3347
+ }
3348
+ /**
3349
+ * A timeout. Two cases, told apart by `code` / `status`:
3350
+ * - `TIMEOUT` (504, 524): the server or Cloudflare gave up on the upstream;
3351
+ * also a 503 from `getCounterparts` when the lookup exceeded its
3352
+ * server-side budget (`partial === true`, refunded).
3353
+ * - `REQUEST_TIMEOUT` (`status === 0`): the SDK's own response timeout —
3354
+ * no bytes for `timeoutMs` (SDK contract §1.6).
3355
+ */
3356
+ declare class TimeoutError extends LexAPIError {
3357
+ static readonly kind: string;
3358
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3359
+ /** `true` when the server answered a budget timeout with `partial: true` (nothing else was returned). */
3360
+ get partial(): boolean | undefined;
3361
+ /** The server-side budget that expired, in ms, when the body reports it. */
3362
+ get serverTimeoutMs(): number | undefined;
3363
+ }
3364
+ /**
3365
+ * 503 — service temporarily unavailable (e.g. while the service restarts).
3366
+ * Derived from the status (no typed code). Retried like 502/504.
3367
+ */
3368
+ declare class ServiceUnavailableError extends LexAPIError {
3369
+ static readonly kind: string;
3370
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext, code?: ErrorCode);
3371
+ }
3372
+ /**
3373
+ * 409 — this jurisdiction's semantic index isn't enabled at all
3374
+ * (`NATIONAL_SEMANTIC_NOT_ENABLED`). Legacy-shape body (`{code, error,
3375
+ * message, jurisdiction}`, no `error.details`) — `jurisdiction` is read off
3376
+ * the raw `body`, not `details`. Not retryable; the call was refunded in
3377
+ * full and never reached the national allowance counter.
3378
+ */
3379
+ declare class NationalSemanticNotEnabledError extends LexAPIError {
3380
+ static readonly kind: string;
3381
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3382
+ /** ISO 3166-1 alpha-2 jurisdiction code (top-level `jurisdiction` on the raw body). */
3383
+ get jurisdiction(): string | undefined;
3384
+ }
3385
+ /**
3386
+ * 503 — a jurisdiction's semantic index exists but is temporarily
3387
+ * unreachable (`NATIONAL_SEMANTIC_UNAVAILABLE`). Extends
3388
+ * `ServiceUnavailableError` so `instanceof ServiceUnavailableError` still
3389
+ * holds (and any existing 503-retry handling still catches it), while
3390
+ * `code`/`name` stay specific. Legacy-shape body, same as
3391
+ * `NationalSemanticNotEnabledError` — `jurisdiction` comes off `body`.
3392
+ */
3393
+ declare class NationalSemanticUnavailableError extends ServiceUnavailableError {
3394
+ static readonly kind: string;
3395
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3396
+ get jurisdiction(): string | undefined;
3397
+ /**
3398
+ * `"SEARCH_INCOMPLETE"` when the index could not complete this search for a
3399
+ * temporary reason and there was nothing left to return (an empty answer
3400
+ * would not have meant "no matches"). `retryAfter` is then the wait the
3401
+ * server asked for — absent once the same search has repeatedly come back
3402
+ * incomplete (try again later, or rephrase or narrow it). `undefined` on
3403
+ * the plain "index unavailable" 503.
3404
+ */
3405
+ get partialReason(): string | undefined;
3406
+ }
3407
+ /**
3408
+ * 422 — the national semantic index cannot search this slice (jurisdiction,
3409
+ * document kind and filters) completely and there is nothing left to return
3410
+ * (`NATIONAL_SEMANTIC_FILTER_UNREACHABLE`, `partialReason:
3411
+ * "SEARCH_INCOMPLETE"`). Not a "no matches" answer, and not temporary:
3412
+ * retrying the same request gives the same answer, so it is never retried —
3413
+ * rephrase the query or change the filters. Refunded in full. Extends
3414
+ * `InvalidParamsError` (the request has to change) while `code`/`name` stay
3415
+ * specific — but the request may be perfectly valid: this is a coverage
3416
+ * limit of the index, not a malformed request, and `param` is absent.
3417
+ * Legacy-shape body — `jurisdiction` comes off `body`.
3418
+ */
3419
+ declare class NationalSemanticFilterUnreachableError extends InvalidParamsError {
3420
+ static readonly kind: string;
3421
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3422
+ get jurisdiction(): string | undefined;
3423
+ /** `"SEARCH_INCOMPLETE"`. */
3424
+ get partialReason(): string | undefined;
3425
+ }
3426
+ /** `error.details` (typed envelope) or the raw body (legacy envelope) on a `DOCUMENT_WITHDRAWN` 410. */
3427
+ interface DocumentWithdrawnDetails {
3428
+ id?: string;
3429
+ jurisdiction?: string;
3430
+ /** ISO date-time the source withdrew the document; `null` when unknown. */
3431
+ withdrawnAt?: string | null;
3432
+ [key: string]: unknown;
3433
+ }
3434
+ /**
3435
+ * 410 — a national document its source withdrew (a takedown, a
3436
+ * pseudonymisation fix, a robots.txt listing). LexAPI
3437
+ * serves nothing of it: no title, no metadata, no text. Two envelope shapes
3438
+ * carry this code: the TYPED envelope on a direct document read
3439
+ * (`GET /{jurisdiction}/documents/{id}`, `error.details: {id, jurisdiction,
3440
+ * withdrawnAt}`), and the LEGACY shape with those same three fields as
3441
+ * top-level siblings of `code`/`error` on the citation routes (a withdrawn
3442
+ * id queried directly, or via `includeNational`). The getters below check
3443
+ * `details` first, then fall back to the raw `body` — correct for either
3444
+ * shape without the caller needing to know which one answered.
3445
+ *
3446
+ * Not retryable (the document is gone, not temporarily failing); never
3447
+ * charges anything (the credits/allowance refund rule already returns
3448
+ * every non-404 4xx-or-5xx). If you hold a cached copy of this document,
3449
+ * drop it — the source withdrew it for a reason that may include a legal
3450
+ * takedown or a pseudonymisation fix (see Terms §7, no re-identification).
3451
+ */
3452
+ declare class DocumentWithdrawnError extends LexAPIError {
3453
+ static readonly kind: string;
3454
+ readonly details: DocumentWithdrawnDetails | undefined;
3455
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
3456
+ private field;
3457
+ /** The withdrawn document's id (e.g. `AT-NOR-10001597`). */
3458
+ get id(): string | undefined;
3459
+ /** Upper-case jurisdiction code. */
3460
+ get jurisdiction(): string | undefined;
3461
+ /** ISO date-time the source withdrew the document; `undefined` when unknown. */
3462
+ get withdrawnAt(): string | undefined;
3463
+ }
3464
+ /** 500 — unexpected server failure (`INTERNAL`). Not retried by default. */
3465
+ declare class InternalServerError extends LexAPIError {
3466
+ static readonly kind: string;
3467
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
1822
3468
  }
1823
- interface WebhookWatchlistChangesPayload extends WebhookDeliveryEnvelope {
1824
- event: "watchlist.changes";
1825
- data: {
1826
- /** Changes in this delivery (max 100). */
1827
- count: number;
1828
- changes: WebhookWatchlistChange[];
1829
- };
3469
+ /** Transport-level failure: DNS, connection reset, etc. No HTTP response was received. */
3470
+ declare class NetworkError extends LexAPIError {
3471
+ static readonly kind: string;
3472
+ readonly cause: unknown;
3473
+ constructor(message: string, cause?: unknown);
1830
3474
  }
1831
- /** Sent by `webhooks.test()`. */
1832
- interface WebhookTestPayload extends WebhookDeliveryEnvelope {
1833
- event: "webhook.test";
1834
- data: {
1835
- message: string;
1836
- searchCriteria?: WebhookCriteria | null;
1837
- };
3475
+ /** The caller's `AbortSignal` fired (status 0). Never retried. `cause` is the signal's reason. */
3476
+ declare class RequestAbortedError extends LexAPIError {
3477
+ static readonly kind: string;
3478
+ readonly cause: unknown;
3479
+ constructor(message: string, cause?: unknown);
1838
3480
  }
1839
- /** Discriminated union of every payload LexAPI delivers — switch on `event`. */
1840
- type WebhookPayload = WebhookDocumentsNewPayload | WebhookWatchlistChangesPayload | WebhookTestPayload;
1841
3481
  /**
1842
- * One entry in a document's version history.
3482
+ * A 2xx response that is not the documented shape: no body, a body that is
3483
+ * not JSON (e.g. an HTML page from a proxy), JSON that is not an object,
3484
+ * `success: false` without an error, or a list field that is missing, not a
3485
+ * list, or holds items that are not objects. Thrown instead of returning an
3486
+ * empty, "successful" result.
1843
3487
  *
1844
- * Versions are LexAPI *observation snapshots* (content-hash changes between
1845
- * fetches), not legal in-force reconstructions — for the text in force on a
1846
- * date use a consolidated CELEX, or `semanticLegislationSearch({ asOf })`.
1847
- * `fetchedAt` is when THIS version was fetched — version N is "current"
1848
- * from there until version N+1's `fetchedAt`.
3488
+ * The message names what was expected and what arrived and never quotes the
3489
+ * body. For JSON of the wrong shape, `body` holds the parsed value; for a
3490
+ * body that is not JSON, `bodyExcerpt` holds its first 200 characters (code
3491
+ * points). Both are raw response content that may contain document text: do
3492
+ * not show them to a model or log them by default. Neither is an own
3493
+ * property of the error, so default logging does not print them.
1849
3494
  */
1850
- interface VersionEntry {
1851
- version: number;
1852
- isCurrent: boolean;
3495
+ declare class InvalidResponseError extends LexAPIError {
3496
+ static readonly kind: string;
3497
+ constructor(message: string, status: number, body?: unknown, context?: LexAPIErrorContext);
3498
+ }
3499
+ /**
3500
+ * An export stream ended (cleanly, at EOF) without its trailing `_done` line —
3501
+ * the server stopped mid-export (SDK contract §1.8). Raised after the rows
3502
+ * that did arrive were yielded; they are NOT a complete export.
3503
+ */
3504
+ declare class IncompleteExportError extends LexAPIError {
3505
+ static readonly kind: string;
3506
+ /** Rows yielded before the stream ended. */
3507
+ readonly rowsRead: number;
1853
3508
  /**
1854
- * Equal hashes mean no text change. A different hash usually means EUR-Lex
1855
- * changed the text — or the current version was re-parsed in place by an
1856
- * improved parser.
3509
+ * @param details the server's `_error` line body (`{ code, message }`) when
3510
+ * one arrived; `undefined` for a missing or `complete: false` trailer.
1857
3511
  */
1858
- contentHash: string;
1859
- fetchedAt: string;
1860
- title?: string | null;
1861
- documentType?: string | null;
1862
- documentTypeCode?: string | null;
1863
- /** Present on single-snapshot responses only (not in history listings). */
1864
- parsedContent?: Record<string, unknown> | null;
3512
+ constructor(message: string, rowsRead: number, details?: unknown);
1865
3513
  }
1866
- interface DocumentVersionsResponse extends CreditedResponse, WithResponseHeaders {
1867
- success: boolean;
1868
- celex: string;
1869
- language: string;
1870
- currentVersion: number;
1871
- /** When the document first entered the corpus — history starts here. */
1872
- trackedSince: string;
1873
- /** Server restatement of the observation-snapshot semantics. */
1874
- semantics: string;
1875
- /** Newest first; the current version is included and flagged. */
1876
- versions: VersionEntry[];
3514
+ /**
3515
+ * `true` for any error thrown by this SDK — from either build (ESM or
3516
+ * CommonJS) or another installed copy. Pass a class to narrow:
3517
+ * `isLexAPIError(err, NotFoundError)`.
3518
+ */
3519
+ declare function isLexAPIError<T extends LexAPIError = LexAPIError>(value: unknown, errorClass?: abstract new (...args: never[]) => T): value is T;
3520
+
3521
+ declare const DEFAULT_BASE_URL = "https://lex-api.com/api/v1";
3522
+ /**
3523
+ * Per-attempt timeout. The 95 s default sits above the API's 90 s deadline on
3524
+ * document reads, so that timeout comes back as a typed, refunded 504; the
3525
+ * CDN ends any wait at 100 s.
3526
+ */
3527
+ declare const DEFAULT_TIMEOUT_MS = 95000;
3528
+ /** Retry policy knobs (SDK contract §1.2). */
3529
+ interface RetryOptions {
3530
+ /** Max retries after the initial attempt. Default 3. Set 0 to disable retries. */
3531
+ maxRetries?: number;
3532
+ /** Exponential backoff base. Default 500 ms. */
3533
+ baseDelayMs?: number;
3534
+ /**
3535
+ * Cap on any single wait (computed or server-directed). Default 30 000 ms.
3536
+ * A cap below the server's requested wait (`Retry-After` / `retryAfter`)
3537
+ * shortens that wait, so the retry may come too early.
3538
+ */
3539
+ maxDelayMs?: number;
3540
+ /**
3541
+ * SDK contract §1.2 opt-in (default `false`): also retry the ten
3542
+ * read-only POSTs (`search`, `getDocument`, `getDocumentsBatch`,
3543
+ * `getDocumentByUrl`, `getDocumentMetadata`, `resolve`, `semanticSearch`,
3544
+ * `semanticLegislationSearch`, `nationalSemanticSearch`,
3545
+ * `nationalLegislationSemanticSearch`) on an **app-origin** 502/503/504 — those
3546
+ * are refunded in full, so the retry is billing-safe. App-origin = a
3547
+ * non-empty `X-LexAPI-Version` or a `RateLimit-Limit` header; anything
3548
+ * else is treated as a proxy answer and never retried on a billed call. Never applies to mutating calls (webhook
3549
+ * writes, `extractCitations`).
3550
+ */
3551
+ retryReadOnlyPosts?: boolean;
1877
3552
  }
1878
- interface DocumentVersionResponse extends CreditedResponse, WithResponseHeaders {
1879
- success: boolean;
1880
- celex: string;
1881
- language: string;
1882
- /** Present on `/at/{date}` responses only — the requested date. */
1883
- asOf?: string;
1884
- semantics: string;
1885
- document: VersionEntry;
1886
- /** SDK-added: mirrors the `X-Corpus-Version` response header. */
1887
- corpusVersion?: number;
3553
+ interface HttpClientOptions {
3554
+ apiKey: string;
3555
+ baseUrl: string;
3556
+ timeoutMs: number;
3557
+ fetchFn: typeof fetch;
3558
+ retry: Required<RetryOptions>;
3559
+ userAgentSuffix?: string | undefined;
1888
3560
  }
1889
- /** Shared params for the version endpoints. */
1890
- interface VersionParams {
1891
- /** 2-letter ISO language of the tracked corpus row (default `en`). */
1892
- language?: string;
3561
+ /** Query values; arrays are sent as repeated parameters (`?a=x&a=y`). */
3562
+ type QueryParams = Record<string, string | number | boolean | undefined | ReadonlyArray<string | number | boolean>>;
3563
+ interface RequestOptions {
3564
+ method: "GET" | "POST" | "PUT" | "DELETE";
3565
+ path: string;
3566
+ query?: QueryParams;
3567
+ body?: unknown;
3568
+ /** Per-call timeout override (per attempt, covering the response body). */
3569
+ timeoutMs?: number | undefined;
3570
+ /** Caller cancellation: aborts the in-flight attempt and any retry wait. */
3571
+ signal?: AbortSignal | undefined;
3572
+ /** `Accept` header override (default `application/json`). */
3573
+ accept?: string;
3574
+ /**
3575
+ * One of the ten read-only POSTs of SDK contract §1.2 — retried on
3576
+ * app-origin 502/503/504 when `retryReadOnlyPosts` is on.
3577
+ */
3578
+ idempotent?: boolean;
3579
+ /**
3580
+ * A free operation (0 credits: `/info`, webhook reads). A retry cannot
3581
+ * charge, so proxy-origin 5xx/520/524 and post-send transport errors are
3582
+ * retried too (SDK contract §1.2).
3583
+ */
3584
+ free?: boolean;
3585
+ /**
3586
+ * @internal What a 2xx answer must look like (SDK contract §1.3); every
3587
+ * JSON method checks that the body is a JSON object without `success: false`.
3588
+ */
3589
+ shape?: ResponseShape;
3590
+ }
3591
+ /** @internal A field a 2xx answer always carries, and its kind. */
3592
+ interface RequiredField {
3593
+ path: string;
3594
+ kind: "object" | "string" | "boolean";
3595
+ }
3596
+ /** @internal The documented shape of a 2xx JSON answer (SDK contract §1.3). */
3597
+ interface ResponseShape {
3598
+ /** List fields (dotted paths for nested ones): when present and not `null`, a list of objects. */
3599
+ lists?: readonly string[];
3600
+ /** List fields the endpoint always sends: missing or `null` is an error. Checked first. */
3601
+ required?: readonly string[];
3602
+ /**
3603
+ * Fields the endpoint always sends, with their kind: missing or `null` (an
3604
+ * empty string for `string`) is an error, and so is a value of another kind.
3605
+ */
3606
+ fields?: readonly RequiredField[];
3607
+ /** Object fields that, when present and not `null`, must be a JSON object. */
3608
+ optionalObjects?: readonly string[];
3609
+ /** `success: false` is a normal answer here (`POST /webhooks/{id}/test`). */
3610
+ successFalseOk?: boolean;
3611
+ /** A 204 or an empty body is an empty result (`DELETE /webhooks/{id}`). */
3612
+ allowEmpty?: boolean;
3613
+ }
3614
+ declare const INSPECT: unique symbol;
3615
+ /**
3616
+ * Single request core used by every SDK method.
3617
+ *
3618
+ * - `x-api-key` auth + `User-Agent: lexapi-typescript/<version>` on every
3619
+ * request (UA omitted on browser runtimes, where it cannot be set). The key
3620
+ * lives in a private field and never appears in `util.inspect`,
3621
+ * `console.log` or `JSON.stringify` output.
3622
+ * - One inactivity timeout per attempt (SDK contract §1.6): it runs until
3623
+ * the response head arrives and restarts on every body chunk, for JSON
3624
+ * bodies and export streams alike.
3625
+ * - Caller `AbortSignal`: aborts the attempt and any retry wait; throws
3626
+ * `RequestAbortedError`, never retried.
3627
+ * - Retries follow the billing-safety rule of SDK contract §1.2 — only when
3628
+ * a retry cannot charge twice (see `shouldRetryStatus`).
3629
+ * - Redirects are followed only within the API origin (or to the same host
3630
+ * over HTTPS on the default ports), at most five per attempt; any other
3631
+ * redirect is refused with a `NetworkError`, so the API key is never sent
3632
+ * to another origin. A custom `fetch` must honour `redirect: "manual"` for
3633
+ * this to hold. The attempt's timeout covers the whole redirect chain.
3634
+ * - Server-directed waits: `Retry-After` on any status; on a 429 only, then
3635
+ * `RateLimit-Reset` and the JSON `retryAfter` field; on a 503
3636
+ * `NATIONAL_SEMANTIC_UNAVAILABLE`, the JSON `retryAfter` field.
3637
+ * `X-RateLimit-*` is never read.
3638
+ */
3639
+ declare class HttpClient {
3640
+ #private;
3641
+ private readonly opts;
3642
+ private readonly userAgent;
3643
+ constructor(opts: HttpClientOptions);
3644
+ /** API base URL. */
3645
+ get baseUrl(): string;
3646
+ /** Client-level per-attempt timeout (ms). */
3647
+ get timeoutMs(): number;
3648
+ /** Redacted view for `JSON.stringify` — never includes the API key. */
3649
+ toJSON(): Record<string, unknown>;
3650
+ /** Redacted view for `util.inspect` / `console.log`. */
3651
+ [INSPECT](): string;
3652
+ /**
3653
+ * Perform a request and parse the JSON body. A 2xx that is not the
3654
+ * documented shape (`options.shape`) throws `InvalidResponseError`.
3655
+ */
3656
+ requestJson<T>(options: RequestOptions): Promise<T>;
3657
+ /**
3658
+ * Like `requestJson`, but also exposes the raw `Response` (for header
3659
+ * signals). The body is read inside the attempt, under its timeout.
3660
+ */
3661
+ requestJsonWithResponse<T>(options: RequestOptions): Promise<{
3662
+ data: T;
3663
+ response: Response;
3664
+ }>;
3665
+ /**
3666
+ * Perform a request and return the raw successful `Response` without
3667
+ * consuming the body (streaming endpoints such as `/export`). The attempt
3668
+ * timeout covers only the response headers; the caller applies its own
3669
+ * idle timeout to body reads. Non-2xx responses are parsed and thrown as
3670
+ * typed errors; the retry policy applies before the first body byte.
3671
+ */
3672
+ requestRaw(options: RequestOptions): Promise<Response>;
3673
+ private execute;
3674
+ /**
3675
+ * `fetch` with redirects followed here rather than by the runtime, which
3676
+ * would repeat every request header to whichever host a redirect names.
3677
+ * Method and body change as `fetch` changes them: a 303, or a 301/302
3678
+ * answer to a POST, continues as a body-less GET; 307/308 repeat the request.
3679
+ * The body of a redirect response is cancelled, so its connection is released.
3680
+ * A response that says it was already redirected (a custom `fetch` that did
3681
+ * not honour `redirect: "manual"`) is refused.
3682
+ */
3683
+ private fetchWithinOrigin;
1893
3684
  }
1894
3685
 
1895
3686
  /** A list filter: an array, or a comma-separated string (`"regulation,directive"`). */
1896
3687
  type ExportListFilter = string | ReadonlyArray<string>;
1897
3688
  /**
1898
- * Filters for `GET /export` (API 2.3.0, lex-api #303). List values are sent
3689
+ * Filters for `GET /export` (API 2.3.0). List values are sent
1899
3690
  * comma-separated and ORed.
1900
3691
  */
1901
3692
  interface ExportParams {
@@ -1945,7 +3736,7 @@ interface ExportParams {
1945
3736
  /**
1946
3737
  * Max rows to stream: a positive integer (anything else throws a
1947
3738
  * `RangeError` before the request — the API answers 400). Clamped to the
1948
- * server's `EXPORT_MAX_ROWS` ceiling (default 50 000).
3739
+ * server's row ceiling (50,000).
1949
3740
  */
1950
3741
  limit?: number;
1951
3742
  }
@@ -2070,8 +3861,9 @@ interface ExportHeaderInfo {
2070
3861
  */
2071
3862
  streaming: number | undefined;
2072
3863
  /**
2073
- * `X-Export-Truncated: 1` — the up-front count exceeded the row cap. A hint
2074
- * only; `stream.truncated` prefers `_done.truncated` once it is read.
3864
+ * `X-Export-Truncated: 1` — the up-front count exceeded the row cap (`0`:
3865
+ * it did not; any other value is `undefined`). A hint only;
3866
+ * `stream.truncated` prefers `_done.truncated` once it is read.
2075
3867
  */
2076
3868
  truncated: boolean | undefined;
2077
3869
  }
@@ -2095,8 +3887,13 @@ interface ExportHeaderInfo {
2095
3887
  * after the rows that did arrive (the `_error` body is on its `details` and
2096
3888
  * on `stream.error`). Unknown `_done` fields (`truncatedBy`, `credits`) are
2097
3889
  * kept on `done`.
2098
- * - Lines that are not JSON objects are counted in `invalidLines`, not yielded.
2099
- * - `_meta`/`_done`/`_error` lines are never yielded as rows.
3890
+ * - A line ends at a line feed byte only. Lines are read as strict UTF-8,
3891
+ * whatever charset the response names (one byte order mark at the very
3892
+ * start of the stream is ignored), with spaces, tabs and carriage returns
3893
+ * trimmed; blank lines are skipped. Lines that are not UTF-8, or not one
3894
+ * JSON object, are counted in `invalidLines`, not yielded.
3895
+ * - `_meta`/`_done`/`_error` lines are never yielded as rows; `meta` comes
3896
+ * only from the very first line of the stream.
2100
3897
  */
2101
3898
  interface ExportStream extends AsyncIterable<ExportRow> {
2102
3899
  readonly meta: ExportMeta | undefined;
@@ -2121,9 +3918,10 @@ interface ExportStream extends AsyncIterable<ExportRow> {
2121
3918
  * pool, see `done.truncatedBy`; never derived from the count; skipped stubs
2122
3919
  * do not count). Before the trailer: the `X-Export-Truncated` header, then
2123
3920
  * `_meta.truncated` — hints from the up-front count, which may be cached
2124
- * for up to a minute and never caps the stream. `undefined` when unknown.
3921
+ * for up to a minute and never caps the stream. `false` when none of
3922
+ * these says.
2125
3923
  */
2126
- readonly truncated: boolean | undefined;
3924
+ readonly truncated: boolean;
2127
3925
  /**
2128
3926
  * Abandon the export and release the connection (e.g. after inspecting
2129
3927
  * `meta` without iterating). Breaking out of `for await` does this too.
@@ -2199,7 +3997,13 @@ declare class WebhooksAPI {
2199
3997
  * 50), starting at `offset`, newest first (SDK contract §1.4). Each
2200
3998
  * delivery is yielded at most once (deduplicated on `id`): a delivery
2201
3999
  * created during the walk shifts later pages by one. Stops on an empty page
2202
- * or when the offset reaches `total`. Pages are free (0 credits).
4000
+ * or when the offset reaches `total`. Without a usable `total`, three pages
4001
+ * in a row that bring no unseen `id` throw `InvalidResponseError` (a page
4002
+ * with a usable `total` ends a run). When a walk throws, the pages already
4003
+ * yielded stay valid; the page that showed the stall is not yielded and is
4004
+ * on the error's `body`. A starting `offset` or `limit` that is not a
4005
+ * non-negative (positive) integer is a `RangeError` before any request.
4006
+ * Pages are free (0 credits).
2203
4007
  *
2204
4008
  * ```ts
2205
4009
  * for await (const page of client.webhooks.paginateDeliveries(id)) {
@@ -2221,13 +4025,16 @@ interface LexAPIOptions {
2221
4025
  baseUrl?: string;
2222
4026
  /**
2223
4027
  * Per-attempt timeout in milliseconds, covering the response body (for
2224
- * `export`: an idle timeout per read). Default 95_000 — enough for a
2225
- * single live EUR-Lex fetch (the API caps each at 90 s, then answers with
2226
- * a typed, refunded 504), and below Cloudflare's 100 s proxy timeout. A
2227
- * request that needs several upstream fetches can still exceed it.
4028
+ * `export`: an idle timeout per read). The 95 s default sits above the
4029
+ * API's 90 s deadline on document reads, so that timeout comes back as a
4030
+ * typed, refunded 504; the CDN ends any wait at 100 s.
2228
4031
  */
2229
4032
  timeoutMs?: number;
2230
- /** Injectable fetch (used for testing / polyfills). Defaults to global fetch. */
4033
+ /**
4034
+ * Injectable fetch (used for testing / polyfills). Defaults to global fetch.
4035
+ * It is called with `redirect: "manual"` and must honour it: the SDK follows
4036
+ * redirects itself, and only within the API origin.
4037
+ */
2231
4038
  fetch?: typeof fetch;
2232
4039
  /** Retry policy. Default: 3 retries, 500 ms base, 30 s cap; read-only POST 5xx retries are opt-in. */
2233
4040
  retry?: RetryOptions;
@@ -2352,22 +4159,36 @@ declare class LexAPI {
2352
4159
  resolve(identifier: string, options?: CallOptions): Promise<ResolveResponse>;
2353
4160
  /**
2354
4161
  * `GET /documents/{celex}/versions` — version history, newest first,
2355
- * current version included and flagged. 1 credit.
4162
+ * current version included and flagged. These are LexAPI's fetch
4163
+ * snapshots, not the law in force on a date; for the version of an EU act
4164
+ * for a date use `legislationAsOf`. 1 credit.
2356
4165
  */
2357
4166
  listDocumentVersions(celex: string, params?: VersionParams, options?: CallOptions): Promise<DocumentVersionsResponse>;
2358
4167
  /**
2359
4168
  * `GET /documents/{celex}/versions/{version}` — one immutable snapshot
2360
4169
  * including `parsedContent`. `corpusVersion` mirrors the
2361
- * `X-Corpus-Version` response header. 1 credit.
4170
+ * `X-Corpus-Version` response header. This is one of LexAPI's fetch
4171
+ * snapshots, not the law in force on a date; for the version of an EU act
4172
+ * for a date use `legislationAsOf`. 1 credit.
2362
4173
  */
2363
4174
  getDocumentVersion(celex: string, version: number, params?: VersionParams, options?: CallOptions): Promise<DocumentVersionResponse>;
2364
4175
  /**
2365
- * `GET /documents/{celex}/at/{date}` — the snapshot LexAPI observed as
2366
- * current on `date` (`YYYY-MM-DD`, end-of-day UTC inclusive). Dates
2367
- * before the document entered the corpus reject with `NotFoundError`
2368
- * carrying the tracking start date. 1 credit.
4176
+ * `GET /documents/{celex}/at/{date}` — the snapshot LexAPI held as current
4177
+ * at the end of `date` (`YYYY-MM-DD`, UTC), from its own fetch history
4178
+ * (`kind: "observation_snapshot"`). This is not the law in force on that
4179
+ * date: for the version of an EU act for a date use `legislationAsOf`
4180
+ * (`inForceLookup` points to it). The snapshot was the current one from
4181
+ * `document.observedFrom` until `document.observedUntil` (`null` for the
4182
+ * current version). A future date returns the current version with
4183
+ * `dateInFuture: true`.
4184
+ *
4185
+ * A date before the document entered the corpus rejects with
4186
+ * `NotFoundError` where `beforeTracking` is `true` (`trackedSince`); a date
4187
+ * next to a version stored before API 2.28.0 whose start LexAPI has no
4188
+ * record of rejects with `boundaryUnknown` `true` and `candidates`
4189
+ * (refunded). 1 credit.
2369
4190
  */
2370
- getDocumentAtDate(celex: string, date: string, params?: VersionParams, options?: CallOptions): Promise<DocumentVersionResponse>;
4191
+ getDocumentAtDate(celex: string, date: string, params?: VersionParams, options?: CallOptions): Promise<DocumentAtDateResponse>;
2371
4192
  /**
2372
4193
  * `POST /citations/extract` — crawl a document's EUR-Lex metadata page
2373
4194
  * for citations and persist them into the graph. Idempotent: an already
@@ -2379,13 +4200,29 @@ declare class LexAPI {
2379
4200
  * `GET /citations/cites/{celexNumber}` — documents this one cites
2380
4201
  * (outbound edges), grouped by target. The document must first have been
2381
4202
  * crawled via `extractCitations` to appear here. 1 credit.
4203
+ *
4204
+ * `celexNumber` may be a national document id (e.g. `AT-NOR-10001597`);
4205
+ * `params.includeNational` also pulls in national neighbours of live
4206
+ * jurisdictions — BUSINESS, SCALE and ENTERPRISE only (`403
4207
+ * TierForbiddenError` below that, refunded in full). A national id whose
4208
+ * jurisdiction is not live is `404 NotFoundError`.
4209
+ *
4210
+ * Filters (API 2.11.0): `citationType`, `provenance`, `jurisdictions` and
4211
+ * `resolution` each take one value or a list (sent comma-separated). On a
4212
+ * national id, `unresolved: true` also returns the references the
4213
+ * document records that could not be turned into an edge
4214
+ * (`unresolved` / `unresolvedTruncated`), at no extra cost.
2382
4215
  */
2383
- getCites(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): Promise<CitesResponse>;
4216
+ getCites(celexNumber: string, params?: CitesParams, options?: CallOptions): Promise<CitesResponse>;
2384
4217
  /**
2385
4218
  * `GET /citations/cited-by/{celexNumber}` — documents that cite this one
2386
4219
  * (inbound edges), grouped by source. 1 credit. For legislation, inbound
2387
4220
  * amendment / corrigendum / repeal edges are refreshed from Cellar when
2388
4221
  * older than 7 days (waits ≤ ~2.5 s) — see `relationSync`.
4222
+ *
4223
+ * `celexNumber` may be a national document id; `params.includeNational`
4224
+ * also pulls in national neighbours of live jurisdictions — BUSINESS+
4225
+ * only (`403 TierForbiddenError` below that). Filters as on `getCites`.
2389
4226
  */
2390
4227
  getCitedBy(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): Promise<CitedByResponse>;
2391
4228
  /**
@@ -2396,13 +4233,34 @@ declare class LexAPI {
2396
4233
  * missed. A target's edges can straddle a page boundary, so the same
2397
4234
  * `celexNumber` may appear in two consecutive pages — merge by
2398
4235
  * `celexNumber` if you need one group per document.
4236
+ * The walk also ends once the offset reaches `totalEdges`, when that is a
4237
+ * non-negative integer. It throws `InvalidResponseError` when a page echoes
4238
+ * an `offset` other than the one requested, or, when the answers carry
4239
+ * neither `totalEdges` nor `offset`, after three pages in a row that each
4240
+ * repeat the one before (comparing the list only; a page with either
4241
+ * signal ends a run, and its list is still the one the next page is
4242
+ * compared with). When a walk throws, the pages already yielded stay
4243
+ * valid; the page that showed the stall is not yielded and is on the
4244
+ * error's `body`. A starting `offset` or `limit` that is not a non-negative
4245
+ * (positive) integer is a `RangeError` before any request. A group whose
4246
+ * `citationCount` is 0 but whose edge list is not empty counts its list.
2399
4247
  */
2400
- paginateCites(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): AsyncGenerator<CitesResponse, void>;
4248
+ paginateCites(celexNumber: string, params?: CitesParams, options?: CallOptions): AsyncGenerator<CitesResponse, void>;
2401
4249
  /**
2402
4250
  * Walk every page of `getCitedBy` (offset in edge rows) until a short or
2403
4251
  * empty page (SDK contract §1.4). Each page is a billed call (1 credit);
2404
4252
  * edges may repeat or be missed if extractions happen during the walk. A source's edges can straddle a page boundary, so the same
2405
4253
  * `celexNumber` may appear in two consecutive pages.
4254
+ * The walk also ends once the offset reaches `totalEdges`, when that is a
4255
+ * non-negative integer. It throws `InvalidResponseError` when a page echoes
4256
+ * an `offset` other than the one requested, or, when the answers carry
4257
+ * neither `totalEdges` nor `offset`, after three pages in a row that each
4258
+ * repeat the one before (comparing the list only; a page with either
4259
+ * signal ends a run, and its list is still the one the next page is
4260
+ * compared with). When a walk throws, the pages already yielded stay
4261
+ * valid; the page that showed the stall is not yielded and is on the
4262
+ * error's `body`. A starting `offset` or `limit` that is not a non-negative
4263
+ * (positive) integer is a `RangeError` before any request.
2406
4264
  */
2407
4265
  paginateCitedBy(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): AsyncGenerator<CitedByResponse, void>;
2408
4266
  /**
@@ -2412,6 +4270,10 @@ declare class LexAPI {
2412
4270
  * If the server-side wall-clock budget expires the endpoint still
2413
4271
  * returns 200 with `partial: true`, an EMPTY `network`, and `null`
2414
4272
  * paging totals — check `partial` before treating the network as empty.
4273
+ *
4274
+ * `celexNumber` may be a national document id; `params.includeNational`
4275
+ * also pulls in national neighbours of live jurisdictions — BUSINESS+
4276
+ * only (`403 TierForbiddenError` below that). See `getCites`.
2415
4277
  */
2416
4278
  getCitationNetwork(celexNumber: string, params?: CitationNetworkParams, options?: CallOptions): Promise<CitationNetworkResponse>;
2417
4279
  /**
@@ -2419,6 +4281,10 @@ declare class LexAPI {
2419
4281
  * outbound edges). 20 credits. `found: false` is a graceful HTTP 200,
2420
4282
  * not an error. Default `maxDepth` 3 (max 8); the visited set is bounded
2421
4283
  * to 5000 nodes.
4284
+ *
4285
+ * `from`/`to` may be national document ids; `params.includeNational` also
4286
+ * follows national documents of live jurisdictions along the way —
4287
+ * BUSINESS+ only (`403 TierForbiddenError` below that). See `getCites`.
2422
4288
  */
2423
4289
  getCitationPath(from: string, to: string, params?: CitationPathParams, options?: CallOptions): Promise<CitationPathResponse>;
2424
4290
  /**
@@ -2426,10 +4292,164 @@ declare class LexAPI {
2426
4292
  * neighbours (documents sharing the most outbound citation targets with
2427
4293
  * the seed). 20 credits. Returns a graceful empty list with `message`
2428
4294
  * when the seed has no outbound citations to couple on.
4295
+ *
4296
+ * `celexNumber` may be a national document id; `params.includeNational`
4297
+ * also considers national documents of live jurisdictions — BUSINESS+
4298
+ * only (`403 TierForbiddenError` below that). See `getCites`.
2429
4299
  */
2430
4300
  getRelatedDocuments(celexNumber: string, params?: RelatedDocumentsParams, options?: CallOptions): Promise<RelatedDocumentsResponse>;
2431
- /** `GET /citations/stats` — global citation graph statistics. 20 credits. */
4301
+ /**
4302
+ * `GET /citations/stats` — global citation graph statistics. 20 credits.
4303
+ *
4304
+ * `params.includeNational` also counts national documents of live
4305
+ * jurisdictions — BUSINESS+ only (`403 TierForbiddenError` below that).
4306
+ *
4307
+ * **Back-compat:** 0.2.0's signature was `getCitationStats(options?:
4308
+ * CallOptions)`. Both the single-argument form (`getCitationStats({
4309
+ * timeoutMs, signal })`) and the current two-argument form
4310
+ * (`getCitationStats(params, options)`) keep working — overloaded here so
4311
+ * TypeScript callers on either shape type-check, and a first argument
4312
+ * that looks like `CallOptions` rather than `CitationStatsParams` is also
4313
+ * detected at runtime (for a non-literal variable or a JS caller, which
4314
+ * the overloads alone can't catch) and honoured as the per-call options
4315
+ * rather than silently read as `params` with the timeout or abort signal
4316
+ * dropped.
4317
+ */
2432
4318
  getCitationStats(options?: CallOptions): Promise<CitationStatsResponse>;
4319
+ getCitationStats(params: CitationStatsParams, options?: CallOptions): Promise<CitationStatsResponse>;
4320
+ /**
4321
+ * `GET /citations/transposition/{celexNumber}` — the measures the member
4322
+ * states notified to the Commission for an EU act (CELEX sector 3),
4323
+ * grouped by country, from the Publications Office's Cellar records of the
4324
+ * notifications (API 2.11.0). **A notification is not a finding that the
4325
+ * measure transposes the act, or transposes it completely** — `note` says
4326
+ * so on every answer. 5 credits, every plan; a 5xx is refunded.
4327
+ *
4328
+ * On BUSINESS, SCALE and ENTERPRISE, for live jurisdictions, the answer
4329
+ * also says which measures LexAPI holds (`id`, `resolved`, `resolution`,
4330
+ * `resolutionBasis`, `counts.resolved`, `source.lanes`) and adds the
4331
+ * documents whose national source records that they transpose or
4332
+ * implement the act (`provenance: "source"`); `resolvedOnly: true` keeps
4333
+ * only the held ones. Below BUSINESS, for a jurisdiction that is not live,
4334
+ * and while the national-source terms are not accepted (`termsRequired:
4335
+ * true` — never a 403) those fields are `null`.
4336
+ *
4337
+ * A CELEX that is not an EU act (sector 3) is `404 NotFoundError`.
4338
+ */
4339
+ getTransposition(celexNumber: string, params?: TranspositionParams, options?: CallOptions): Promise<TranspositionResponse>;
4340
+ /**
4341
+ * `GET /citations/counterparts/{id}` — a national document's counterparts
4342
+ * in the other live jurisdictions, through the EU acts it transposes or
4343
+ * implements (API 2.11.0). Each `via[]` entry is one EU act, with the
4344
+ * other jurisdictions' measures for it ranked `1` (the national source
4345
+ * records the relation), `2` (a notified measure LexAPI holds) or `3` (a
4346
+ * notified Cellar record LexAPI does not hold, `id: null`). An EU act
4347
+ * CELEX as `id` lists its own measures the same way.
4348
+ *
4349
+ * **20 credits; BUSINESS, SCALE and ENTERPRISE only** (`403
4350
+ * TierForbiddenError` below that, refunded). A lookup past its 20-second
4351
+ * server-side budget throws `TimeoutError` (503, `err.partial === true`),
4352
+ * refunded. The SDK does not retry it (the same lookup would hit the same
4353
+ * budget); retry yourself, or narrow with `jurisdictions`.
4354
+ */
4355
+ getCounterparts(id: string, params?: CounterpartsParams, options?: CallOptions): Promise<CounterpartsResponse>;
4356
+ /**
4357
+ * `GET /national/coverage` — which jurisdictions are live, what each one
4358
+ * covers (legislation / case law, semantic search, sources with their
4359
+ * attribution), and when each was last synced. Public: no API key or
4360
+ * allowance required, free.
4361
+ */
4362
+ getNationalCoverage(options?: CallOptions): Promise<NationalCoverageResponse>;
4363
+ /**
4364
+ * `GET /{jurisdiction}/documents/{id}` — one national document by its
4365
+ * corpus id (e.g. `"AT-NOR-12345"`), analogous to `getDocument`.
4366
+ *
4367
+ * **Cost: 1 credit** — every national read is a corpus read (there is no
4368
+ * live-fetch fallback), so the 5-credit upfront reservation always
4369
+ * settles to 1 (an unknown id too). Check
4370
+ * `document.textAvailability.available` before reading `content`, and
4371
+ * always show `document.attribution` to the user alongside the text.
4372
+ * The document has one shape for every jurisdiction (API 2.8.0):
4373
+ * `documentKind` (`act` | `decision`), `decision` (court, chamber,
4374
+ * caseNumbers, citedNorms — `null` for acts; see `isNationalDecision`)
4375
+ * and the closed `content` key set.
4376
+ *
4377
+ * A document its source withdrew (a takedown, a pseudonymisation fix)
4378
+ * throws `DocumentWithdrawnError` (410) instead of answering — nothing of
4379
+ * it is served, not even the title; drop any copy you hold.
4380
+ */
4381
+ getNationalDocument(jurisdiction: string, id: string, params?: {
4382
+ language?: string;
4383
+ }, options?: CallOptions): Promise<NationalDocumentResponse>;
4384
+ /**
4385
+ * `GET /{jurisdiction}/documents` — browse a jurisdiction's corpus by
4386
+ * title (`q`), type, and in-force status. Newest-first by the document's
4387
+ * own date.
4388
+ *
4389
+ * **Cost: 3 credits per call** — flat; pagination does not multiply the
4390
+ * price, unlike `search`. **Paging:** `page` only reaches the first 1,000
4391
+ * rows (a 400 past that); page further with `cursor` (each response's
4392
+ * `nextCursor`), which works at any depth — see
4393
+ * `paginateNationalDocuments` for a ready-made walk. A slow page is a
4394
+ * retry-safe `TimeoutError` (504, refunded); the `total` count is capped
4395
+ * at 10,000 and flagged `totalExact: false` past that or on a slow count.
4396
+ */
4397
+ listNationalDocuments(jurisdiction: string, params?: NationalDocumentListParams, options?: CallOptions): Promise<NationalDocumentListResponse>;
4398
+ /**
4399
+ * Walk every page of `listNationalDocuments` via `cursor` (works past the
4400
+ * 1,000-row `page` ceiling, unlike passing `page` yourself). Each page is
4401
+ * a separate billed call. Stops after a page whose `hasMore` is not `true`,
4402
+ * whose `nextCursor` is absent, `null` or empty, or that is empty. A
4403
+ * `nextCursor` the walk already sent, or one that is not a string, throws
4404
+ * `InvalidResponseError`; the pages already yielded stay valid, and the
4405
+ * page that showed the stall is not yielded and is on the error's `body`.
4406
+ * Any `params.page` is ignored and never sent — pass
4407
+ * `params.cursor` only to resume a walk you saved partway through;
4408
+ * `page` together with `cursor` is a 400 ("Use either cursor or page,
4409
+ * not both"), so this strips `page` at runtime, not just in the type
4410
+ * (`Omit` alone only guards TypeScript callers — a JS caller, or one
4411
+ * using `as`, could otherwise still pass it through). A `limit` that is
4412
+ * not a positive integer is a `RangeError` before any request.
4413
+ */
4414
+ paginateNationalDocuments(jurisdiction: string, params?: Omit<NationalDocumentListParams, "page">, options?: CallOptions): AsyncGenerator<NationalDocumentListResponse, void>;
4415
+ /**
4416
+ * `POST /{jurisdiction}/search/semantic` — embedding-based semantic
4417
+ * search over a jurisdiction's case law. Same request/response shape as
4418
+ * `semanticSearch`, plus `jurisdiction`/`documentId`/`attribution` and
4419
+ * `document` (the matched decision as the listing returns it — the same
4420
+ * fields in every jurisdiction, API 2.8.0) on every hit.
4421
+ *
4422
+ * **Cost: a flat 5 credits** — `hyde` is accepted but never changes the
4423
+ * price or the billing tier here: the national index never rewrites, so
4424
+ * the response reports `hyde: false` (never `true`) when requested.
4425
+ */
4426
+ nationalSemanticSearch(jurisdiction: string, request: NationalSemanticCaseLawOptions, options?: CallOptions): Promise<NationalSemanticCaseLawResponse>;
4427
+ /**
4428
+ * `POST /{jurisdiction}/legislation/semantic` — embedding-based semantic
4429
+ * search over a jurisdiction's legislation; article-level matches. Same
4430
+ * shape as `semanticLegislationSearch`, plus `jurisdiction`/`documentId`/
4431
+ * `attribution` and `document` (the matched act's listing summary) on
4432
+ * every hit; the index fields (`law_title`, `article_ref`, `section`,
4433
+ * `language`, `in_force`, `valid_from`, `valid_to`, `law_type`) are
4434
+ * always present, `null` when the index has nothing (API 2.8.0).
4435
+ *
4436
+ * **`asOf` (API 2.29.0)** labels each hit for a date (`asOfResolved`,
4437
+ * `asOfReason`, `asOfVersion`); the response adds `asOf` and
4438
+ * `asOfSummary`. The search runs over today's texts only. A hit is
4439
+ * resolved only when the publisher's dates, as of LexAPI's last recorded
4440
+ * read of the act (`asOfVersion.checkedAt`), show today's wording already
4441
+ * applied on the date; an unresolved hit keeps today's wording — it is not
4442
+ * established as the text for the date. LexAPI holds such dates for
4443
+ * Austria and Spain.
4444
+ *
4445
+ * `NationalSemanticLegislationOptions` has no `hyde` field, and this SDK
4446
+ * never forwards one on this call even if a caller bypasses the type
4447
+ * system — the server now validates `hyde` as a boolean on this route too
4448
+ * (400 otherwise), so a stray non-boolean value would 400 for nothing.
4449
+ *
4450
+ * **Cost: 5 credits.**
4451
+ */
4452
+ nationalLegislationSemanticSearch(jurisdiction: string, request: NationalSemanticLegislationOptions, options?: CallOptions): Promise<NationalSemanticLegislationResponse>;
2433
4453
  /**
2434
4454
  * `POST /search/semantic` — embedding-based semantic search over CJEU
2435
4455
  * case law. Use this (not `search`) for *concept* queries; EUR-Lex
@@ -2466,6 +4486,11 @@ declare class LexAPI {
2466
4486
  * cannot be answered keeps its latest text with `asOfResolved: false` and
2467
4487
  * an `asOfReason`. The response adds `asOf` and `asOfSummary`.
2468
4488
  *
4489
+ * **In force today:** EU hits carry `inForce` (with `notInForceReason`,
4490
+ * `endOfValidity`, `entryIntoForce`) when the act's status is known;
4491
+ * `inForce: true` keeps only hits known to be in force today and reports
4492
+ * what it removed in `inForceFilter`.
4493
+ *
2469
4494
  * **Cost:** 5 credits for the search; with `asOf`, each live fetch of a
2470
4495
  * version the corpus does not hold reserves 5 and settles by outcome
2471
4496
  * (Cellar 4, browser 5, no text 1, failed 0) — at most 3 per request by
@@ -2473,6 +4498,37 @@ declare class LexAPI {
2473
4498
  * (`insufficient_credits`), never a 402. The `hyde` option is case-law only.
2474
4499
  */
2475
4500
  semanticLegislationSearch(request: SemanticLegislationSearchOptions, options?: CallOptions): Promise<SemanticLegislationSearchResponse>;
4501
+ /**
4502
+ * `POST /legislation/as-of` — the version of an EU regulation, directive
4503
+ * or decision listed for a date: the newest consolidated version dated on
4504
+ * or before it, or the act as published in the Official Journal when none
4505
+ * is. With `provision`, also that article, annex or recital range of the
4506
+ * version. Requires LexAPI API 2.26.0.
4507
+ *
4508
+ * **Unresolved is a normal return, not an error:** when the version or
4509
+ * the text cannot be established the call resolves with
4510
+ * `asOfResolved: false`, an `asOfReason` and no `provision`. Use
4511
+ * `provision.text` only when `asOfResolved` is `true`; `asOfVersion` can
4512
+ * also be present on an unresolved `provision` answer.
4513
+ * An unknown act throws `NotFoundError`; invalid input throws
4514
+ * `InvalidCelexError` / `InvalidParamsError`. An API older than 2.26.0
4515
+ * has no such endpoint and also answers 404 (`NotFoundError`).
4516
+ * `err.unknownEndpoint` is `false` there (the API sends it from 2.27.0):
4517
+ * check `err.message.includes("Unknown API endpoint")`.
4518
+ *
4519
+ * Consolidated versions have no legal force; only the act as published in
4520
+ * the Official Journal (`baseCelex`) is authentic. The answer does not say
4521
+ * whether an individual provision applied on that date, and
4522
+ * `act.inForceToday` is about today, not `asOf`. A retroactive amendment
4523
+ * counts from the date of the amending act.
4524
+ *
4525
+ * **Cost:** 1 credit when no text is fetched; when the provision's text
4526
+ * has to be fetched, 4 (5 when it is fetched live from EUR-Lex) whatever
4527
+ * the answer, and 1 if the fetch fails or finds no text. A fetch reserves
4528
+ * up to 5 credits: a pool holding fewer gets
4529
+ * `asOfReason: "insufficient_credits"`.
4530
+ */
4531
+ legislationAsOf(request: LegislationAsOfRequest, options?: CallOptions): Promise<LegislationAsOfResponse>;
2476
4532
  /**
2477
4533
  * `GET /export` — stream matching corpus rows as NDJSON (BUSINESS, SCALE
2478
4534
  * and ENTERPRISE; lower tiers get 403 `TierForbiddenError`). Metadata-only
@@ -2505,7 +4561,8 @@ declare class LexAPI {
2505
4561
  /**
2506
4562
  * Normalized credit visibility for one response (SDK contract §1.5).
2507
4563
  * All fields tolerate the `usage`/`credits` blocks being absent
2508
- * (legacy daily-call accounts omit `credits`).
4564
+ * (legacy daily-call accounts omit `credits`); a figure that is not a finite
4565
+ * number, or a `resetsAt` that is not a string, counts as absent.
2509
4566
  */
2510
4567
  interface CreditUsage {
2511
4568
  /**
@@ -2552,7 +4609,9 @@ type WebhookBody = string | Uint8Array | ArrayBuffer;
2552
4609
  interface VerifyWebhookOptions {
2553
4610
  /**
2554
4611
  * Reject deliveries whose signed `timestamp` is further than this from
2555
- * now (replay guard). Default 300 000 ms (5 minutes). `0` disables the check.
4612
+ * now (replay guard; the edge passes, compared in whole microseconds).
4613
+ * Default 300 000 ms (5 minutes). `0` disables the check, a negative value
4614
+ * rejects every delivery, and `NaN` is a `RangeError`.
2556
4615
  */
2557
4616
  toleranceMs?: number;
2558
4617
  /** Clock override (testing). Default `Date.now()`. */
@@ -2568,21 +4627,36 @@ declare class WebhookSignatureError extends Error {
2568
4627
  static [Symbol.hasInstance](value: unknown): boolean;
2569
4628
  constructor(reason: WebhookSignatureError["reason"], message: string);
2570
4629
  }
2571
- /** Compute the expected `X-Webhook-Signature` (hex HMAC-SHA256) for a raw body. */
4630
+ /**
4631
+ * Compute the expected `X-Webhook-Signature` (hex HMAC-SHA256) for a raw
4632
+ * body. A string body is signed as its UTF-8 encoding; a string with a lone
4633
+ * surrogate has none and throws `WebhookSignatureError("malformed_body")`.
4634
+ */
2572
4635
  declare function computeSignature(rawBody: WebhookBody, secret: string): Promise<string>;
2573
4636
  /**
2574
4637
  * `true` when `signature` (the `X-Webhook-Signature` header) is the
2575
4638
  * HMAC-SHA256 of `rawBody` under `secret`. Constant-time comparison.
2576
4639
  * Signature only — use {@link verifyWebhook} to also check freshness.
2577
4640
  * Throws `WebhookSignatureError("missing_secret")` for an empty secret
2578
- * (a configuration error, not a bad delivery).
4641
+ * (a configuration error, not a bad delivery). A string body with a lone
4642
+ * surrogate is `false`.
2579
4643
  */
2580
4644
  declare function verifySignature(rawBody: WebhookBody, signature: string | null | undefined, secret: string): Promise<boolean>;
2581
4645
  /**
2582
4646
  * Verify a delivery and parse it into a typed {@link WebhookPayload}
2583
- * (switch on `event`). Throws {@link WebhookSignatureError} on a missing
2584
- * or invalid signature, a non-JSON body, or a `timestamp` outside
2585
- * `toleranceMs` (default 5 minutes).
4647
+ * (switch on `event`). Throws {@link WebhookSignatureError}; its `reason`
4648
+ * is the first check that fails, in this order: an empty secret
4649
+ * (`missing_secret`), an absent or empty header (`missing_signature`), the
4650
+ * signature (`invalid_signature`), a body that is not one UTF-8 JSON object
4651
+ * (`malformed_body`), a `timestamp` that is not
4652
+ * `YYYY-MM-DDTHH:MM:SS[.fraction]` with `Z` or a `±HH:MM` offset, or is
4653
+ * further than `toleranceMs` (default 5 minutes) from now (`stale_timestamp`).
4654
+ *
4655
+ * The body is decoded as strict UTF-8 (one leading byte order mark is
4656
+ * ignored) and parsed from the same bytes the signature covers, as one
4657
+ * strict JSON text (no `NaN` or `Infinity`). A string body stands for its
4658
+ * UTF-8 encoding; a string with a lone surrogate has none and fails
4659
+ * verification (`invalid_signature`).
2586
4660
  *
2587
4661
  * ```ts
2588
4662
  * app.post("/lexapi-webhook", express.raw({ type: "application/json" }), async (req, res) => {
@@ -2598,6 +4672,6 @@ declare function verifySignature(rawBody: WebhookBody, signature: string | null
2598
4672
  */
2599
4673
  declare function verifyWebhook(rawBody: WebhookBody, signature: string | null | undefined, secret: string, options?: VerifyWebhookOptions): Promise<WebhookPayload>;
2600
4674
 
2601
- declare const VERSION = "0.2.0";
4675
+ declare const VERSION = "0.5.0";
2602
4676
 
2603
- export { AS_OF_REASONS, type AcceptLanguages, type Annex, type Article, type AsOfReason, type AsOfVersion, AuthenticationError, type Author, type BatchDocumentError, type BatchSourceCounts, type CallOptions, type CitationEdgeDetail, type CitationEdgeParams, type CitationEdgeSummary, type CitationExtractResponse, type CitationNeighbour, type CitationNetworkParams, type CitationNetworkResponse, type CitationPathNode, type CitationPathParams, type CitationPathResponse, type CitationStatsResponse, type CitationStatsTopCited, type CitationStatsTopCiting, type CitationType, type CitedByResponse, type CitedDocumentGroup, type CitesResponse, type CitingDocumentGroup, type ConsolidatedVersionHint, type CreditUsage, type CreditedResponse, type CreditsExhaustedDetails, CreditsExhaustedError, type CreditsInfo, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type DeliveryStatus, type Document, type DocumentByUrlRequest, type DocumentByUrlResponse, type DocumentContent, type DocumentContentBatchRequest, type DocumentContentBatchResponse, type DocumentContentRequest, type DocumentContentResponse, type DocumentMetadata, type DocumentMetadataRequest, type DocumentMetadataResponse, type DocumentType, type DocumentTypeCode, type DocumentUrls, type DocumentVersionResponse, type DocumentVersionsResponse, type Domain, type ErrorCode, type ExportDone, type ExportDoneInfo, type ExportHeaderInfo, type ExportListFilter, type ExportMeta, type ExportMetaInfo, type ExportParams, type ExportRow, type ExportStream, type ExportStreamOptions, type IdentifierType, type IncludeSelection, type IncludeToken, IncompleteExportError, type InfoResponse, type InfoSearchFilters, InternalServerError, InvalidCelexError, InvalidParamsError, InvalidResponseError, InvalidUrlError, type Language, LexAPI, LexAPIError, type LexAPIErrorContext, type LexAPIOptions, NetworkError, NotFoundError, type OneOrMany, type Procedure, type RateLimitInfo, RateLimitedError, type RecentDocumentsParams, type RecentDocumentsResponse, type Recital, type RelatedDocument, type RelatedDocumentsParams, type RelatedDocumentsResponse, type RelationSync, RequestAbortedError, type ResolveResponse, type ResolvedVia, type ResponseHeaders, type RetryOptions, type SearchRequest, type SearchResponse, type SearchResult, type Section, type SemanticCaseLawResult, type SemanticCaseLawSearchOptions, type SemanticCaseLawSearchResponse, type SemanticLanguage, type SemanticLegislationResult, type SemanticLegislationSearchOptions, type SemanticLegislationSearchResponse, type SemanticSearchOptions, type SemanticUsageInfo, ServiceUnavailableError, type Subdomain, type SubscriptionInfo, type SubscriptionTier, type Table, type TextAvailability, type TextScope, type TextUnavailableReason, TierForbiddenError, TimeoutError, type TitleSource, UpstreamError, type UsageInfo, VERSION, type VerifyWebhookOptions, type VersionEntry, type VersionParams, WEBHOOK_DELIVERY_HEADER, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, type WatchlistRelation, type WebhookBody, type WebhookChangeDocument, type WebhookCreateRequest, type WebhookCreateResponse, type WebhookCriteria, type WebhookDeleteResponse, type WebhookDeliveriesParams, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDeliveryEnvelope, type WebhookDetail, type WebhookDocumentsNewPayload, type WebhookListItem, type WebhookListResponse, type WebhookPayload, type WebhookResponse, type WebhookRetryPolicy, WebhookSignatureError, type WebhookStatus, type WebhookTestPayload, type WebhookTestResponse, type WebhookUpdateRequest, type WebhookUpdateResponse, type WebhookWatchlistChange, type WebhookWatchlistChangesPayload, WebhooksAPI, type WithResponseHeaders, computeSignature, getCreditUsage, isLexAPIError, normalizeRetryAfterSeconds, parseResponseHeaders, verifySignature, verifyWebhook };
4677
+ export { AS_OF_LOOKUP_REASONS, AS_OF_REASONS, type AcceptLanguages, type Annex, type Article, type AsOfLookupReason, type AsOfReason, type AsOfVersion, AuthenticationError, type Author, type BatchDocumentError, type BatchSourceCounts, CITATION_PROVENANCES, CITATION_RESOLUTIONS, CITATION_TYPES, type CallOptions, type CitationDocumentKind, type CitationEdgeDetail, type CitationEdgeKind, type CitationEdgeParams, type CitationEdgeSummary, type CitationExtractResponse, type CitationFilterParams, type CitationNeighbour, type CitationNetworkParams, type CitationNetworkResponse, type CitationNode, type CitationPathNode, type CitationPathParams, type CitationPathResponse, type CitationProvenance, type CitationResolution, type CitationStatsParams, type CitationStatsResponse, type CitationStatsTopCited, type CitationStatsTopCiting, type CitationType, type CitedByResponse, type CitedDocumentGroup, type CitesParams, type CitesResponse, type CitingDocumentGroup, type ConsolidatedVersionHint, type Counterpart, type CounterpartVia, type CounterpartsParams, type CounterpartsResponse, type CountsSource, type CreditUsage, type CreditedResponse, type CreditsExhaustedDetails, CreditsExhaustedError, type CreditsInfo, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type DeliveryStatus, type Document, type DocumentAtDateResponse, type DocumentAtDateSnapshot, type DocumentByUrlRequest, type DocumentByUrlResponse, type DocumentContent, type DocumentContentBatchRequest, type DocumentContentBatchResponse, type DocumentContentRequest, type DocumentContentResponse, type DocumentMetadata, type DocumentMetadataRequest, type DocumentMetadataResponse, type DocumentType, type DocumentTypeCode, type DocumentUrls, type DocumentVersionResponse, type DocumentVersionsResponse, type DocumentWithdrawnDetails, DocumentWithdrawnError, type Domain, type ErrorCode, type EuSemanticCaseLawResult, type EuSemanticLegislationResult, type ExportDone, type ExportDoneInfo, type ExportHeaderInfo, type ExportListFilter, type ExportMeta, type ExportMetaInfo, type ExportParams, type ExportRow, type ExportStream, type ExportStreamOptions, type FieldProvenance, type IdentifierType, type InForceLabel, type InForceLookup, type IncludeSelection, type IncludeToken, IncompleteExportError, type InfoResponse, type InfoSearchFilters, InternalServerError, InvalidCelexError, InvalidParamsError, InvalidResponseError, InvalidUrlError, type Language, type LegislationAsOfAct, type LegislationAsOfProvision, type LegislationAsOfRequest, type LegislationAsOfResponse, type LegislationAsOfVersion, LexAPI, LexAPIError, type LexAPIErrorContext, type LexAPIOptions, NATIONAL_AS_OF_REASONS, type NationalAllowanceExhaustedDetails, NationalAllowanceExhaustedError, type NationalArticle, type NationalAsOfReason, type NationalAsOfVersion, type NationalCaseLawCoverageAvailability, type NationalCaseLawFilters, type NationalCitationGraph, type NationalCitationGraphFloors, type NationalCitationGraphMethods, type NationalCitationGraphPrecision, type NationalCitationGraphRateKey, type NationalCitationGraphUnmeasuredReason, type NationalCitedNorm, type NationalCoverageAvailability, type NationalCoverageResponse, type NationalDecision, type NationalDecisionDocument, type NationalDocument, type NationalDocumentContent, type NationalDocumentKind, type NationalDocumentListParams, type NationalDocumentListResponse, type NationalDocumentResponse, type NationalDocumentSummary, type NationalJurisdictionCoverage, type NationalLegislationFilters, type NationalOcrInfo, type NationalRepeal, type NationalSearchPartialReason, type NationalSemanticCaseLawOptions, type NationalSemanticCaseLawResponse, type NationalSemanticCaseLawResult, NationalSemanticFilterUnreachableError, type NationalSemanticLegislationOptions, type NationalSemanticLegislationResponse, type NationalSemanticLegislationResult, NationalSemanticNotEnabledError, type NationalSemanticSearchAvailability, NationalSemanticUnavailableError, type NationalSource, type NationalTextBasis, type NationalTextBasisKind, type NationalTextSource, NetworkError, NotFoundError, type NotFoundReason, type NotInForceReason, type OneOrMany, PaymentPastDueError, type Procedure, type Provenance, type RateLimitInfo, RateLimitedError, type RecentDocumentsParams, type RecentDocumentsResponse, type Recital, type RelatedDocument, type RelatedDocumentsParams, type RelatedDocumentsResponse, type RelationSync, RequestAbortedError, type ResolveResponse, type ResolvedVia, type ResponseHeaders, type RetryOptions, type SearchRequest, type SearchResponse, type SearchResult, type Section, type SemanticCaseLawResult, type SemanticCaseLawSearchOptions, type SemanticCaseLawSearchResponse, type SemanticHitTextAvailability, type SemanticHitTextUnavailableReason, type SemanticLanguage, type SemanticLegislationResult, type SemanticLegislationSearchOptions, type SemanticLegislationSearchResponse, type SemanticSearchOptions, type SemanticUsageInfo, ServiceUnavailableError, type SnapshotCandidate, type Subdomain, type SubscriptionInfo, type SubscriptionTier, type Table, type TextAvailability, type TextScope, type TextUnavailableReason, TierForbiddenError, TimeoutError, type TitleSource, type TranspositionCountry, type TranspositionMeasure, type TranspositionParams, type TranspositionResponse, type UnresolvedReference, UpstreamError, type UsageInfo, VERSION, type VerifyWebhookOptions, type VersionEntry, type VersionParams, WEBHOOK_DELIVERY_HEADER, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, type WatchlistRelation, type WebhookBody, type WebhookChangeDocument, type WebhookCreateRequest, type WebhookCreateResponse, type WebhookCriteria, type WebhookDeleteResponse, type WebhookDeliveriesParams, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDeliveryEnvelope, type WebhookDetail, type WebhookDocumentsNewPayload, type WebhookListItem, type WebhookListResponse, type WebhookPayload, type WebhookResponse, type WebhookRetryPolicy, WebhookSignatureError, type WebhookStatus, type WebhookTestPayload, type WebhookTestResponse, type WebhookUpdateRequest, type WebhookUpdateResponse, type WebhookWatchlistChange, type WebhookWatchlistChangesPayload, WebhooksAPI, type WithResponseHeaders, computeSignature, getCreditUsage, isLexAPIError, isNationalAsOfVersion, isNationalDecision, normalizeRetryAfterSeconds, parseResponseHeaders, verifySignature, verifyWebhook };