@lexapi/client 0.1.0 → 0.4.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.cts CHANGED
@@ -1,3 +1,117 @@
1
+ /**
2
+ * LexAPI response headers, parsed into one typed object.
3
+ *
4
+ * Several facts are only reported in headers — which upstream answered (and
5
+ * therefore what a document read settles at), whether a search came from
6
+ * the result cache, rate-limit headroom — so every JSON response the SDK
7
+ * returns carries them as `result.headers`. Absent headers are `undefined`.
8
+ */
9
+ /** Draft-6 IETF `RateLimit-*` headers (sent on every `/api/v1` response). */
10
+ interface RateLimitInfo {
11
+ /** Requests allowed per window (`RateLimit-Limit`). */
12
+ limit?: number;
13
+ /** Requests left in the current window (`RateLimit-Remaining`). */
14
+ remaining?: number;
15
+ /** Seconds until the window resets (`RateLimit-Reset` — a delta, not a timestamp). */
16
+ reset?: number;
17
+ /** e.g. `"120;w=60"` (`RateLimit-Policy`). */
18
+ policy?: string;
19
+ }
20
+ /**
21
+ * How a `/documentContent/batch` was served. Counts overlap and do not map
22
+ * one-to-one onto prices: `liveFetches` is every item that needed a fetch
23
+ * and was not served by Cellar or an OJ issue (so it includes failed and
24
+ * text-unavailable items), and `textUnavailable` overlaps the other buckets.
25
+ */
26
+ interface BatchSourceCounts {
27
+ /** Items served from the LexAPI corpus (`X-Batch-Corpus-Hits`). */
28
+ corpusHits?: number;
29
+ /** Items answered by the Publications Office Cellar API (`X-Batch-Cellar-Served`). */
30
+ cellarServed?: number;
31
+ /** Items recovered from an Official Journal issue (`X-Batch-OJ-Recovered`). */
32
+ ojRecovered?: number;
33
+ /** Items that needed a fetch not served by Cellar/OJ — includes failed and text-unavailable ones (`X-Batch-Live-Fetches`). */
34
+ liveFetches?: number;
35
+ /** Items returned with metadata but no text (`X-Batch-Text-Unavailable`). */
36
+ textUnavailable?: number;
37
+ }
38
+ interface ResponseHeaders {
39
+ /**
40
+ * Which source answered (`X-Source`): `corpus` (1 credit), `cellar` /
41
+ * `cellar-oj` (4 credits), `live` (browser fetch, 5 credits).
42
+ */
43
+ source?: "corpus" | "cellar" | "cellar-oj" | "live" | (string & {});
44
+ /** `/search` upstream (`X-Search-Source`): `soap`, `cellar`, `corpus`; absent for EUR-Lex result pages. */
45
+ searchSource?: "soap" | "cellar" | "corpus" | (string & {});
46
+ /** `/search` result cache (`X-Search-Cache`): `hit`, `miss`, `bypass`. */
47
+ searchCache?: "hit" | "miss" | "bypass" | (string & {});
48
+ /** Language rendition actually served (`X-Language`). */
49
+ language?: string;
50
+ /** Present only when another language was served instead (`X-Language-Fallback`). */
51
+ languageFallback?: string;
52
+ /** `false` when the document has metadata but no text (`X-Text-Available`). */
53
+ textAvailable?: boolean;
54
+ /** Monotonic corpus version for this CELEX (`X-Corpus-Version`). */
55
+ corpusVersion?: number;
56
+ /** When the current corpus version was fetched (`X-Corpus-FetchedAt`). */
57
+ corpusFetchedAt?: string;
58
+ /** Internal live-fetch cache state, informational (`X-Cache`). */
59
+ cache?: string;
60
+ /** Tier clamping notice (`X-Warning`). */
61
+ warning?: string;
62
+ /** Requested document types with no EUR-Lex form code (`X-Ignored-DocumentTypes`). */
63
+ ignoredDocumentTypes?: string[];
64
+ /** Post-filter dimensions (`X-PostFiltered-By`). */
65
+ postFilteredBy?: string;
66
+ /** Rows kept by the post-filter (`X-PostFiltered-Kept`). */
67
+ postFilteredKept?: string;
68
+ /** Number of EUR-Lex searches a multi-value `documentType` fanned out to (`X-DocumentType-FanOut`). */
69
+ documentTypeFanOut?: number;
70
+ /** `/documents/recent` language post-filter (`X-Language-Filter`, `X-Language-Kept`). */
71
+ languageFilter?: string;
72
+ languageKept?: string;
73
+ /** `/documentContent/batch` source breakdown. */
74
+ batch?: BatchSourceCounts;
75
+ /** Rate-limit headroom for this API key. */
76
+ rateLimit?: RateLimitInfo;
77
+ /** Raw `Retry-After` header (delta-seconds or HTTP-date), sent on per-minute 429s. */
78
+ retryAfter?: string;
79
+ /**
80
+ * API contract version the server implements (`X-LexAPI-Version`, e.g.
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.
83
+ */
84
+ apiVersion?: string;
85
+ /** Deployed build (`X-LexAPI-Release`, e.g. `2.1.0+633eb67`) — quote it in bug reports. */
86
+ release?: string;
87
+ /** Rows kept by the `/documents/recent` lenient language filter (`X-Language-Partial-Kept`). */
88
+ languagePartialKept?: number;
89
+ /** Age in seconds of a cached answer (`X-Cache-Age`). */
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
+ };
105
+ }
106
+ /** Minimal `Headers` surface (works with polyfilled / injected fetch implementations). */
107
+ interface HeaderGetter {
108
+ get(name: string): string | null;
109
+ }
110
+ /** Parse the LexAPI headers off a fetch `Response` (or any `Headers`). */
111
+ declare function parseResponseHeaders(source: {
112
+ headers: HeaderGetter;
113
+ } | HeaderGetter): ResponseHeaders;
114
+
1
115
  /**
2
116
  * Typed errors mirroring the LexAPI error envelope:
3
117
  *
@@ -8,10 +122,21 @@
8
122
  * codes never crash the parser — the raw code string is preserved on the
9
123
  * base `LexAPIError` (forward compatibility).
10
124
  */
125
+
11
126
  /** Stable error codes from the OpenAPI `ErrorResponse.error.code` enum. */
12
- type ErrorCode = "NOT_FOUND" | "INVALID_CELEX" | "INVALID_URL" | "INVALID_PARAMS" | "RATE_LIMITED" | "TIER_FORBIDDEN" | "CREDITS_EXHAUSTED" | "UPSTREAM_ERROR" | "TIMEOUT" | "INTERNAL" | "UNAUTHORIZED" | "NETWORK_ERROR" | (string & {});
127
+ 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" | "NATIONAL_ALLOWANCE_EXHAUSTED" | "NATIONAL_SEMANTIC_NOT_ENABLED" | "NATIONAL_SEMANTIC_UNAVAILABLE" | "NATIONAL_SEMANTIC_FILTER_UNREACHABLE" | "DOCUMENT_WITHDRAWN" | (string & {});
128
+ /** Extra context attached to errors built from an HTTP response. */
129
+ interface LexAPIErrorContext {
130
+ /** The parsed JSON error body, verbatim (e.g. legacy `upgradeUrl`, `current`/`limit`). */
131
+ body?: unknown;
132
+ /** Parsed response headers (rate limits, source, …). */
133
+ headers?: ResponseHeaders;
134
+ }
13
135
  /** Base class for every error thrown by the SDK. */
14
136
  declare class LexAPIError extends Error {
137
+ /** Stable class tag used by the cross-build `instanceof` brand check. */
138
+ static readonly kind: string;
139
+ static [Symbol.hasInstance](value: unknown): boolean;
15
140
  /** Stable machine-readable code (`error.code`, or derived from the HTTP status for legacy bodies). */
16
141
  readonly code: ErrorCode;
17
142
  /** HTTP status. `0` for client-side failures (network error, client-side timeout). */
@@ -19,86 +144,382 @@ declare class LexAPIError extends Error {
19
144
  /** The `error.details` object from the typed envelope, when present. */
20
145
  readonly details: unknown;
21
146
  /**
22
- * Seconds to wait before retrying, when the server said so (429).
147
+ * Seconds to wait before retrying, when the server said so (429; also the
148
+ * 503 of an incomplete national semantic search).
23
149
  * Sourced from the `Retry-After` response HEADER first; the JSON
24
150
  * `retryAfter` body field is only a fallback because it historically
25
151
  * carried buggy epoch-seconds values (epoch-looking values are
26
152
  * normalized to a delta).
27
153
  */
28
154
  readonly retryAfter: number | undefined;
29
- constructor(code: ErrorCode, message: string, status: number, details?: unknown, retryAfter?: number);
155
+ /**
156
+ * The parsed JSON error body, verbatim. Useful for legacy-shape fields the
157
+ * typed properties don't cover (`upgradeUrl` on tier gates, `current` /
158
+ * `limit` on the webhook ceiling, `usage` on legacy quota 429s).
159
+ */
160
+ readonly body: unknown;
161
+ /** Parsed response headers, when the error came from an HTTP response. */
162
+ readonly headers: ResponseHeaders | undefined;
163
+ constructor(code: ErrorCode, message: string, status: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
30
164
  /**
31
165
  * Build the most specific error subclass for a non-2xx response.
32
166
  * Accepts both the typed envelope and the legacy bare `{error, message}` shape.
33
167
  */
34
- static fromResponse(status: number, body: unknown, headerRetryAfter?: number): LexAPIError;
168
+ static fromResponse(status: number, body: unknown, headerRetryAfter?: number, headers?: ResponseHeaders): LexAPIError;
35
169
  }
36
170
  /** 404 — document or resource missing (`NOT_FOUND`). */
37
171
  declare class NotFoundError extends LexAPIError {
38
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
172
+ static readonly kind: string;
173
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
39
174
  }
40
175
  /** 400 — CELEX failed validation (`INVALID_CELEX`). */
41
176
  declare class InvalidCelexError extends LexAPIError {
42
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
177
+ static readonly kind: string;
178
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
43
179
  }
44
180
  /** 400 — URL had no resolvable CELEX (`INVALID_URL`). */
45
181
  declare class InvalidUrlError extends LexAPIError {
46
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
182
+ static readonly kind: string;
183
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
47
184
  }
48
185
  /** 400 — missing or malformed params (`INVALID_PARAMS`). */
49
186
  declare class InvalidParamsError extends LexAPIError {
50
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
187
+ static readonly kind: string;
188
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext,
189
+ /**
190
+ * @internal Lets a subclass (`NationalSemanticFilterUnreachableError`)
191
+ * keep its own `code` while still being `instanceof InvalidParamsError`.
192
+ * Not part of the public constructor contract.
193
+ */
194
+ code?: ErrorCode);
195
+ /**
196
+ * The parameter that was refused, when the server names it — e.g. an
197
+ * unknown citation-graph filter value (API 2.11.0). Read from `details`
198
+ * (typed envelope) or the top level of the body (legacy shape).
199
+ */
200
+ get param(): string | undefined;
201
+ /** The refused value of {@link param}, when the server echoes it. */
202
+ get value(): unknown;
203
+ /** The allowed values of {@link param}, when the server lists them (may be empty). */
204
+ get allowed(): string[] | undefined;
51
205
  }
52
206
  /** 401 — missing, invalid, or revoked API key. */
53
207
  declare class AuthenticationError extends LexAPIError {
54
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
208
+ static readonly kind: string;
209
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
55
210
  }
56
- /** 429 — quota or rate ceiling hit (`RATE_LIMITED`). Check `retryAfter`. */
211
+ /**
212
+ * 429 — per-minute rate limit (`RATE_LIMITED`), or, on legacy daily plans,
213
+ * the used-up daily / monthly-semantic quota (`QUOTA_EXHAUSTED`; `code`
214
+ * tells them apart). 429s use the legacy `{error, message, retryAfter}` body
215
+ * (with a top-level `code` from lex-api #304 on); the `Retry-After` header is
216
+ * authoritative and is what `retryAfter` reads first.
217
+ */
57
218
  declare class RateLimitedError extends LexAPIError {
58
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
219
+ static readonly kind: string;
220
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext, code?: "RATE_LIMITED" | "QUOTA_EXHAUSTED");
221
+ /** `RateLimit-*` headers from the 429 response (limit / remaining / reset seconds). */
222
+ get rateLimit(): RateLimitInfo | undefined;
223
+ /**
224
+ * `true` for a legacy-plan quota 429 (daily call quota, or the monthly
225
+ * semantic quota) rather than the per-minute limiter (SDK contract §1.2):
226
+ * `code` is `QUOTA_EXHAUSTED`, or — servers before lex-api #304, which
227
+ * send no code — the body carries `usage.resetsAt` with neither a
228
+ * `Retry-After` header nor a `retryAfter` body field. It cannot succeed
229
+ * before `resetsAt`, so the SDK does not retry it and `retryAfter` is
230
+ * `undefined`.
231
+ */
232
+ get quotaExhausted(): boolean;
233
+ /** When a legacy quota resets: the body's `resetsAt`, else `usage.resetsAt`. */
234
+ get resetsAt(): string | undefined;
59
235
  }
60
236
  /** 403 — tier-gated endpoint (`TIER_FORBIDDEN`). Retrying cannot help; upgrade the plan. */
61
237
  declare class TierForbiddenError extends LexAPIError {
62
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
238
+ static readonly kind: string;
239
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
240
+ }
241
+ /** `error.details` on a 402 `CREDITS_EXHAUSTED` envelope. */
242
+ interface CreditsExhaustedDetails {
243
+ /** The operation that was refused, e.g. `"semantic_case_law"`. */
244
+ operation?: string;
245
+ /** Its upfront credit weight (variable-priced operations are admitted against their upfront weight). */
246
+ weight?: number;
247
+ /** Credits left in the pool (monthly + top-up − used). `weight − available` is the shortfall. */
248
+ available?: number;
249
+ /** Monthly allowance. */
250
+ included?: number;
251
+ /** Top-up credits. */
252
+ topup?: number;
253
+ /** Credits used this window. */
254
+ used?: number;
255
+ /** When the monthly pool refills. */
256
+ resetsAt?: string | null;
257
+ [key: string]: unknown;
63
258
  }
64
- /** 402 — monthly credit pool exhausted (`CREDITS_EXHAUSTED`). Not retried. */
259
+ /**
260
+ * 402 — monthly credit pool (incl. top-ups) cannot cover the operation
261
+ * (`CREDITS_EXHAUSTED`). Not retried: wait for `resetsAt`, buy a top-up, or
262
+ * upgrade. A cheaper operation may still succeed — compare `weight` to `available`.
263
+ */
65
264
  declare class CreditsExhaustedError extends LexAPIError {
265
+ static readonly kind: string;
66
266
  /** When the monthly credit allowance resets (ISO date-time), when the server said so. */
67
267
  readonly resetsAt: string | undefined;
68
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, resetsAt?: string);
268
+ /** Typed view of `error.details` (operation, weight, available, included, topup, used, resetsAt). */
269
+ readonly details: CreditsExhaustedDetails | undefined;
270
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, resetsAt?: string, context?: LexAPIErrorContext);
271
+ /** The refused operation's credit weight (`details.weight`). */
272
+ get weight(): number | undefined;
273
+ /** Credits left in the pool (`details.available`). */
274
+ get available(): number | undefined;
275
+ /** The refused operation (`details.operation`). */
276
+ get operation(): string | undefined;
277
+ }
278
+ /** `error.details` on a 402 `NATIONAL_ALLOWANCE_EXHAUSTED` envelope. */
279
+ interface NationalAllowanceExhaustedDetails {
280
+ /** ISO 3166-1 alpha-2 jurisdiction code of the call that was refused. */
281
+ jurisdiction?: string;
282
+ /** The tier's monthly allowance of national calls. */
283
+ limit?: number;
284
+ /** Always `0` on this error. */
285
+ remaining?: number;
286
+ /** When the allowance resets (ISO date-time: start of the next UTC month). */
287
+ resetsAt?: string;
288
+ /** `/pricing` — upgrading to BUSINESS removes the allowance entirely. */
289
+ upgradeUrl?: string;
290
+ [key: string]: unknown;
291
+ }
292
+ /**
293
+ * 402 — the monthly national-law call allowance of a plan below BUSINESS
294
+ * (FREE/STARTER/PROFESSIONAL) is used up (`NATIONAL_ALLOWANCE_EXHAUSTED`).
295
+ * A usage shortfall, not a credit shortfall: no credits
296
+ * were charged for the refused call. Resolves at `resetsAt` (start of next
297
+ * UTC month) or immediately on upgrading to BUSINESS/SCALE/ENTERPRISE, which
298
+ * have no separate limit. Mirrors `X-National-Limit`/`X-National-Remaining`/
299
+ * `X-National-Reset` on the response that triggered it.
300
+ */
301
+ declare class NationalAllowanceExhaustedError extends LexAPIError {
302
+ static readonly kind: string;
303
+ /** Typed view of `error.details` (jurisdiction, limit, remaining, resetsAt, upgradeUrl). */
304
+ readonly details: NationalAllowanceExhaustedDetails | undefined;
305
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
306
+ /** The jurisdiction code of the refused call (`details.jurisdiction`). */
307
+ get jurisdiction(): string | undefined;
308
+ /** The tier's monthly allowance of national calls (`details.limit`). */
309
+ get limit(): number | undefined;
310
+ /** Always `0` (`details.remaining`). */
311
+ get remaining(): number | undefined;
312
+ /** When the allowance resets (`details.resetsAt`, ISO date-time). */
313
+ get resetsAt(): string | undefined;
314
+ /** `/pricing` (`details.upgradeUrl`). */
315
+ get upgradeUrl(): string | undefined;
69
316
  }
70
317
  /** 502 — EUR-Lex returned an error (`UPSTREAM_ERROR`). Retry-safe on GETs. */
71
318
  declare class UpstreamError extends LexAPIError {
72
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
319
+ static readonly kind: string;
320
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
73
321
  }
74
322
  /**
75
- * `TIMEOUT` — either a server-reported 504 (upstream EUR-Lex fetch timed out,
76
- * spec-marked retry-safe) or a client-side timeout (`status === 0`) when the
77
- * configured `timeoutMs` elapsed before a response arrived.
323
+ * A timeout. Two cases, told apart by `code` / `status`:
324
+ * - `TIMEOUT` (504, 524): the server or Cloudflare gave up on the upstream;
325
+ * also a 503 from `getCounterparts` when the lookup exceeded its
326
+ * server-side budget (`partial === true`, refunded).
327
+ * - `REQUEST_TIMEOUT` (`status === 0`): the SDK's own response timeout —
328
+ * no bytes for `timeoutMs` (SDK contract §1.6).
78
329
  */
79
330
  declare class TimeoutError extends LexAPIError {
80
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
331
+ static readonly kind: string;
332
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
333
+ /** `true` when the server answered a budget timeout with `partial: true` (nothing else was returned). */
334
+ get partial(): boolean | undefined;
335
+ /** The server-side budget that expired, in ms, when the body reports it. */
336
+ get serverTimeoutMs(): number | undefined;
337
+ }
338
+ /**
339
+ * 503 — service temporarily unavailable (e.g. a deploy's drain window).
340
+ * Derived from the status (no typed code). Retried like 502/504.
341
+ */
342
+ declare class ServiceUnavailableError extends LexAPIError {
343
+ static readonly kind: string;
344
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext, code?: ErrorCode);
345
+ }
346
+ /**
347
+ * 409 — this jurisdiction's semantic index isn't enabled at all
348
+ * (`NATIONAL_SEMANTIC_NOT_ENABLED`). Legacy-shape body (`{code, error,
349
+ * message, jurisdiction}`, no `error.details`) — `jurisdiction` is read off
350
+ * the raw `body`, not `details`. Not retryable; the call was refunded in
351
+ * full and never reached the national allowance counter.
352
+ */
353
+ declare class NationalSemanticNotEnabledError extends LexAPIError {
354
+ static readonly kind: string;
355
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
356
+ /** ISO 3166-1 alpha-2 jurisdiction code (top-level `jurisdiction` on the raw body). */
357
+ get jurisdiction(): string | undefined;
358
+ }
359
+ /**
360
+ * 503 — a jurisdiction's semantic index exists but is temporarily
361
+ * unreachable (`NATIONAL_SEMANTIC_UNAVAILABLE`). Extends
362
+ * `ServiceUnavailableError` so `instanceof ServiceUnavailableError` still
363
+ * holds (and any existing 503-retry handling still catches it), while
364
+ * `code`/`name` stay specific. Legacy-shape body, same as
365
+ * `NationalSemanticNotEnabledError` — `jurisdiction` comes off `body`.
366
+ */
367
+ declare class NationalSemanticUnavailableError extends ServiceUnavailableError {
368
+ static readonly kind: string;
369
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
370
+ get jurisdiction(): string | undefined;
371
+ /**
372
+ * `"SEARCH_INCOMPLETE"` when the index could not complete this search for a
373
+ * temporary reason and there was nothing left to return (an empty answer
374
+ * would not have meant "no matches"). `retryAfter` is then the wait the
375
+ * server asked for — absent once the same search has repeatedly come back
376
+ * incomplete (try again later, or rephrase or narrow it). `undefined` on
377
+ * the plain "index unavailable" 503.
378
+ */
379
+ get partialReason(): string | undefined;
380
+ }
381
+ /**
382
+ * 422 — the national semantic index cannot search this slice (jurisdiction,
383
+ * document kind and filters) completely and there is nothing left to return
384
+ * (`NATIONAL_SEMANTIC_FILTER_UNREACHABLE`, `partialReason:
385
+ * "SEARCH_INCOMPLETE"`). Not a "no matches" answer, and not temporary:
386
+ * retrying the same request gives the same answer, so it is never retried —
387
+ * rephrase the query or change the filters. Refunded in full. Extends
388
+ * `InvalidParamsError` (the request has to change) while `code`/`name` stay
389
+ * specific — but the request may be perfectly valid: this is a coverage
390
+ * limit of the index, not a malformed request, and `param` is absent.
391
+ * Legacy-shape body — `jurisdiction` comes off `body`.
392
+ */
393
+ declare class NationalSemanticFilterUnreachableError extends InvalidParamsError {
394
+ static readonly kind: string;
395
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
396
+ get jurisdiction(): string | undefined;
397
+ /** `"SEARCH_INCOMPLETE"`. */
398
+ get partialReason(): string | undefined;
399
+ }
400
+ /** `error.details` (typed envelope) or the raw body (legacy envelope) on a `DOCUMENT_WITHDRAWN` 410. */
401
+ interface DocumentWithdrawnDetails {
402
+ id?: string;
403
+ jurisdiction?: string;
404
+ /** ISO date-time the source withdrew the document; `null` when unknown. */
405
+ withdrawnAt?: string | null;
406
+ [key: string]: unknown;
407
+ }
408
+ /**
409
+ * 410 — a national document its source withdrew (a takedown, a
410
+ * pseudonymisation fix, a robots.txt listing). LexAPI
411
+ * serves nothing of it: no title, no metadata, no text. Two envelope shapes
412
+ * carry this code: the TYPED envelope on a direct document read
413
+ * (`GET /{jurisdiction}/documents/{id}`, `error.details: {id, jurisdiction,
414
+ * withdrawnAt}`), and the LEGACY shape with those same three fields as
415
+ * top-level siblings of `code`/`error` on the citation routes (a withdrawn
416
+ * id queried directly, or via `includeNational`). The getters below check
417
+ * `details` first, then fall back to the raw `body` — correct for either
418
+ * shape without the caller needing to know which one answered.
419
+ *
420
+ * Not retryable (the document is gone, not temporarily failing); never
421
+ * charges anything (the credits/allowance refund rule already returns
422
+ * every non-404 4xx-or-5xx). If you hold a cached copy of this document,
423
+ * drop it — the source withdrew it for a reason that may include a legal
424
+ * takedown or a pseudonymisation fix (see docs §7, no re-identification).
425
+ */
426
+ declare class DocumentWithdrawnError extends LexAPIError {
427
+ static readonly kind: string;
428
+ readonly details: DocumentWithdrawnDetails | undefined;
429
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
430
+ private field;
431
+ /** The withdrawn document's id (e.g. `AT-NOR-10001597`). */
432
+ get id(): string | undefined;
433
+ /** Upper-case jurisdiction code. */
434
+ get jurisdiction(): string | undefined;
435
+ /** ISO date-time the source withdrew the document; `undefined` when unknown. */
436
+ get withdrawnAt(): string | undefined;
81
437
  }
82
438
  /** 500 — unexpected server failure (`INTERNAL`). Not retried by default. */
83
439
  declare class InternalServerError extends LexAPIError {
84
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
440
+ static readonly kind: string;
441
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
85
442
  }
86
443
  /** Transport-level failure: DNS, connection reset, etc. No HTTP response was received. */
87
444
  declare class NetworkError extends LexAPIError {
445
+ static readonly kind: string;
446
+ readonly cause: unknown;
447
+ constructor(message: string, cause?: unknown);
448
+ }
449
+ /** The caller's `AbortSignal` fired (status 0). Never retried. `cause` is the signal's reason. */
450
+ declare class RequestAbortedError extends LexAPIError {
451
+ static readonly kind: string;
88
452
  readonly cause: unknown;
89
453
  constructor(message: string, cause?: unknown);
90
454
  }
455
+ /**
456
+ * A 2xx response whose body was not the JSON LexAPI sends (e.g. an HTML page
457
+ * from a proxy). `body` holds the first 500 characters of the raw text.
458
+ */
459
+ declare class InvalidResponseError extends LexAPIError {
460
+ static readonly kind: string;
461
+ constructor(message: string, status: number, rawText?: string, context?: LexAPIErrorContext);
462
+ }
463
+ /**
464
+ * An export stream ended (cleanly, at EOF) without its trailing `_done` line —
465
+ * the server stopped mid-export (SDK contract §1.8). Raised after the rows
466
+ * that did arrive were yielded; they are NOT a complete export.
467
+ */
468
+ declare class IncompleteExportError extends LexAPIError {
469
+ static readonly kind: string;
470
+ /** Rows yielded before the stream ended. */
471
+ readonly rowsRead: number;
472
+ /**
473
+ * @param details the server's `_error` line body (`{ code, message }`) when
474
+ * one arrived; `undefined` for a missing or `complete: false` trailer.
475
+ */
476
+ constructor(message: string, rowsRead: number, details?: unknown);
477
+ }
478
+ /**
479
+ * `true` for any error thrown by this SDK — from either build (ESM or
480
+ * CommonJS) or another installed copy. Pass a class to narrow:
481
+ * `isLexAPIError(err, NotFoundError)`.
482
+ */
483
+ declare function isLexAPIError<T extends LexAPIError = LexAPIError>(value: unknown, errorClass?: abstract new (...args: never[]) => T): value is T;
484
+ /**
485
+ * Normalize a JSON `retryAfter` body value. The field historically carried
486
+ * buggy absolute epoch values instead of delta-seconds (pending server fix);
487
+ * epoch-looking values are converted to a non-negative delta in seconds.
488
+ */
489
+ declare function normalizeRetryAfterSeconds(value: number): number;
91
490
 
92
491
  declare const DEFAULT_BASE_URL = "https://lex-api.com/api/v1";
93
- declare const DEFAULT_TIMEOUT_MS = 60000;
492
+ /**
493
+ * 95 s per attempt: above the 90 s hard timeout the API puts on a single live
494
+ * EUR-Lex fetch (so such a fetch ends in the server's typed, refunded 504
495
+ * rather than a client abort that may still be billed), and below
496
+ * Cloudflare's 100 s proxy timeout. A request that runs several upstream
497
+ * fetches (Cellar, then the browser; a batch) can still exceed it.
498
+ */
499
+ declare const DEFAULT_TIMEOUT_MS = 95000;
94
500
  /** Retry policy knobs (SDK contract §1.2). */
95
501
  interface RetryOptions {
96
502
  /** Max retries after the initial attempt. Default 3. Set 0 to disable retries. */
97
503
  maxRetries?: number;
98
504
  /** Exponential backoff base. Default 500 ms. */
99
505
  baseDelayMs?: number;
100
- /** Cap on any single wait (computed or server-directed). Default 30 000 ms. */
506
+ /**
507
+ * Cap on any single wait (computed or server-directed). Default 30 000 ms.
508
+ * A cap below the server's requested wait (`Retry-After` / `retryAfter`)
509
+ * shortens that wait, so the retry may come too early.
510
+ */
101
511
  maxDelayMs?: number;
512
+ /**
513
+ * SDK contract §1.2 opt-in (default `false`): also retry the eight
514
+ * read-only POSTs (`search`, `getDocument`, `getDocumentsBatch`,
515
+ * `getDocumentByUrl`, `getDocumentMetadata`, `resolve`, `semanticSearch`,
516
+ * `semanticLegislationSearch`) on an **app-origin** 502/503/504 — those
517
+ * are refunded in full, so the retry is billing-safe. App-origin = a
518
+ * non-empty `X-LexAPI-Version` or a `RateLimit-Limit` header; anything
519
+ * else is treated as a proxy answer and never retried on a billed call. Never applies to mutating calls (webhook
520
+ * writes, `extractCitations`).
521
+ */
522
+ retryReadOnlyPosts?: boolean;
102
523
  }
103
524
  interface HttpClientOptions {
104
525
  apiKey: string;
@@ -108,57 +529,101 @@ interface HttpClientOptions {
108
529
  retry: Required<RetryOptions>;
109
530
  userAgentSuffix?: string | undefined;
110
531
  }
111
- type QueryParams = Record<string, string | number | boolean | undefined>;
532
+ /** Query values; arrays are sent as repeated parameters (`?a=x&a=y`). */
533
+ type QueryParams = Record<string, string | number | boolean | undefined | ReadonlyArray<string | number | boolean>>;
112
534
  interface RequestOptions {
113
535
  method: "GET" | "POST" | "PUT" | "DELETE";
114
536
  path: string;
115
537
  query?: QueryParams;
116
538
  body?: unknown;
117
- /** Per-call timeout override. */
539
+ /** Per-call timeout override (per attempt, covering the response body). */
118
540
  timeoutMs?: number | undefined;
541
+ /** Caller cancellation: aborts the in-flight attempt and any retry wait. */
542
+ signal?: AbortSignal | undefined;
543
+ /** `Accept` header override (default `application/json`). */
544
+ accept?: string;
545
+ /**
546
+ * One of the eight read-only POSTs of SDK contract §1.2 — retried on
547
+ * app-origin 502/503/504 when `retryReadOnlyPosts` is on.
548
+ */
549
+ idempotent?: boolean;
550
+ /**
551
+ * A free operation (0 credits: `/info`, webhook reads). A retry cannot
552
+ * charge, so proxy-origin 5xx/520/524 and post-send transport errors are
553
+ * retried too (SDK contract §1.2).
554
+ */
555
+ free?: boolean;
119
556
  }
557
+ declare const INSPECT: unique symbol;
120
558
  /**
121
559
  * Single request core used by every SDK method.
122
560
  *
123
- * - `x-api-key` auth + `User-Agent: lexapi-typescript/<version>` on every request
124
- * (UA omitted on browser runtimes, where it cannot be set).
125
- * - Timeout per attempt via `AbortController`.
126
- * - Retries: up to `maxRetries` (default 3) on 429/502/503/504 and on
127
- * transport-level network errors, with exponential backoff + full jitter.
128
- * Server-directed waits win over computed backoff, resolved in order:
129
- * `Retry-After` header → `RateLimit-Reset` header → JSON `retryAfter` body
130
- * field (epoch-guarded — the field was buggy epoch-seconds until a pending
131
- * server fix, which is why the HEADER is authoritative) → backoff.
132
- * - Non-idempotent methods (anything but GET) are retried ONLY on 429 —
133
- * never on 5xx or network errors, where the request may have been applied.
561
+ * - `x-api-key` auth + `User-Agent: lexapi-typescript/<version>` on every
562
+ * request (UA omitted on browser runtimes, where it cannot be set). The key
563
+ * lives in a private field and never appears in `util.inspect`,
564
+ * `console.log` or `JSON.stringify` output.
565
+ * - One inactivity timeout per attempt (SDK contract §1.6): it runs until
566
+ * the response head arrives and restarts on every body chunk, for JSON
567
+ * bodies and export streams alike.
568
+ * - Caller `AbortSignal`: aborts the attempt and any retry wait; throws
569
+ * `RequestAbortedError`, never retried.
570
+ * - Retries follow the billing-safety rule of SDK contract §1.2 — only when
571
+ * a retry cannot charge twice (see `shouldRetryStatus` and PLAN.md §1.2).
572
+ * - Server-directed waits: `Retry-After` on any status; on a 429 only, then
573
+ * `RateLimit-Reset` and the JSON `retryAfter` field; on a 503
574
+ * `NATIONAL_SEMANTIC_UNAVAILABLE`, the JSON `retryAfter` field.
575
+ * `X-RateLimit-*` is never read.
134
576
  */
135
577
  declare class HttpClient {
578
+ #private;
136
579
  private readonly opts;
137
580
  private readonly userAgent;
138
581
  constructor(opts: HttpClientOptions);
139
- /** Perform a request and parse the JSON body (204 yields `undefined`). */
582
+ /** API base URL. */
583
+ get baseUrl(): string;
584
+ /** Client-level per-attempt timeout (ms). */
585
+ get timeoutMs(): number;
586
+ /** Redacted view for `JSON.stringify` — never includes the API key. */
587
+ toJSON(): Record<string, unknown>;
588
+ /** Redacted view for `util.inspect` / `console.log`. */
589
+ [INSPECT](): string;
590
+ /** Perform a request and parse the JSON body (204 / empty body yields `{}`). */
140
591
  requestJson<T>(options: RequestOptions): Promise<T>;
141
- /** Like `requestJson`, but also exposes the raw `Response` (for header signals). */
592
+ /**
593
+ * Like `requestJson`, but also exposes the raw `Response` (for header
594
+ * signals). The body is read inside the attempt, under its timeout.
595
+ */
142
596
  requestJsonWithResponse<T>(options: RequestOptions): Promise<{
143
597
  data: T;
144
598
  response: Response;
145
599
  }>;
146
600
  /**
147
601
  * Perform a request and return the raw successful `Response` without
148
- * consuming the body (used by streaming endpoints such as `/export`).
149
- * Non-2xx responses are parsed and thrown as typed errors; the retry
150
- * policy applies before the first body byte is consumed.
602
+ * consuming the body (streaming endpoints such as `/export`). The attempt
603
+ * timeout covers only the response headers; the caller applies its own
604
+ * idle timeout to body reads. Non-2xx responses are parsed and thrown as
605
+ * typed errors; the retry policy applies before the first body byte.
151
606
  */
152
607
  requestRaw(options: RequestOptions): Promise<Response>;
153
- private fetchWithTimeout;
608
+ private execute;
154
609
  }
155
610
 
156
611
  /**
157
- * Hand-curated types mirroring `openapi.yaml` (LexAPI 2.0.0).
158
- * Field names and nullability follow the spec exactly — `type: [X, 'null']`
159
- * becomes `X | null`, and properties outside a `required` list are optional.
612
+ * Hand-curated types mirroring LexAPI's `openapi.yaml` (LexAPI 2.0.0) and
613
+ * `docs.md`, cross-checked against the server's controllers.
614
+ *
615
+ * Validated against: lex-api `main` @ 633eb67 (2026-10-26, PR #298).
616
+ *
617
+ * Conventions:
618
+ * - `type: [X, 'null']` becomes `X | null`; properties outside a `required`
619
+ * list are optional.
620
+ * - Open string enums (`"a" | "b" | (string & {})`) are used where the server
621
+ * may add values (forward compatibility) — known values still autocomplete.
622
+ * - Fields the SDK adds from response headers are documented as "SDK-added".
160
623
  */
161
- type SubscriptionTier = "FREE" | "STARTER" | "PROFESSIONAL" | "BUSINESS" | "ENTERPRISE";
624
+
625
+ /** Subscription tiers. `SCALE` was added with the 2026-07 pricing. */
626
+ type SubscriptionTier = "FREE" | "STARTER" | "PROFESSIONAL" | "BUSINESS" | "SCALE" | "ENTERPRISE" | (string & {});
162
627
  /** ISO 639-1 code (24 official EU languages). */
163
628
  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";
164
629
  type Domain = "EU_LAW" | "NATIONAL_LAW" | "ALL";
@@ -168,32 +633,39 @@ type DocumentType = "judgment" | "opinion" | "order" | "regulation" | "directive
168
633
  type Author = "commission" | "council" | "parliament" | "court-of-justice" | "general-court" | "ecb" | "eca" | "eesc" | "cor" | "ema" | "efsa";
169
634
  type Procedure = "ordinary" | "codecision" | "consent" | "consultation" | "budget" | "implementing" | "delegated" | "comitology" | "appointment" | "non-legislative";
170
635
  type TextScope = "title" | "text" | "title-text" | "any";
636
+ /** A single value or a list of values (the API accepts both on list filters). */
637
+ type OneOrMany<T> = T | T[];
171
638
  interface SubscriptionInfo {
172
639
  tier?: SubscriptionTier;
173
640
  maxPages?: number;
174
641
  maxBatchSize?: number;
175
642
  maxWebhooks?: number;
643
+ /** Semantic endpoints only: the effective result cap for this call. */
644
+ maxResults?: number;
176
645
  /** `credits` = monthly credit pool (pricing v2); `daily` = legacy daily-call model. */
177
646
  pricingMode?: "credits" | "daily";
178
647
  /** Legacy daily-call ceiling. `null` for credit-pool (v2) accounts. */
179
648
  dailyLimit?: number | null;
180
649
  /** Monthly credit allowance. `null` for legacy daily-call accounts. */
181
650
  monthlyCredits?: number | null;
182
- /** e.g. "120 requests/minute" */
651
+ /** e.g. `"120 requests/minute"`. `"0 requests/minute"` means unlimited (hand-priced plans). */
183
652
  rateLimit?: string;
184
653
  }
185
654
  /**
186
655
  * Caller's current usage counters at request time. Dual-mode: credits over
187
656
  * the monthly window for v2 accounts, API calls for the day on legacy
188
- * accounts — read `unit` to disambiguate.
657
+ * accounts. Prefer the richer `credits` block on v2 responses.
189
658
  */
190
659
  interface UsageInfo {
191
660
  current?: number;
192
661
  limit?: number;
193
662
  remaining?: number;
663
+ /** Documented by the spec; not currently emitted by the server. */
194
664
  unit?: "credits" | "calls";
195
665
  /** When the counter resets (ISO date-time). */
196
- resetsAt?: string;
666
+ resetsAt?: string | null;
667
+ /** Legacy daily-call plans only: calls this request counted (always 1). */
668
+ unitsCharged?: number;
197
669
  }
198
670
  /**
199
671
  * Pricing-v2 credit-pool state. Present on responses for credit-pool
@@ -201,7 +673,12 @@ interface UsageInfo {
201
673
  * daily-call accounts.
202
674
  */
203
675
  interface CreditsInfo {
204
- /** Credits this specific request cost (0 for free operations such as /info). */
676
+ /**
677
+ * Credits this request cost (0 for free operations such as /info). On
678
+ * operations that settle by source (document reads, searches, HyDE, asOf
679
+ * fetches) refunds are applied after the response is sent, so this can
680
+ * show the upfront charge; the next call's envelope reflects the refund.
681
+ */
205
682
  operation_weight?: number;
206
683
  /** Credits used in the current monthly window. */
207
684
  current?: number;
@@ -221,6 +698,14 @@ interface CreditedResponse {
221
698
  usage?: UsageInfo;
222
699
  credits?: CreditsInfo;
223
700
  }
701
+ /**
702
+ * Parsed response headers attached by the SDK to every JSON response
703
+ * (`result.headers`). See {@link ResponseHeaders}.
704
+ */
705
+ interface WithResponseHeaders {
706
+ /** SDK-added: parsed LexAPI response headers (source, rate limits, warnings, …). */
707
+ headers?: ResponseHeaders;
708
+ }
224
709
  interface InfoSearchFilters {
225
710
  textScope?: TextScope[];
226
711
  domain?: Domain[];
@@ -229,7 +714,7 @@ interface InfoSearchFilters {
229
714
  author?: Author[];
230
715
  procedure?: Procedure[];
231
716
  }
232
- interface InfoResponse extends CreditedResponse {
717
+ interface InfoResponse extends CreditedResponse, WithResponseHeaders {
233
718
  service?: string;
234
719
  version?: string;
235
720
  description?: string;
@@ -241,17 +726,21 @@ interface InfoResponse extends CreditedResponse {
241
726
  /**
242
727
  * `include` / `fields` token. The spec's enum lists
243
728
  * metadata/fullText/articles/recitals/sections/tables/annexes; the
244
- * `DocumentContent` description additionally documents `paragraphs` as
245
- * part of the accepted include set.
729
+ * `DocumentContent` description additionally documents `paragraphs`.
246
730
  */
247
731
  type IncludeToken = "metadata" | "fullText" | "articles" | "recitals" | "paragraphs" | "sections" | "tables" | "annexes";
248
732
  /** Array form, or a comma-separated string like `"metadata,articles"`. */
249
733
  type IncludeSelection = IncludeToken[] | string;
734
+ /**
735
+ * Opt-in language fallback for documents with no text in the requested
736
+ * language: an ordered list of ISO codes the caller can consume, or `"any"`.
737
+ */
738
+ type AcceptLanguages = Language[] | "any";
250
739
  /** A top-level article extracted from the document body. */
251
740
  interface Article {
252
- /** Stable id from the EUR-Lex `eli-subdivision` (e.g. `art_17`). */
741
+ /** Stable id (e.g. `art_17`, `art_6a` for an inserted article). */
253
742
  id?: string;
254
- /** e.g. `"Article 17"` */
743
+ /** e.g. `"Article 17"` — the heading as published. */
255
744
  number: string;
256
745
  title?: string | null;
257
746
  /** Plain-text body of the article (paragraphs joined). */
@@ -264,13 +753,16 @@ interface Article {
264
753
  */
265
754
  interface Section {
266
755
  type: "chapter" | "section";
267
- number: string;
268
- title: string;
756
+ /** `null` for an unnumbered section heading. */
757
+ number: string | null;
758
+ /** `null` when the heading has no title text. */
759
+ title: string | null;
269
760
  articleRange?: [string, string] | null;
270
761
  }
271
762
  /** Preamble recital — also the element type of `paragraphs[]` (numbered prose). */
272
763
  interface Recital {
273
- number: number;
764
+ /** `null` when the recital's number could not be read from the markup. */
765
+ number: number | null;
274
766
  text: string;
275
767
  }
276
768
  interface Annex {
@@ -285,21 +777,60 @@ interface Table {
285
777
  /**
286
778
  * Structured document body. Case-law CELEXes (sector 6) emit numbered
287
779
  * grounds in `paragraphs[]` with empty `recitals[]`; legislation keeps
288
- * `recitals[]` — the two arrays are mutually exclusive on one document.
289
- * With `include`/`fields` selection any of these keys can be omitted.
780
+ * `recitals[]`. With `include`/`fields` selection any key can be omitted.
290
781
  */
291
782
  interface DocumentContent {
292
783
  fullText?: string;
293
784
  articles?: Article[];
294
785
  /** Legislative preamble recitals. Empty `[]` on case-law — see `paragraphs`. */
295
786
  recitals?: Recital[];
296
- /** Judgment grounds (case-law) or fullText splits when no structured extractor matched. */
787
+ /** Judgment grounds (case-law), text outside articles, or fullText splits. */
297
788
  paragraphs?: Recital[];
298
789
  sections?: Section[];
299
790
  /** Genuine data tables only (layout-table noise is filtered out server-side). */
300
791
  tables?: Table[];
301
792
  annexes?: Annex[];
302
793
  }
794
+ /** Why a document response carries no text. */
795
+ type TextUnavailableReason = "not_in_language" | "not_published_yet" | "no_machine_readable_rendition" | "too_large" | "unknown" | (string & {});
796
+ /** Pointer to a consolidated version (CONSLEG, CELEX sector 0) of a base act. */
797
+ interface ConsolidatedVersionHint {
798
+ /** e.g. `"02006R1907-20260622"` — pass back to `getDocument` (a normal, separately charged read). */
799
+ celex: string;
800
+ /** Consolidation date (`YYYY-MM-DD`), from the CELEX suffix. */
801
+ date: string;
802
+ /** `cellar` — Publications Office list; `corpus` — Cellar was unreachable, newest version LexAPI holds. */
803
+ source: "cellar" | "corpus" | (string & {});
804
+ /** `newestConsolidated` only — lower-case ISO codes the version exists in. */
805
+ availableLanguages?: string[];
806
+ }
807
+ /**
808
+ * Whether a document response carries its text, and if not, why. Present on
809
+ * every document response. A text-unavailable document is a `200` with
810
+ * metadata and `content: null` (billed 1 credit), not a 404.
811
+ */
812
+ interface TextAvailability {
813
+ available: boolean;
814
+ /** Absent when `available` is true. */
815
+ reason?: TextUnavailableReason;
816
+ retryable?: boolean;
817
+ /**
818
+ * ISO codes whose text could be served. `null` = unknown; `[]` = known to
819
+ * be none. Those are different facts — do not collapse them.
820
+ */
821
+ availableLanguages?: string[] | null;
822
+ /** Where EUR-Lex itself points for the text (e.g. the European Parliament site). */
823
+ externalSource?: string;
824
+ /** e.g. `"cellar-manifestations"`, `"parse-worker"` (our own `too_large` verdict). */
825
+ source?: string;
826
+ checkedAt?: string;
827
+ /** Base acts only: newest consolidated version dated on or before today, in the requested language. */
828
+ latestConsolidated?: ConsolidatedVersionHint;
829
+ /** Base acts only: the next consolidated version dated after today, in the requested language. */
830
+ upcomingConsolidated?: ConsolidatedVersionHint;
831
+ /** Base acts only: the newest consolidated version when it has NO text in the requested language. */
832
+ newestConsolidated?: ConsolidatedVersionHint;
833
+ }
303
834
  /** Normalized metadata for a single document. */
304
835
  interface DocumentMetadata {
305
836
  /** Canonical CELEX. Always present on metadata responses. */
@@ -308,11 +839,18 @@ interface DocumentMetadata {
308
839
  celexNumber?: string;
309
840
  /** `null` when the document is genuinely sparse — never `"Unknown Title"`. */
310
841
  title?: string | null;
842
+ /**
843
+ * Present only when `title` is NOT in the requested language: the ISO
844
+ * 639-1 code of the language it is in (`en` for the English fallback).
845
+ * Absent means the title is in the requested language.
846
+ */
847
+ titleLanguage?: string;
311
848
  /** Prose form of the document, e.g. `"Regulation"`. */
312
849
  documentType?: string | null;
313
850
  /** Stable enum slug for `documentType` (e.g. `"regulation"`). */
314
851
  documentTypeCode?: DocumentTypeCode | null;
315
- author?: string;
852
+ /** `null` for placeholder authors (e.g. consolidated texts' "Provisional data"). */
853
+ author?: string | null;
316
854
  /** Legacy DD/MM/YYYY string as published by EUR-Lex. Prefer `dateOfDocumentISO`. */
317
855
  dateOfDocument?: string | null;
318
856
  /** ISO-8601 date parsed from `dateOfDocument`. */
@@ -337,40 +875,59 @@ interface DocumentMetadata {
337
875
  directoryCodes?: string[];
338
876
  subject?: string[];
339
877
  }
878
+ /** Canonical EUR-Lex URLs for a document. */
879
+ interface DocumentUrls {
880
+ html?: string;
881
+ metadata?: string;
882
+ pdf?: string;
883
+ xml?: string;
884
+ }
340
885
  /** Fully-parsed document: metadata + structured content. */
341
886
  interface Document extends DocumentMetadata {
342
887
  /** ISO code of the language rendition actually served. */
343
888
  language?: string;
344
889
  /** Present only on a fallback — the language originally requested. */
345
890
  languageRequested?: string;
346
- /** Present only on a fallback — the language served instead (`en`). */
891
+ /** Present only on a fallback — the language served instead. */
347
892
  languageFallback?: string;
348
- content?: DocumentContent;
349
- urls?: {
350
- html?: string;
351
- metadata?: string;
352
- };
893
+ /**
894
+ * `null` when EUR-Lex publishes this document's notice but not its text —
895
+ * check `textAvailability.available` before reading it.
896
+ */
897
+ content?: DocumentContent | null;
898
+ /** Present on every document response. */
899
+ textAvailability?: TextAvailability;
900
+ urls?: DocumentUrls;
901
+ fetchedAt?: string;
902
+ /** Monotonic corpus version of this CELEX (corpus-served documents). */
903
+ version?: number;
353
904
  }
354
905
  /**
355
906
  * Response-side document-type slug. The spec enumerates the known values,
356
907
  * but unknown prose is slugified server-side (e.g. `staff working document`
357
908
  * → `staff_working_document`), so unknown strings must be tolerated.
358
909
  */
359
- type DocumentTypeCode = "regulation" | "directive" | "decision" | "recommendation" | "opinion" | "ag_opinion" | "judgment" | "order" | "communication" | "proposal" | "report" | "resolution" | "declaration" | "treaty" | "protocol" | "agreement" | "guideline" | "staff_working_document" | "abstract" | (string & {});
910
+ type DocumentTypeCode = "regulation" | "directive" | "decision" | "recommendation" | "opinion" | "ag_opinion" | "judgment" | "order" | "communication" | "proposal" | "report" | "resolution" | "declaration" | "treaty" | "protocol" | "agreement" | "guideline" | "staff_working_document" | "consolidated_text" | "abstract" | (string & {});
360
911
  /** A single entry in a search results page. */
361
912
  interface SearchResult {
362
913
  /** Title with HTML entities decoded and sentence-spacing restored. */
363
914
  title?: string;
364
- /** Legacy field. Same value as `celex`. */
915
+ /** Legacy field. Same value as `celex`. May be `""` for rare listings without a parseable CELEX. */
365
916
  celexNumber?: string;
366
- /** Canonical CELEX alias. */
367
- celex?: string;
917
+ /** Canonical CELEX alias. `null` for rare listings without a parseable CELEX. */
918
+ celex?: string | null;
368
919
  /** Legacy field. Same value as `documentType`. */
369
920
  form?: string | null;
370
921
  documentType?: string | null;
371
922
  documentTypeCode?: DocumentTypeCode | null;
372
923
  date?: string;
924
+ dateOfDocument?: string | null;
373
925
  dateOfDocumentISO?: string | null;
926
+ /** Qualifier EUR-Lex appends to the date (e.g. `"Date of signature"`). */
927
+ dateType?: string | null;
928
+ ecli?: string | null;
929
+ /** EUR-Lex internal reference number, when listed. */
930
+ internalNumber?: string | null;
374
931
  author?: string | null;
375
932
  /**
376
933
  * Upper-case 2-letter ISO codes the document is published in. Empty `[]`
@@ -385,29 +942,43 @@ interface SearchResult {
385
942
  * is required — a completely empty body fails with 400.
386
943
  */
387
944
  interface SearchRequest {
388
- /** Free-text search. Prefer 1–3 distinctive terms; quotes force exact-phrase matching. */
945
+ /**
946
+ * Free-text search. Prefer 1–3 distinctive terms; quotes force
947
+ * exact-phrase matching. `"*"` (or only wildcard/quote characters) means
948
+ * no text constraint — a filter-only search.
949
+ */
389
950
  query?: string;
951
+ /** Bypass the 60-minute result cache and re-fetch from EUR-Lex. Same price. Default `false`. */
952
+ fresh?: boolean;
390
953
  textScope?: TextScope;
391
954
  dateFrom?: string;
392
955
  dateTo?: string;
393
956
  year?: number | number[];
394
957
  month?: number | number[];
395
958
  /** Multi-value arrays fan out to one EUR-Lex search per resolved form code. */
396
- documentType?: DocumentType | DocumentType[];
397
- author?: Author | Author[];
398
- procedure?: Procedure | Procedure[];
959
+ documentType?: OneOrMany<DocumentType>;
960
+ author?: OneOrMany<Author>;
961
+ procedure?: OneOrMany<Procedure>;
399
962
  domain?: Domain;
400
- subdomain?: Subdomain | Subdomain[];
963
+ /**
964
+ * One subdomain or several. Several are ORed when the EUR-Lex web service
965
+ * answers (`headers.searchSource === "soap"`, the normal path). If the
966
+ * search falls back to EUR-Lex result pages (no `searchSource`), EUR-Lex
967
+ * applies only the FIRST subdomain; the Cellar listing fallback does not
968
+ * take several at all. Pass one subdomain when the result set must be exact.
969
+ */
970
+ subdomain?: OneOrMany<Subdomain>;
401
971
  language?: Language;
402
972
  /**
403
- * EUR-Lex result pages to fetch. Clamped to the subscription tier
404
- * (FREE=1, STARTER=5, PROFESSIONAL=20, BUSINESS=100); if clamped, the
405
- * response carries an `X-Warning` header (surfaced as `xWarning`).
973
+ * EUR-Lex result pages to fetch (3 credits per page, unfetched pages
974
+ * refunded). Clamped to the subscription tier (FREE=1, STARTER=5,
975
+ * PROFESSIONAL=20, BUSINESS/SCALE/ENTERPRISE=100); if clamped, the response
976
+ * carries an `X-Warning` header (surfaced as `xWarning`).
406
977
  */
407
978
  maxPages?: number;
408
979
  }
409
- interface SearchResponse extends CreditedResponse {
410
- searchParameters?: SearchRequest;
980
+ interface SearchResponse extends CreditedResponse, WithResponseHeaders {
981
+ searchParameters?: Omit<SearchRequest, "fresh" | "maxPages">;
411
982
  /** Total matching documents on EUR-Lex. */
412
983
  totalResults?: number;
413
984
  /** Total result pages available on EUR-Lex. */
@@ -416,6 +987,17 @@ interface SearchResponse extends CreditedResponse {
416
987
  /** Number of results in this response. */
417
988
  resultCount?: number;
418
989
  results?: SearchResult[];
990
+ /**
991
+ * Present only when the search returned nothing: routes the caller to
992
+ * semantic search (EUR-Lex keyword search is literal).
993
+ */
994
+ hint?: string;
995
+ /**
996
+ * `"corpus"` when EUR-Lex was unreachable and the answer came from the
997
+ * LexAPI corpus mirror — always with `partial: true` (possibly incomplete,
998
+ * title-only text matching).
999
+ */
1000
+ source?: "corpus" | (string & {});
419
1001
  /**
420
1002
  * Present and `true` when the result set was capped by the tier
421
1003
  * `maxPages` limit and more pages exist on EUR-Lex. Check
@@ -427,65 +1009,73 @@ interface SearchResponse extends CreditedResponse {
427
1009
  truncatedReason?: string;
428
1010
  /**
429
1011
  * Present and `true` when an upstream timeout dropped one of the
430
- * requested pages; the pages collected before the failure are still in
431
- * `results`. Check `partialReason`.
1012
+ * requested pages, or the answer came from the corpus fallback. Check
1013
+ * `partialReason`.
432
1014
  */
433
1015
  partial?: boolean;
434
1016
  partialReason?: string;
435
1017
  /**
436
1018
  * Comma-joined dimensions on which a controller-side post-filter dropped
437
- * rows (`author`, `date`, `documentType`). `"date"` signals the
438
- * recall-vs-pagination trade-off: raise `maxPages` to widen recall on
439
- * tight date filters.
1019
+ * rows (`author`, `date`). `"date"` signals the recall-vs-pagination
1020
+ * trade-off: raise `maxPages` to widen recall on tight date filters.
440
1021
  */
441
1022
  postFilteredBy?: string;
442
1023
  /** Requested types that resolve to no EUR-Lex form code (reported, not silently dropped). */
443
1024
  ignoredDocumentTypes?: string[];
444
1025
  fetchedAt?: string;
445
- /**
446
- * SDK-added: contents of the `X-Warning` response header when present
447
- * (e.g. `maxPages` clamped to the tier ceiling). Not part of the JSON body.
448
- */
1026
+ /** SDK-added: the `X-Warning` response header (e.g. `maxPages` clamped). */
449
1027
  xWarning?: string;
450
1028
  }
451
1029
  interface DocumentContentRequest {
1030
+ /** CELEX, incl. corrigenda (`32013R0952R(04)`) and consolidated forms (`02016R0679-20180524`). */
452
1031
  celexNumber: string;
453
- /** Force a live scrape, bypassing the corpus cache. */
1032
+ /** Force a fresh upstream read, bypassing the corpus row and the HTML fetch cache (billed at the live rate). */
454
1033
  bypassCorpus?: boolean;
455
1034
  /**
456
1035
  * Language rendition to return (whole document). Falls back to English
457
- * when unavailable — see `languageRequested`/`languageFallback` on the
458
- * document.
1036
+ * when unavailable — see `languageRequested`/`languageFallback`.
459
1037
  */
460
1038
  language?: Language;
1039
+ /**
1040
+ * Opt-in fallback when the requested language has no text: the first
1041
+ * accepted language that does is served instead (labelled like the
1042
+ * automatic English fallback).
1043
+ */
1044
+ acceptLanguages?: AcceptLanguages;
461
1045
  /** Trim the response payload to the listed pieces. */
462
1046
  include?: IncludeSelection;
463
1047
  /** Alias accepted alongside `include`. */
464
1048
  fields?: IncludeSelection;
465
- /** Narrow `content.articles` to a single article (`art_17`, `17`, or `Article 17`). */
1049
+ /** Narrow `content.articles` to one article (`art_17`, `17`, `Article 17`, `6a`). */
466
1050
  articleId?: string;
467
1051
  }
468
- interface DocumentContentResponse extends CreditedResponse {
1052
+ interface DocumentContentResponse extends CreditedResponse, WithResponseHeaders {
469
1053
  success: boolean;
470
1054
  document: Document;
471
1055
  }
472
1056
  interface DocumentContentBatchRequest {
473
- /** Truncated to the tier batch ceiling (FREE=1, STARTER=5, PROFESSIONAL=20, BUSINESS=50). */
1057
+ /** Truncated to the tier batch ceiling (FREE=1, STARTER=5, PROFESSIONAL=20, BUSINESS+=50). */
474
1058
  celexNumbers: string[];
475
1059
  bypassCorpus?: boolean;
476
1060
  language?: Language;
1061
+ acceptLanguages?: AcceptLanguages;
477
1062
  include?: IncludeSelection;
478
1063
  fields?: IncludeSelection;
479
1064
  articleId?: string;
480
1065
  }
481
- /** One failed CELEX from a batch fetch. */
1066
+ /** One failed CELEX from a batch fetch — as the server sends it: `{ celex, error }`. */
482
1067
  interface BatchDocumentError {
483
- celexNumber?: string;
484
- /** Short error slug (includes upstream timeouts as `"FetchTimeoutError" | "TIMEOUT"`). */
1068
+ /** The CELEX that failed. */
1069
+ celex?: string;
1070
+ /** Free-text failure message (not a stable slug). */
485
1071
  error?: string;
1072
+ /** @deprecated Never sent by the server — read `celex`. */
1073
+ celexNumber?: string;
1074
+ /** @deprecated Never sent by the server — read `error`. */
486
1075
  message?: string;
1076
+ [key: string]: unknown;
487
1077
  }
488
- interface DocumentContentBatchResponse extends CreditedResponse {
1078
+ interface DocumentContentBatchResponse extends CreditedResponse, WithResponseHeaders {
489
1079
  success: boolean;
490
1080
  /** Number of CELEX numbers in the request body. */
491
1081
  requested: number;
@@ -493,11 +1083,15 @@ interface DocumentContentBatchResponse extends CreditedResponse {
493
1083
  processed: number;
494
1084
  successful: number;
495
1085
  failed: number;
1086
+ /**
1087
+ * Returned documents that carry metadata but no text (`content: null`).
1088
+ * They stay in `documents[]`, not `errors[]`.
1089
+ */
1090
+ textUnavailable?: number;
496
1091
  /**
497
1092
  * Present and `true` when the request exceeded the tier batch ceiling.
498
- * Mirrors the `X-Warning` header (also surfaced as `xWarning`). Check
499
- * `trimmedTo`/`trimmedReason` — trimmed entries were silently dropped
500
- * server-side.
1093
+ * Check `trimmedTo`/`trimmedReason` — trimmed entries were dropped
1094
+ * server-side (and not charged).
501
1095
  */
502
1096
  trimmed?: boolean;
503
1097
  trimmedTo?: number;
@@ -511,26 +1105,36 @@ interface DocumentContentBatchResponse extends CreditedResponse {
511
1105
  interface RecentDocumentsParams {
512
1106
  /** How many days back from today to include. Default 7. */
513
1107
  days?: number;
1108
+ /**
1109
+ * ONE document type. The endpoint applies only the first type of a list
1110
+ * (no fan-out, unlike `/search`), so the SDK accepts a single value.
1111
+ */
514
1112
  documentType?: DocumentType;
515
- author?: Author;
1113
+ /** One author or several (sent as repeated params; EUR-Lex ORs them). */
1114
+ author?: OneOrMany<Author>;
516
1115
  domain?: Domain;
1116
+ /**
1117
+ * ONE subdomain. A subdomain filter sends the request to EUR-Lex result
1118
+ * pages, where EUR-Lex reads only the first `DTS_SUBDOM` value
1119
+ * (lex-api `server/utils/urlBuilder.js`), so the SDK accepts a single value.
1120
+ */
517
1121
  subdomain?: Subdomain;
518
1122
  /** Result language (default `en`). */
519
1123
  language?: Language;
520
- /** Maximum number of results to return. Default 50. */
1124
+ /** Maximum number of results to return. Default 50 (3 credits per ~10 results, tier-capped). */
521
1125
  limit?: number;
522
1126
  }
523
- interface RecentDocumentsResponse extends CreditedResponse {
1127
+ interface RecentDocumentsResponse extends CreditedResponse, WithResponseHeaders {
524
1128
  success: boolean;
525
1129
  /** Echo of the resolved query parameters (with computed `dateFrom`/`dateTo`). */
526
1130
  parameters?: {
527
1131
  days?: number;
528
1132
  dateFrom?: string;
529
1133
  dateTo?: string;
530
- documentType?: string | null;
531
- author?: string | null;
1134
+ documentType?: string | string[] | null;
1135
+ author?: string | string[] | null;
532
1136
  domain?: string | null;
533
- subdomain?: string | null;
1137
+ subdomain?: string | string[] | null;
534
1138
  language?: string;
535
1139
  limit?: number;
536
1140
  };
@@ -542,6 +1146,8 @@ interface RecentDocumentsResponse extends CreditedResponse {
542
1146
  requested: string;
543
1147
  kept: number;
544
1148
  beforeFilter: number;
1149
+ /** Rows kept leniently because their language list was too short to trust. */
1150
+ partialMetadataKept?: number;
545
1151
  };
546
1152
  fetchedAt?: string;
547
1153
  /** SDK-added: `X-Warning` response header, when present. */
@@ -550,11 +1156,13 @@ interface RecentDocumentsResponse extends CreditedResponse {
550
1156
  interface DocumentByUrlRequest {
551
1157
  /** Any `eur-lex.europa.eu` URL containing a CELEX (path segment or `uri=` param). */
552
1158
  url: string;
1159
+ /** Force a fresh upstream read (accepted by the server; billed at the live rate). */
1160
+ bypassCorpus?: boolean;
553
1161
  include?: IncludeSelection;
554
1162
  fields?: IncludeSelection;
555
1163
  articleId?: string;
556
1164
  }
557
- interface DocumentByUrlResponse extends CreditedResponse {
1165
+ interface DocumentByUrlResponse extends CreditedResponse, WithResponseHeaders {
558
1166
  success: boolean;
559
1167
  /** The exact URL passed in the request body. */
560
1168
  sourceUrl: string;
@@ -566,44 +1174,195 @@ interface DocumentMetadataRequest {
566
1174
  celexNumber: string;
567
1175
  bypassCorpus?: boolean;
568
1176
  }
569
- interface DocumentMetadataResponse extends CreditedResponse {
1177
+ interface DocumentMetadataResponse extends CreditedResponse, WithResponseHeaders {
570
1178
  success: boolean;
571
1179
  /** Metadata-only — no `content`. Includes the canonical EUR-Lex URLs. */
572
1180
  metadata: DocumentMetadata & {
573
- urls?: {
574
- html?: string;
575
- metadata?: string;
576
- pdf?: string;
577
- xml?: string;
578
- };
1181
+ /**
1182
+ * Sector-3 base acts only, and only when a recent document read already
1183
+ * looked it up (cached ~24 h). Absent means "not looked up", not "none exists".
1184
+ */
1185
+ latestConsolidated?: ConsolidatedVersionHint;
1186
+ upcomingConsolidated?: ConsolidatedVersionHint;
1187
+ newestConsolidated?: ConsolidatedVersionHint;
1188
+ urls?: DocumentUrls;
579
1189
  };
580
1190
  }
581
1191
  type IdentifierType = "celex" | "url" | "eli" | "ecli";
582
- interface ResolveResponse {
1192
+ /**
1193
+ * Which resolution path matched. `celex`/`url` resolve purely from the
1194
+ * identifier; `ecli-corpus` / `eli-corpus` mean a corpus lookup answered;
1195
+ * `eli-cellar` means the ELI was looked up in the Publications Office's
1196
+ * Cellar register. `eli` means the CELEX was derived from the ELI's pattern
1197
+ * alone (`verified: false` on servers that send `verified`).
1198
+ */
1199
+ type ResolvedVia = "celex" | "url" | "eli" | "ecli-corpus" | "eli-corpus" | "eli-cellar" | (string & {});
1200
+ interface ResolveResponse extends CreditedResponse, WithResponseHeaders {
583
1201
  success: boolean;
584
1202
  /** Echo of the caller's input. */
585
1203
  identifier: string;
586
1204
  identifierType: IdentifierType;
587
- /** Which resolution path matched. Pure path for celex/url/eli; corpus lookup for ecli. */
588
- resolvedVia: IdentifierType;
1205
+ resolvedVia: ResolvedVia;
1206
+ /**
1207
+ * `true` when the corpus or Cellar confirmed the identifier → CELEX mapping.
1208
+ * `false` when the CELEX was read off the identifier without a lookup:
1209
+ * CELEX and URL inputs (resolve does not check that the document exists),
1210
+ * and an ELI resolved from its pattern while Cellar was unreachable — that
1211
+ * last kind may name a CELEX that does not exist, so resolve it again later.
1212
+ * Absent on servers older than the field.
1213
+ */
1214
+ verified?: boolean;
589
1215
  celex: string;
590
- urls: {
591
- metadata?: string;
592
- html?: string;
593
- pdf?: string;
594
- xml?: string;
595
- };
1216
+ urls: DocumentUrls;
1217
+ }
1218
+ /**
1219
+ * Classification of a citation edge. `amendment`, `repeal` and
1220
+ * `corrigendum` are structural relations (from Cellar for legislation).
1221
+ * `transposition` (API 2.11.0): a member-state measure → the EU act it was
1222
+ * notified for or records that it transposes. A notified measure is a
1223
+ * notification, not a finding that the measure transposes the act, or
1224
+ * transposes it completely.
1225
+ */
1226
+ type CitationType = "reference" | "amendment" | "repeal" | "corrigendum" | "implementation" | "legal-basis" | "proposal" | "transposition";
1227
+ /** Every {@link CitationType} value, for building filters or validating input. */
1228
+ declare const CITATION_TYPES: readonly ["reference", "amendment", "repeal", "corrigendum", "implementation", "legal-basis", "proposal", "transposition"];
1229
+ /**
1230
+ * Where an edge comes from (API 2.11.0): `notice` — the EUR-Lex notice page
1231
+ * of the citing document; `cellar` — a relation recorded in the Publications
1232
+ * Office's Cellar repository; `notice+cellar` — both; `cellar-nim` — a
1233
+ * measure a member state notified to the Commission for an EU act (a
1234
+ * notification, not a finding that the measure transposes the act);
1235
+ * `source` — the national source itself records the relation; `resolver` —
1236
+ * the national source records a textual reference that LexAPI's
1237
+ * deterministic resolver matched (see {@link CitationResolution}).
1238
+ */
1239
+ type CitationProvenance = "notice" | "cellar" | "notice+cellar" | "cellar-nim" | "source" | "resolver";
1240
+ /** Every {@link CitationProvenance} value. */
1241
+ declare const CITATION_PROVENANCES: readonly ["notice", "cellar", "notice+cellar", "cellar-nim", "source", "resolver"];
1242
+ /**
1243
+ * How the target of a national edge was identified (API 2.11.0): `id` — the
1244
+ * source names it by its id or a one-to-one native id; `key` — a unique
1245
+ * native key (an official number, a gazette position); `abbreviation` — a
1246
+ * code abbreviation matched to its act (filter it out with
1247
+ * `resolution: ["id", "key"]` if you need only id and key matches);
1248
+ * `text-pattern` — an EU act number with its EU marker found in running
1249
+ * text. Edges read from EUR-Lex or Cellar have no resolution (`null`).
1250
+ */
1251
+ type CitationResolution = "id" | "key" | "abbreviation" | "text-pattern";
1252
+ /** Every {@link CitationResolution} value. */
1253
+ declare const CITATION_RESOLUTIONS: readonly ["id", "key", "abbreviation", "text-pattern"];
1254
+ /**
1255
+ * A graph node's kind (API 2.11.0): `act` for an EU act (CELEX sector 3) or a
1256
+ * national act, `decision` for an EU court decision (sector 6) or a national
1257
+ * decision; `null` for every other CELEX sector.
1258
+ */
1259
+ type CitationDocumentKind = "act" | "decision";
1260
+ /**
1261
+ * Where `totalCitations` / `totalEdges` (and the network's paging totals)
1262
+ * come from (API 2.10.0): `stats` — the per-node counts the graph maintains
1263
+ * with every write; `counted` — counted over the matching edge rows for this
1264
+ * request. Both are exact for the request; the totals mean the same either way.
1265
+ */
1266
+ type CountsSource = "stats" | "counted";
1267
+ /**
1268
+ * The identity of a graph node (API 2.11.0), on every `citedBy[]` /
1269
+ * `cites[]` group, network neighbour, `path[]` node and `related[]` entry.
1270
+ * `celexNumber` is unchanged and carries the same id.
1271
+ */
1272
+ interface CitationNode {
1273
+ /** The CELEX number of an EU document; a national document's LexAPI id (`AT-NOR-10001597`). */
1274
+ id?: string | null;
1275
+ /** `EU` for an EU document, otherwise the upper-case national code (`AT`, `DE`, …). */
1276
+ jurisdiction?: string | null;
1277
+ documentKind?: CitationDocumentKind | null;
1278
+ }
1279
+ /**
1280
+ * Edge filters shared by `getCites`, `getCitedBy`, `getCitationNetwork`,
1281
+ * `getCitationPath` and `getRelatedDocuments` (API 2.11.0). Each takes one
1282
+ * value or a list, sent comma-separated. An unknown value is a `400`
1283
+ * `InvalidParamsError` naming the parameter (`err.param`) and its allowed
1284
+ * values (`err.allowed`), refunded in full.
1285
+ */
1286
+ interface CitationFilterParams {
1287
+ /** Keep only edges of these types (one value or a list). */
1288
+ citationType?: OneOrMany<CitationType>;
1289
+ /**
1290
+ * Keep only edges with these provenances. `cellar-nim`, `source` and
1291
+ * `resolver` are accepted only while a national jurisdiction is open to you.
1292
+ */
1293
+ provenance?: OneOrMany<CitationProvenance>;
1294
+ /**
1295
+ * Keep only neighbours in these jurisdictions: `eu` and the lower-case
1296
+ * codes of the national jurisdictions open to you (`["eu", "at"]`). A
1297
+ * national code asks for national documents exactly like
1298
+ * `includeNational: true`, with the same plan gate (BUSINESS, SCALE and
1299
+ * ENTERPRISE; `403 TierForbiddenError` below). Any other code is a `400`.
1300
+ */
1301
+ jurisdictions?: OneOrMany<string>;
1302
+ /**
1303
+ * Keep only edges whose target was identified by one of these methods
1304
+ * (national edges only — EU edges never match). While no national
1305
+ * jurisdiction is open to you every value is a `400`.
1306
+ */
1307
+ resolution?: OneOrMany<CitationResolution>;
1308
+ }
1309
+ /**
1310
+ * A reference a national document records that LexAPI could not turn into
1311
+ * an edge (API 2.11.0) — `unresolved: true` on `getCites` /
1312
+ * `getCitationNetwork` for a national document id.
1313
+ */
1314
+ interface UnresolvedReference {
1315
+ /** What the source recorded: a cited norm, an EU act, a relation field, a notified measure. */
1316
+ kind: "norm" | "eu-act" | "relation" | "nim" | (string & {});
1317
+ /** The source's own string (at most 500 characters). */
1318
+ text: string;
1319
+ /** What the resolver understood of `text`; `null` when nothing. */
1320
+ parsedKey: Record<string, unknown> | null;
1321
+ /**
1322
+ * `unresolved` — not matched; `not-held` — identified, but LexAPI does not
1323
+ * hold it; `ambiguous` — more than one candidate; `out-of-scope` — a target
1324
+ * outside the graph.
1325
+ */
1326
+ status: "unresolved" | "not-held" | "ambiguous" | "out-of-scope" | (string & {});
1327
+ /** The id the target would have, when it could be built and is visible to you. */
1328
+ targetId: string | null;
1329
+ }
1330
+ /**
1331
+ * Where a neighbour's title came from: the corpus (in the requested
1332
+ * language, or another language), a citation row, the edge itself, or
1333
+ * `unknown` (no title anywhere).
1334
+ */
1335
+ type TitleSource = "corpus" | "corpus-fallback-lang" | "citation-source" | "citation-target" | "edge" | "unknown" | (string & {});
1336
+ /**
1337
+ * Freshness of the target's inbound structural edges (amendment /
1338
+ * corrigendum / repeal), refreshed from Cellar at most once every 7 days.
1339
+ */
1340
+ interface RelationSync {
1341
+ source?: "cellar";
1342
+ /**
1343
+ * `fresh` (nothing to do), `refreshed` (during this request), `pending`
1344
+ * (refresh took >2.5 s and finishes in the background — this response
1345
+ * shows the previously stored edges), `cooldown`/`error` (Cellar failed
1346
+ * recently), `skipped` (see `reason`).
1347
+ */
1348
+ status?: "fresh" | "refreshed" | "pending" | "cooldown" | "error" | "skipped" | (string & {});
1349
+ /** Present when `status` is `skipped`. */
1350
+ reason?: "not-applicable" | "disabled" | "busy" | "budget" | (string & {});
1351
+ /** Last completed refresh when known; null when never refreshed. */
1352
+ syncedAt?: string | null;
596
1353
  }
597
- /** Classification of a citation edge. */
598
- type CitationType = "reference" | "amendment" | "repeal" | "implementation" | "legal-basis" | "proposal";
599
1354
  /** Edge shape emitted on fresh extraction. */
600
1355
  interface CitationEdgeSummary {
1356
+ /** The citing document. */
1357
+ sourceCelex?: string;
601
1358
  targetCelex?: string;
1359
+ /** Whether the edge was found pointing out of (`outbound`) or into (`inbound`) the extracted document. */
1360
+ direction?: "outbound" | "inbound" | (string & {});
602
1361
  citationType?: CitationType;
603
1362
  /** Surrounding text around the citation on the source metadata page, when available. */
604
1363
  contextSnippet?: string | null;
605
1364
  }
606
- interface CitationExtractResponse {
1365
+ interface CitationExtractResponse extends CreditedResponse, WithResponseHeaders {
607
1366
  success: boolean;
608
1367
  message?: string;
609
1368
  /** Present on fresh extraction. Omitted when `alreadyExtracted` is true. */
@@ -613,9 +1372,9 @@ interface CitationExtractResponse {
613
1372
  };
614
1373
  /** Number of citation edges persisted (or already on file). */
615
1374
  citationCount?: number;
616
- /** Edges that were just extracted. Empty array when `alreadyExtracted: true`. */
1375
+ /** Edges that were just extracted. Omitted when `alreadyExtracted: true`. */
617
1376
  citations?: CitationEdgeSummary[];
618
- /** True when the document had already been processed (extraction is idempotent). */
1377
+ /** True when the document had already been processed (settles at 1 credit). */
619
1378
  alreadyExtracted?: boolean;
620
1379
  }
621
1380
  /** A single citation edge with classification, context, and timestamp. */
@@ -623,69 +1382,132 @@ interface CitationEdgeDetail {
623
1382
  citationType?: CitationType;
624
1383
  contextSnippet?: string | null;
625
1384
  extractedAt?: string;
1385
+ /** Where the edge comes from (API 2.11.0); `null` on a national edge not yet classified. */
1386
+ provenance?: CitationProvenance | null;
1387
+ /** How the target was identified (API 2.11.0); `null` on every EUR-Lex / Cellar edge. */
1388
+ resolution?: CitationResolution | null;
626
1389
  }
627
1390
  /** All edges from one source document into the target (cited-by grouping). */
628
- interface CitingDocumentGroup {
1391
+ interface CitingDocumentGroup extends CitationNode {
629
1392
  celexNumber?: string;
630
1393
  title?: string | null;
1394
+ titleSource?: TitleSource;
1395
+ /** Edges of this source in THIS page (raw citation rows). */
631
1396
  citationCount?: number;
1397
+ /** A `…_RES` variant of the source was collapsed into this group. */
1398
+ hasResume?: boolean;
1399
+ /** A `…_SUM` variant of the source was collapsed into this group. */
1400
+ hasSummary?: boolean;
632
1401
  citations?: CitationEdgeDetail[];
633
1402
  }
634
1403
  /** All edges from the source document into one target (cites grouping). */
635
- interface CitedDocumentGroup {
1404
+ interface CitedDocumentGroup extends CitationNode {
636
1405
  celexNumber?: string;
637
1406
  title?: string | null;
1407
+ titleSource?: TitleSource;
638
1408
  citationCount?: number;
639
1409
  citations?: CitationEdgeDetail[];
640
1410
  }
641
- /** Pagination filters shared by the cites / cited-by endpoints. */
642
- interface CitationEdgeParams {
643
- /** Filter to a single citation type. */
644
- citationType?: CitationType;
1411
+ /** Pagination and filters shared by the cites / cited-by endpoints. */
1412
+ interface CitationEdgeParams extends CitationFilterParams {
645
1413
  /** Max edges to return per page. Default 100. */
646
1414
  limit?: number;
647
1415
  /** Pagination offset (in edges, not documents). Default 0. */
648
1416
  offset?: number;
1417
+ /** Language preferred for neighbour titles (default `en`). */
1418
+ language?: Language;
1419
+ /**
1420
+ * Also return national documents of live jurisdictions as neighbours
1421
+ * (national acts/decisions that cite, implement or are cited by the EU
1422
+ * graph, where the national source records the link). BUSINESS, SCALE
1423
+ * and ENTERPRISE only — `403 TierForbiddenError` below that. A `celexNumber`
1424
+ * that is itself a national id (`AT-…`) includes national neighbours
1425
+ * without this flag.
1426
+ */
1427
+ includeNational?: boolean;
1428
+ }
1429
+ /** Params for {@link getCites}: the shared edge params plus `unresolved`. */
1430
+ interface CitesParams extends CitationEdgeParams {
1431
+ /**
1432
+ * `true` on a national document id adds `unresolved` /
1433
+ * `unresolvedTruncated` to the response — the references the document
1434
+ * records that could not be turned into an edge. Ignored on an EU id. No
1435
+ * extra credits.
1436
+ */
1437
+ unresolved?: boolean;
649
1438
  }
650
- interface CitedByResponse {
1439
+ interface CitedByResponse extends CreditedResponse, WithResponseHeaders {
651
1440
  success: boolean;
652
1441
  /** The CELEX whose inbound edges are being listed. */
653
1442
  targetDocument: string;
654
- /** Total inbound edges matching the filter (across all pages). */
1443
+ /** Distinct citing→cited document pairs matching the filter (across all pages). */
655
1444
  totalCitations?: number;
1445
+ /** Edge rows matching the filter — what `offset` / `limit` page over. */
1446
+ totalEdges?: number;
1447
+ /** Where the totals come from (API 2.10.0). */
1448
+ countsSource?: CountsSource;
1449
+ /** Citing documents in THIS page (not the global distinct total). */
656
1450
  uniqueDocuments?: number;
657
1451
  limit?: number;
658
1452
  offset?: number;
659
1453
  citedBy: CitingDocumentGroup[];
1454
+ relationSync?: RelationSync;
1455
+ /** Whether national documents were included (see `includeNational`). Absent while no national jurisdiction is live. */
1456
+ includeNational?: boolean;
660
1457
  }
661
- interface CitesResponse {
1458
+ interface CitesResponse extends CreditedResponse, WithResponseHeaders {
662
1459
  success: boolean;
663
1460
  /** The CELEX whose outbound edges are being listed. */
664
1461
  sourceDocument: string;
1462
+ /** Distinct citing→cited document pairs matching the filter (across all pages). */
665
1463
  totalCitations?: number;
1464
+ /** Edge rows matching the filter — what `offset` / `limit` page over. */
1465
+ totalEdges?: number;
1466
+ /** Where the totals come from (API 2.10.0). */
1467
+ countsSource?: CountsSource;
1468
+ /** Cited documents in THIS page (not the global distinct total). */
666
1469
  uniqueDocuments?: number;
667
1470
  limit?: number;
668
1471
  offset?: number;
669
1472
  cites: CitedDocumentGroup[];
1473
+ /** Whether national documents were included (see `includeNational`). Absent while no national jurisdiction is live. */
1474
+ includeNational?: boolean;
1475
+ /** With `unresolved: true` on a national document id: references that did not become an edge (at most 500). */
1476
+ unresolved?: UnresolvedReference[];
1477
+ /** `true` when the document has more than 500 such references. With `unresolved` only. */
1478
+ unresolvedTruncated?: boolean;
1479
+ }
1480
+ /** One distinct (`citationType`, `provenance`, `resolution`) combination of a neighbour's edges (API 2.11.0). */
1481
+ interface CitationEdgeKind {
1482
+ citationType: CitationType;
1483
+ provenance: CitationProvenance | null;
1484
+ resolution: CitationResolution | null;
670
1485
  }
671
1486
  /** A neighbour in the citation graph, deduplicated across edge types. */
672
- interface CitationNeighbour {
1487
+ interface CitationNeighbour extends CitationNode {
673
1488
  celexNumber?: string;
674
1489
  title?: string | null;
1490
+ titleSource?: TitleSource;
675
1491
  /** Number of edges to/from this neighbour. */
676
1492
  count?: number;
677
1493
  /** Union of `citationType` values across all edges to/from it. */
678
1494
  types?: CitationType[];
1495
+ /** The distinct type / provenance / resolution of this page's edges to/from the neighbour (API 2.11.0). */
1496
+ edgeDetails?: CitationEdgeKind[];
679
1497
  }
680
- interface CitationNetworkParams {
681
- /** Filter both directions to a single citation type. */
682
- citationType?: CitationType;
1498
+ interface CitationNetworkParams extends CitationFilterParams {
683
1499
  /** Max edges to fetch per direction (default 100, max 500). */
684
1500
  limit?: number;
685
1501
  /** Pagination offset (in edges, applied to both directions). */
686
1502
  offset?: number;
1503
+ /** Language preferred for neighbour titles (default `en`). */
1504
+ language?: Language;
1505
+ /** Also include national neighbours of live jurisdictions. BUSINESS+ only — `403 TierForbiddenError` below that. */
1506
+ includeNational?: boolean;
1507
+ /** `true` on a national document id adds `unresolved` / `unresolvedTruncated` (not on a partial response). No extra credits. */
1508
+ unresolved?: boolean;
687
1509
  }
688
- interface CitationNetworkResponse {
1510
+ interface CitationNetworkResponse extends CreditedResponse, WithResponseHeaders {
689
1511
  success: boolean;
690
1512
  /** The centre CELEX. */
691
1513
  document: string;
@@ -706,11 +1528,16 @@ interface CitationNetworkResponse {
706
1528
  citesTotal: number | null;
707
1529
  /** Total inbound edges matching the query. `null` when the response is partial. */
708
1530
  citedByTotal: number | null;
1531
+ /** Outbound edge ROWS — what `offset` pages over. `null` when partial. */
1532
+ citesEdgeTotal?: number | null;
1533
+ /** Inbound edge ROWS — what `offset` pages over. `null` when partial. */
1534
+ citedByEdgeTotal?: number | null;
1535
+ /** Where the totals come from (API 2.10.0); `null` when partial. */
1536
+ countsSource?: CountsSource | null;
709
1537
  };
710
1538
  /**
711
1539
  * Present and `true` when the server-side wall-clock budget expired —
712
- * `network` arrays are empty and paging totals `null`. Retry with a
713
- * smaller `limit` or use the per-direction endpoints. Do not treat an
1540
+ * `network` arrays are empty and paging totals `null`. Do not treat an
714
1541
  * empty partial network as "no citations".
715
1542
  */
716
1543
  partial?: boolean;
@@ -718,6 +1545,13 @@ interface CitationNetworkResponse {
718
1545
  message?: string;
719
1546
  /** The server-side budget that expired (only on partial responses). */
720
1547
  timeoutMs?: number;
1548
+ relationSync?: RelationSync;
1549
+ /** Whether national neighbours were included (see `includeNational`). Absent while no national jurisdiction is live. */
1550
+ includeNational?: boolean;
1551
+ /** With `unresolved: true` on a national document id: references that did not become an edge (at most 500). */
1552
+ unresolved?: UnresolvedReference[];
1553
+ /** `true` when the document has more than 500 such references. With `unresolved` only. */
1554
+ unresolvedTruncated?: boolean;
721
1555
  }
722
1556
  interface CitationStatsTopCited {
723
1557
  celexNumber?: string;
@@ -729,8 +1563,15 @@ interface CitationStatsTopCiting {
729
1563
  title?: string | null;
730
1564
  citesCount?: number;
731
1565
  }
732
- interface CitationStatsResponse {
1566
+ /** Params for {@link getCitationStats}. */
1567
+ interface CitationStatsParams {
1568
+ /** Also count national documents of live jurisdictions. BUSINESS+ only — `403 TierForbiddenError` below that. */
1569
+ includeNational?: boolean;
1570
+ }
1571
+ interface CitationStatsResponse extends CreditedResponse, WithResponseHeaders {
733
1572
  success: boolean;
1573
+ /** Whether national documents were counted (see `includeNational`). Absent while no national jurisdiction is live. */
1574
+ includeNational?: boolean;
734
1575
  stats: {
735
1576
  totalCitations: number;
736
1577
  uniqueSourceDocuments: number;
@@ -739,14 +1580,57 @@ interface CitationStatsResponse {
739
1580
  mostCited: CitationStatsTopCited[];
740
1581
  /** Top-10 documents with the most outbound citations. */
741
1582
  mostCiting: CitationStatsTopCiting[];
1583
+ /**
1584
+ * With `includeNational: true` only (API 2.11.0): per jurisdiction (`EU`
1585
+ * and each live one in scope), the edges whose citing end (`asSource`) or
1586
+ * cited end (`asTarget`) is in it. Unclassified edges are counted under
1587
+ * `unstamped`, only while there are any.
1588
+ */
1589
+ byJurisdiction?: Record<string, {
1590
+ asSource?: number;
1591
+ asTarget?: number;
1592
+ }>;
1593
+ /** With `includeNational: true` only: edges per `provenance` value (`unstamped` while edges remain unclassified). */
1594
+ byProvenance?: Record<string, number>;
1595
+ /**
1596
+ * With `includeNational: true` only: the measures the in-scope member
1597
+ * states notified to the Commission that Cellar still lists, and how many
1598
+ * are matched to a document LexAPI holds — the same rule as `counts` on
1599
+ * {@link TranspositionResponse}.
1600
+ */
1601
+ transposition?: {
1602
+ measures?: number;
1603
+ resolved?: number;
1604
+ byCountry?: Record<string, {
1605
+ measures?: number;
1606
+ resolved?: number;
1607
+ }>;
1608
+ };
742
1609
  };
1610
+ /** When these (cached) statistics were computed. */
1611
+ cachedAt?: string;
1612
+ /** How long the statistics are cached, in seconds. */
1613
+ cacheTtlSeconds?: number;
743
1614
  }
744
- interface CitationPathNode {
1615
+ interface CitationPathNode extends CitationNode {
745
1616
  celexNumber: string;
746
1617
  /** Enriched at read time from the corpus where available. */
747
1618
  title: string | null;
1619
+ titleSource?: TitleSource;
1620
+ }
1621
+ interface CitationPathParams extends CitationFilterParams {
1622
+ /** Hop budget (default 3, max 8). */
1623
+ maxDepth?: number;
1624
+ /** Language preferred for node titles (default `en`). */
1625
+ language?: Language;
1626
+ /**
1627
+ * Also follow national documents of live jurisdictions. BUSINESS+ only —
1628
+ * `403 TierForbiddenError` below that. `from`/`to` may themselves be
1629
+ * national ids (`AT-…`) regardless of this flag.
1630
+ */
1631
+ includeNational?: boolean;
748
1632
  }
749
- interface CitationPathResponse {
1633
+ interface CitationPathResponse extends CreditedResponse, WithResponseHeaders {
750
1634
  success: boolean;
751
1635
  from: string;
752
1636
  to: string;
@@ -759,15 +1643,26 @@ interface CitationPathResponse {
759
1643
  path: CitationPathNode[];
760
1644
  /** Present when `found` is false. */
761
1645
  message?: string;
1646
+ /** Whether national documents were followed (see `includeNational`). Absent while no national jurisdiction is live. */
1647
+ includeNational?: boolean;
762
1648
  }
763
- interface RelatedDocument {
1649
+ interface RelatedDocument extends CitationNode {
764
1650
  celexNumber: string;
765
1651
  title?: string | null;
1652
+ titleSource?: TitleSource;
766
1653
  /** Number of citation targets the related document shares with the seed. */
767
1654
  sharedCount: number;
768
1655
  sharedTargets?: string[];
769
1656
  }
770
- interface RelatedDocumentsResponse {
1657
+ interface RelatedDocumentsParams extends CitationFilterParams {
1658
+ /** Max neighbours (default 10, max 50). */
1659
+ limit?: number;
1660
+ /** Language preferred for titles (default `en`). */
1661
+ language?: Language;
1662
+ /** Also consider national documents of live jurisdictions. BUSINESS+ only — `403 TierForbiddenError` below that. */
1663
+ includeNational?: boolean;
1664
+ }
1665
+ interface RelatedDocumentsResponse extends CreditedResponse, WithResponseHeaders {
771
1666
  success: boolean;
772
1667
  celexNumber: string;
773
1668
  method: "bibliographic-coupling";
@@ -777,6 +1672,186 @@ interface RelatedDocumentsResponse {
777
1672
  related: RelatedDocument[];
778
1673
  /** Present when the seed has no outbound citations to couple on. */
779
1674
  message?: string;
1675
+ /** Whether national documents were considered (see `includeNational`). Absent while no national jurisdiction is live. */
1676
+ includeNational?: boolean;
1677
+ }
1678
+ /** Params for {@link getTransposition}. */
1679
+ interface TranspositionParams {
1680
+ /**
1681
+ * Countries to list, ISO-2 codes (`["es", "cz"]`; `EL` for Greece, `UK`
1682
+ * for the United Kingdom); default all 28. `eu` is accepted and ignored;
1683
+ * an unknown code is a `400`.
1684
+ */
1685
+ jurisdictions?: OneOrMany<string>;
1686
+ /**
1687
+ * `true`: only the measures resolved to a document LexAPI holds, in live
1688
+ * jurisdictions. Does nothing when holdings are not joined (below
1689
+ * BUSINESS, or `termsRequired`).
1690
+ */
1691
+ resolvedOnly?: boolean;
1692
+ /** Language of the act's title (default `en`). */
1693
+ language?: Language;
1694
+ }
1695
+ /**
1696
+ * One notified measure for an EU act (API 2.11.0) — the same keys for every
1697
+ * country; a field the record lacks is `null`. `id`, `resolved`,
1698
+ * `resolution` and `resolutionBasis` come from LexAPI's holdings: filled on
1699
+ * BUSINESS, SCALE and ENTERPRISE for a live jurisdiction, `null` otherwise.
1700
+ */
1701
+ interface TranspositionMeasure {
1702
+ /** The LexAPI id of the document the measure resolves to, when held and not withdrawn. */
1703
+ id: string | null;
1704
+ /** Whether the measure is matched to a document LexAPI holds; `null` when holdings are not joined. */
1705
+ resolved: boolean | null;
1706
+ resolution: CitationResolution | null;
1707
+ /** What the match used (e.g. the gazette number); `null` when not resolved or not joined. */
1708
+ resolutionBasis: {
1709
+ keyKind?: string;
1710
+ key?: string;
1711
+ } | null;
1712
+ /**
1713
+ * `cellar-nim` — the Cellar record of the member state's notification;
1714
+ * `source` — the national source itself records that the document
1715
+ * transposes or implements the act (`cellar` is then `null`).
1716
+ */
1717
+ provenance: "cellar-nim" | "source" | (string & {});
1718
+ /** `transposition` when Cellar types the act as a directive or framework decision, else `implementation`. */
1719
+ citationType: "transposition" | "implementation" | (string & {});
1720
+ /** The measure's title as notified, in the member state's language. */
1721
+ title: string | null;
1722
+ /** The kind of measure as notified (`Ley Orgánica`, `Zákon`, …). */
1723
+ typeAct: string | null;
1724
+ /** Where the measure was published, as notified. */
1725
+ officialJournal: {
1726
+ name?: string | null;
1727
+ number?: string | null;
1728
+ date?: string | null;
1729
+ };
1730
+ /** The member state's own reference for the measure. */
1731
+ reference: string | null;
1732
+ eli: string | null;
1733
+ /** A link to the measure, as notified. */
1734
+ link: string | null;
1735
+ /** The Cellar record of the notification; `null` on a measure only a national source records. */
1736
+ cellar: {
1737
+ id?: string | null;
1738
+ /** The record's sector-7 CELEX number for this act; `null` when it has none (never guessed). */
1739
+ celex?: string | null;
1740
+ /** Not mirrored — always `null`. */
1741
+ commissionReference?: null;
1742
+ dateDocument?: string | null;
1743
+ dateNotification?: string | null;
1744
+ entryIntoForce?: string | null;
1745
+ } | null;
1746
+ }
1747
+ /** One country's measures for the act. */
1748
+ interface TranspositionCountry {
1749
+ /** Upper-case code of the member state (`EL` for Greece), or `UK`. */
1750
+ jurisdiction: string;
1751
+ /** Whether LexAPI serves this country's national law (the same `live` as `getNationalCoverage`). */
1752
+ live: boolean;
1753
+ counts: {
1754
+ /** Measures for the act in this country (not only those in this page). */
1755
+ measures?: number;
1756
+ /** Of those, matched to a document LexAPI holds; `null` when holdings are not joined. */
1757
+ resolved?: number | null;
1758
+ };
1759
+ measures: TranspositionMeasure[];
1760
+ }
1761
+ /** `GET /citations/transposition/{celexNumber}` (API 2.11.0). */
1762
+ interface TranspositionResponse extends CreditedResponse, WithResponseHeaders {
1763
+ success: boolean;
1764
+ /** `true` when LexAPI's holdings are joined, `false` otherwise. Absent while no national jurisdiction is live. */
1765
+ includeNational?: boolean;
1766
+ /**
1767
+ * Present (`true`) only when holdings would be joined but the account has
1768
+ * not yet accepted the national-source terms: every holdings field is
1769
+ * then `null`. Accept the terms once in the dashboard.
1770
+ */
1771
+ termsRequired?: true;
1772
+ document: {
1773
+ id?: string;
1774
+ celexNumber?: string;
1775
+ jurisdiction?: "EU" | (string & {});
1776
+ documentKind?: "act" | (string & {});
1777
+ title?: string | null;
1778
+ };
1779
+ source: {
1780
+ cellar?: {
1781
+ /** When the newest of the act's records was last read from Cellar; `null` when the act has none. */
1782
+ syncedAt?: string | null;
1783
+ /** All the act's measures across every country (not narrowed by `jurisdictions`). */
1784
+ measures?: number;
1785
+ /** The attribution the Publications Office's reuse terms require — keep it with anything you republish. */
1786
+ attribution?: string;
1787
+ };
1788
+ /** The live jurisdictions whose own sources record a transposition or implementation of this act; `null` when holdings are not joined. */
1789
+ lanes?: string[] | null;
1790
+ };
1791
+ /**
1792
+ * Always: "Measures are those the member state notified to the Commission
1793
+ * for this act. A notification is not a finding that the measure
1794
+ * transposes the act, or transposes it completely."
1795
+ */
1796
+ note: string;
1797
+ /** Per country with at least one measure (in the `jurisdictions` asked for), in code order. */
1798
+ jurisdictions: TranspositionCountry[];
1799
+ /** `true` when more than 2,000 measures matched (narrow with `jurisdictions`), or the national-source edge cap was hit. */
1800
+ truncated: boolean;
1801
+ }
1802
+ /** Params for {@link getCounterparts}. */
1803
+ interface CounterpartsParams {
1804
+ /** 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`. */
1805
+ jurisdictions?: OneOrMany<string>;
1806
+ /** Language of the titles (default `en`). */
1807
+ language?: Language;
1808
+ }
1809
+ /** A measure of another live jurisdiction for the same EU act. */
1810
+ interface Counterpart {
1811
+ jurisdiction: string;
1812
+ /** The LexAPI id of the counterpart; `null` for a notified Cellar record LexAPI does not hold (rank 3). */
1813
+ id: string | null;
1814
+ resolved: boolean;
1815
+ title: string | null;
1816
+ citationType: "transposition" | "implementation" | (string & {});
1817
+ provenance: "source" | "cellar-nim" | (string & {});
1818
+ /**
1819
+ * `1` — the national source records the relation (`source`); `2` — a
1820
+ * notified measure LexAPI holds (`cellar-nim`, resolved); `3` — a notified
1821
+ * Cellar record LexAPI does not hold.
1822
+ */
1823
+ rank: 1 | 2 | 3;
1824
+ }
1825
+ /** One EU act the queried document transposes or implements, with the other jurisdictions' measures for it. */
1826
+ interface CounterpartVia {
1827
+ euAct: CitationNode & {
1828
+ title?: string | null;
1829
+ /** Measures all member states notified for the act. */
1830
+ notifiedMeasures?: number;
1831
+ };
1832
+ /** The document's own edge to the act; `null` when the queried id is the EU act itself. */
1833
+ edge: {
1834
+ citationType?: "transposition" | "implementation" | (string & {});
1835
+ provenance?: CitationProvenance | null;
1836
+ resolution?: CitationResolution | null;
1837
+ } | null;
1838
+ /** By `rank`, then jurisdiction; at most 200. Never the queried document. */
1839
+ counterparts: Counterpart[];
1840
+ /** `true` when more than 200 counterparts matched for this act. */
1841
+ truncated: boolean;
1842
+ }
1843
+ /** `GET /citations/counterparts/{id}` (API 2.11.0). */
1844
+ interface CounterpartsResponse extends CreditedResponse, WithResponseHeaders {
1845
+ success: boolean;
1846
+ /** Always `true` when present; absent while no national jurisdiction is live. */
1847
+ includeNational?: boolean;
1848
+ document: CitationNode & {
1849
+ title?: string | null;
1850
+ };
1851
+ /** One entry per EU act the document transposes or implements (CELEX order, at most 200); for an EU act as id, the act itself. */
1852
+ via: CounterpartVia[];
1853
+ /** `true` when the document implements more than 200 EU acts. */
1854
+ truncated: boolean;
780
1855
  }
781
1856
  /** Languages accepted by the semantic endpoints (narrower than `Language`). */
782
1857
  type SemanticLanguage = "en" | "fr" | "de" | "es" | "it" | "sl" | "el" | "nl" | "pt" | "pl";
@@ -787,7 +1862,7 @@ type SemanticLanguage = "en" | "fr" | "de" | "es" | "it" | "sl" | "el" | "nl" |
787
1862
  interface SemanticSearchOptions {
788
1863
  /** Natural-language query to embed. */
789
1864
  query: string;
790
- /** Max results. Clamped to the caller's tier ceiling. Default 10. */
1865
+ /** Max results. Clamped to the tier ceiling (legislation: never above 50). Default 10. */
791
1866
  limit?: number;
792
1867
  /**
793
1868
  * Drop results below this cosine similarity (wire: `min_score`).
@@ -796,11 +1871,11 @@ interface SemanticSearchOptions {
796
1871
  * to widen recall, `0` to disable the floor entirely.
797
1872
  */
798
1873
  minScore?: number;
799
- /** Language of returned content. Default `en`. */
1874
+ /** Language of returned content (a preference on legislation). Default `en`. */
800
1875
  language?: SemanticLanguage;
801
1876
  /**
802
- * Set `true` to receive the full document text in each hit (wire:
803
- * `include: ["text"]`). By default each hit carries a ~600-char snippet
1877
+ * Set `true` to receive the full text in each hit (wire:
1878
+ * `include: ["text"]`). By default each hit carries a ~600-char `snippet`
804
1879
  * instead — about a 10-50x payload reduction.
805
1880
  */
806
1881
  includeText?: boolean;
@@ -810,128 +1885,888 @@ interface SemanticSearchOptions {
810
1885
  /** Options for `semanticSearch` (case law) — adds HyDE query rewriting. */
811
1886
  interface SemanticCaseLawSearchOptions extends SemanticSearchOptions {
812
1887
  /**
813
- * Enable HyDE query rewriting (case-law endpoint only; ignored by
814
- * `/legislation/semantic`): an LLM drafts the passage a relevant
815
- * judgment would contain and retrieval fuses plain-query and
816
- * hypothetical-passage rankings. Markedly better recall on short or
817
- * keyword-style queries.
1888
+ * Enable HyDE query rewriting (case-law endpoint only): an LLM drafts the
1889
+ * passage a relevant judgment would contain and retrieval fuses
1890
+ * plain-query and hypothetical-passage rankings.
818
1891
  *
819
- * **Billing: 15 credits instead of 5**, and adds ~1–3 s of latency (one
820
- * LLM call). Best-effort: if generation fails the search transparently
821
- * falls back to plain retrieval, the response reports `hyde: false`,
822
- * and the 10-credit premium is **automatically refunded**
823
- * (`credits.operation_weight` reflects the base rate).
824
- *
825
- * Must be a JSON boolean — string values are rejected with 400.
1892
+ * **Billing: 15 credits instead of 5**, and adds ~1–3 s of latency.
1893
+ * Best-effort: if generation fails the search falls back to plain
1894
+ * retrieval, the response reports `hyde: false`, and the 10-credit
1895
+ * premium is **automatically refunded**.
826
1896
  */
827
1897
  hyde?: boolean;
828
1898
  }
829
- /** Single case-law match from `/search/semantic`. */
1899
+ /** Options for `semanticLegislationSearch` — adds point-in-time `asOf`. */
1900
+ interface SemanticLegislationSearchOptions extends SemanticSearchOptions {
1901
+ /**
1902
+ * Answer each hit with the version in force on this date (`YYYY-MM-DD`,
1903
+ * 1952-01-01 … today UTC): the act as published before its first
1904
+ * consolidation, otherwise the consolidated version in force on that
1905
+ * date. Omit for the latest version.
1906
+ *
1907
+ * **Billing:** 5 credits for the search; each live fetch of a version the
1908
+ * corpus does not hold reserves 5 just before it starts and settles by
1909
+ * outcome (Cellar 4, browser 5, no text 1, failed/timed out 0) — at most
1910
+ * `SEMANTIC_ASOF_MAX_FETCHES` (default 3) per request. A fetch the pool
1911
+ * cannot cover is skipped (`asOfReason: "insufficient_credits"`). An
1912
+ * invalid `asOf` is a 400 (refunded in full).
1913
+ */
1914
+ asOf?: string;
1915
+ }
1916
+ /** Single case-law match from `/search/semantic`. */
830
1917
  interface SemanticCaseLawResult {
831
1918
  /**
832
- * Snapshot-scoped UUID — regenerated when the upstream index is rebuilt.
1919
+ * Snapshot-scoped id — regenerated when the upstream index is rebuilt.
833
1920
  * Do NOT store as a long-term identifier; use
834
1921
  * `(metadata.celex_id, metadata.document_type)` for persistent joins.
835
1922
  */
836
1923
  case_id?: string | null;
837
1924
  /** Cosine similarity, 0–1. */
838
1925
  score?: number;
839
- /** Matching passage; replaced with the full document text when a parsed copy is available. */
1926
+ /** Full matched-document text — present ONLY with `includeText: true`. */
840
1927
  text?: string;
1928
+ /** ~600-character preview — present by default (replaced by `text` with `includeText`). */
1929
+ snippet?: string;
841
1930
  case_name?: string | null;
842
1931
  case_number?: string | null;
843
1932
  ecli?: string | null;
844
1933
  court?: string | null;
1934
+ parties?: string | null;
1935
+ /** LLM-generated digest of the ruling. */
1936
+ summary?: string | null;
1937
+ decision_date?: string | null;
1938
+ jurisdiction?: string | null;
1939
+ language?: string | null;
1940
+ /**
1941
+ * Structured analytics — present ONLY where the upstream extractor was
1942
+ * confident; omitted otherwise (never `null`).
1943
+ */
1944
+ outcome?: string;
1945
+ outcome_detail?: string;
1946
+ party_role?: string;
1947
+ claimed_amount?: number;
1948
+ awarded_amount?: number;
1949
+ currency?: string;
1950
+ award_percentage?: number;
1951
+ legal_area?: string | string[];
1952
+ legislation_cited?: string[];
1953
+ duration_days?: number;
1954
+ was_appealed?: boolean;
1955
+ appeal_outcome?: string;
1956
+ extraction_confidence?: number;
1957
+ extraction_model?: string;
1958
+ extracted_at?: string;
845
1959
  /** Always includes `celex_id` when available — the persistent identity key. */
846
1960
  metadata?: {
847
1961
  celex_id?: string;
848
1962
  document_type?: string | null;
1963
+ /** Position of the match within the judgment, when available. */
1964
+ paragraph_number?: number;
849
1965
  [key: string]: unknown;
850
1966
  };
1967
+ [key: string]: unknown;
851
1968
  }
852
1969
  /** Semantic-specific quota counters (legacy daily-call plans only). */
853
1970
  interface SemanticUsageInfo {
854
1971
  current?: number;
855
1972
  limit?: number;
856
1973
  remaining?: number;
1974
+ /** Semantic-quota units this call consumed (always 1). */
1975
+ unitsCharged?: number;
857
1976
  }
858
- interface SemanticCaseLawSearchResponse {
1977
+ interface SemanticCaseLawSearchResponse extends CreditedResponse, WithResponseHeaders {
859
1978
  success: boolean;
860
1979
  searchType?: "semantic-case-law";
861
1980
  query?: string;
862
1981
  resultCount?: number;
863
1982
  results: SemanticCaseLawResult[];
864
1983
  /**
865
- * Present only on best-effort responses (low-confidence hits below your
866
- * `minScore`, or noise-floor fallback) — its presence is itself the
867
- * low-confidence signal. Omitted entirely (never `null`) otherwise.
1984
+ * Present only on best-effort responses (low-confidence hits) — its
1985
+ * presence is itself the low-confidence signal. Omitted (never `null`) otherwise.
868
1986
  */
869
1987
  hint?: string;
870
1988
  /**
871
- * Present only when the request set `hyde: true`. Reports whether HyDE
872
- * rewriting actually ran; `false` means generation failed, the search
873
- * fell back to plain retrieval, and the 10-credit premium was refunded.
1989
+ * Present only when the request set `hyde: true`. `false` means generation
1990
+ * failed, the search fell back to plain retrieval, and the 10-credit
1991
+ * premium was refunded.
874
1992
  */
875
1993
  hyde?: boolean;
876
- /**
877
- * Present only when HyDE ran (`hyde: true` in the response): the
878
- * LLM-drafted hypothetical judgment passage whose embedding was fused
879
- * into retrieval — useful for debugging why results matched.
880
- */
1994
+ /** Present only when HyDE ran: the LLM-drafted hypothetical judgment passage. */
881
1995
  hypotheticalDocument?: string;
882
1996
  /** Opaque upstream pass-through; shape not stable — use `tookMs` for timing. */
883
1997
  metadata?: Record<string, unknown>;
884
1998
  /** Server-measured wall-clock time for this request, in ms. */
885
1999
  tookMs?: number;
2000
+ /** Legacy daily-call plans only. */
886
2001
  semanticUsage?: SemanticUsageInfo;
887
- subscription?: SubscriptionInfo & {
888
- maxResults?: number;
889
- };
890
- usage?: UsageInfo;
891
- credits?: CreditsInfo;
2002
+ }
2003
+ /**
2004
+ * Why an `asOf` hit could not be answered for that date; the hit then keeps
2005
+ * its latest text (`asOfResolved: false`). Never silently wrong text.
2006
+ *
2007
+ * - `not_yet_adopted` — `asOf` is before the date of the act.
2008
+ * - `not_yet_in_force` — the act existed but had not yet entered into force.
2009
+ * - `no_longer_in_force` — `asOf` is after the act's end of validity.
2010
+ * - `in_force_dates_unknown` — the act's in-force dates could not be established.
2011
+ * - `not_in_language` — the version in force has no text in that language.
2012
+ * - `text_unavailable` — the version in force has no text.
2013
+ * - `article_not_in_version` — that article/annex/recital does not exist in the version in force.
2014
+ * - `part_not_resolvable` — the match is a part that cannot be looked up by date (e.g. a table).
2015
+ * - `article_unknown` — the hit has no article identity.
2016
+ * - `version_list_unavailable` — the list of consolidated versions could not be read.
2017
+ * - `version_lookup_cap` — too many version-list lookups (per request, or per account per minute).
2018
+ * - `fetch_budget_exhausted` — this request's live-fetch limit was reached.
2019
+ * - `fetch_pending` — that version is already being fetched; ask again shortly.
2020
+ * - `fetch_capacity` — too many live fetches in flight; ask again shortly.
2021
+ * - `fetch_failed` / `fetch_timeout` — the live fetch failed or ran out of time.
2022
+ * - `request_deadline` — the request ran out of time.
2023
+ * - `insufficient_credits` — the credit pool could not cover that fetch.
2024
+ * - `credit_check_failed` — the credit check did not answer; no fetch was made.
2025
+ */
2026
+ 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 & {});
2027
+ /** Every documented {@link AsOfReason} value, in spec order (runtime list). */
2028
+ 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"];
2029
+ /** The version an `asOf` hit's text comes from. */
2030
+ interface AsOfVersion {
2031
+ celex?: string;
2032
+ /** Consolidation date; `null` for the act as published. */
2033
+ date?: string | null;
2034
+ kind?: "consolidated" | "as_published" | (string & {});
892
2035
  }
893
2036
  /** Single article-level match from `/legislation/semantic`. */
894
2037
  interface SemanticLegislationResult {
895
- /** Cosine similarity, 0–1. */
2038
+ /** Index hit id (snapshot-scoped; `asof:<celex>:<ref>` when `asOf` swapped the text). */
2039
+ id?: string;
2040
+ /** Cosine similarity, 0–1 (of the indexed text — see `matchedVersion`). */
896
2041
  score?: number;
897
- /** Matching article text from the embedding index. */
2042
+ /** Full article text — present ONLY with `includeText: true`. */
898
2043
  text?: string;
899
- /** Article identifier (e.g. `Article 17`). */
2044
+ /** Compact preview of the matched text — present by default. */
2045
+ snippet?: string;
2046
+ /** Article identifier (e.g. `art_17`) — usable as `articleId` on `getDocument`. */
900
2047
  article_ref?: string | null;
901
2048
  /** CELEX identifier of the parent legal act. */
902
2049
  law_id?: string | null;
903
2050
  law_title?: string | null;
2051
+ /** Language of the matched text (the request's `language` is a preference). */
2052
+ language?: string;
2053
+ section?: string | null;
2054
+ chapter?: string | null;
2055
+ exact_match_law_id?: boolean;
2056
+ /** `true` on a consolidated text; absent otherwise. */
2057
+ consolidated?: boolean;
2058
+ /** Consolidated texts only — the consolidation date (`YYYY-MM-DD`). */
2059
+ consolidatedAsOf?: string;
2060
+ /** Consolidated texts only — the act this text consolidates; cite it as the authentic source. */
2061
+ baseCelex?: string;
2062
+ /**
2063
+ * Consolidated texts only — "The act as amended, consolidated as of
2064
+ * <date>; not the authentic text. …" Only the Official Journal text is authentic.
2065
+ */
2066
+ consolidatedNote?: string;
2067
+ /** Present when the act as published matched the same article; its own match. */
2068
+ baseAct?: {
2069
+ law_id?: string;
2070
+ article_ref?: string | null;
2071
+ score?: number | null;
2072
+ };
2073
+ /** `asOf` requests only — echo of the request's `asOf`. */
2074
+ asOf?: string;
2075
+ /** `asOf` requests only — whether this hit carries the text in force on `asOf`. */
2076
+ asOfResolved?: boolean;
2077
+ /** Why `asOfResolved` is false; the hit then keeps its latest text. */
2078
+ asOfReason?: AsOfReason;
2079
+ /** `asOf` requests only — the version this hit's text comes from. */
2080
+ asOfVersion?: AsOfVersion;
2081
+ /**
2082
+ * Present when `asOf` swapped the text — the version the index matched
2083
+ * (`score` is its similarity, not the in-force text's).
2084
+ */
2085
+ matchedVersion?: {
2086
+ id?: string | null;
2087
+ law_id?: string;
2088
+ consolidatedAsOf?: string | null;
2089
+ };
904
2090
  metadata?: Record<string, unknown>;
2091
+ [key: string]: unknown;
905
2092
  }
906
- interface SemanticLegislationSearchResponse {
2093
+ interface SemanticLegislationSearchResponse extends CreditedResponse, WithResponseHeaders {
907
2094
  success: boolean;
908
2095
  searchType?: "semantic-legislation";
909
2096
  query?: string;
910
2097
  resultCount?: number;
911
2098
  results: SemanticLegislationResult[];
2099
+ /** `asOf` requests only — echo of the request's `asOf`. */
2100
+ asOf?: string;
2101
+ /** `asOf` requests only. */
2102
+ asOfSummary?: {
2103
+ /** Live fetches attempted, including failed and timed-out ones (those cost 0). */
2104
+ liveFetches?: number;
2105
+ /** Hits returned with `asOfResolved: false`. */
2106
+ unresolved?: number;
2107
+ };
912
2108
  /** Present only on best-effort responses — see `SemanticCaseLawSearchResponse.hint`. */
913
2109
  hint?: string;
914
2110
  /** Opaque upstream pass-through; shape not stable — use `tookMs` for timing. */
915
2111
  metadata?: Record<string, unknown>;
916
2112
  tookMs?: number;
2113
+ /** Legacy daily-call plans only. */
917
2114
  semanticUsage?: SemanticUsageInfo;
918
- subscription?: SubscriptionInfo & {
2115
+ }
2116
+ /** Availability block shared by `legislation` and `caseLaw` on a coverage entry. */
2117
+ interface NationalCoverageAvailability {
2118
+ available: boolean;
2119
+ description?: string;
2120
+ /** Approximate document count. `null` whenever `available` is false (incl. every jurisdiction still in preparation). */
2121
+ documents?: number | null;
2122
+ /** Earliest year covered, as an integer. `null` when unknown — today, always `null` for `legislation`. */
2123
+ from?: number | null;
2124
+ }
2125
+ /** `caseLaw` adds the courts covered. */
2126
+ interface NationalCaseLawCoverageAvailability extends NationalCoverageAvailability {
2127
+ courts?: string[];
2128
+ }
2129
+ /** Whether semantic search is indexed for this jurisdiction, per domain. */
2130
+ interface NationalSemanticSearchAvailability {
2131
+ legislation: boolean;
2132
+ caseLaw: boolean;
2133
+ }
2134
+ /** One upstream data source a jurisdiction's corpus is built from. */
2135
+ interface NationalSource {
2136
+ name: string;
2137
+ url: string;
2138
+ licence: string;
2139
+ attribution: string;
2140
+ }
2141
+ /**
2142
+ * Reason a citation-graph rate is not measured (API 2.13.0):
2143
+ * `not-collected` — LexAPI does not hold these references for the documents
2144
+ * it already has; `source-empty` — the source leaves the field empty or
2145
+ * absent on every document LexAPI holds.
2146
+ */
2147
+ type NationalCitationGraphUnmeasuredReason = "not-collected" | "source-empty" | (string & {});
2148
+ /** A citation-graph rate key, as used by `methods.unmeasured` and `floors`. */
2149
+ type NationalCitationGraphRateKey = "decisionsToActs" | "actsToEu" | "textPattern";
2150
+ /** What a jurisdiction's citation extraction does. */
2151
+ interface NationalCitationGraphMethods {
2152
+ /** How court decisions' references to acts are resolved. */
2153
+ decisions?: CitationResolution | null;
2154
+ /** Resolution methods used for references to national acts. */
2155
+ acts?: string[];
2156
+ /** Resolution methods used for references to EU law. */
2157
+ eu?: string[];
2158
+ /**
2159
+ * API 2.13.0 — absent when every rate is measured; otherwise rate →
2160
+ * reason code for the rates the sources do not let LexAPI measure (such a
2161
+ * rate is `null` and carries no floor), e.g. `{ decisionsToActs: "not-collected" }`.
2162
+ */
2163
+ unmeasured?: Partial<Record<NationalCitationGraphRateKey, NationalCitationGraphUnmeasuredReason>>;
2164
+ }
2165
+ /** The labelled-sample check of one resolution method of the jurisdiction's own extraction. */
2166
+ interface NationalCitationGraphPrecision {
2167
+ resolver?: string | null;
2168
+ resolverVersion?: number | null;
2169
+ /** `source` or `resolver` (API 2.12.0). */
2170
+ provenance?: "source" | "resolver" | null;
2171
+ /** Edges checked by hand. */
2172
+ labelled?: number | null;
2173
+ /** Clopper-Pearson 95 % upper bound on the error rate; `null` with no labels. */
2174
+ errorUpperBound?: number | null;
2175
+ }
2176
+ /**
2177
+ * API 2.12.0 — the lowest values the rates are expected to stay at (each the
2178
+ * measured value minus 10 percentage points, never below 0, at a dated
2179
+ * measurement). A rate that does not apply, is unmeasured, or was not
2180
+ * measured when the floors were set is `null`.
2181
+ */
2182
+ interface NationalCitationGraphFloors {
2183
+ /** Floor of `decisionResolutionRate`. */
2184
+ decisionsToActs?: number | null;
2185
+ /** Floor of `actEuRate`. */
2186
+ actsToEu?: number | null;
2187
+ /** Floor of `textPatternRate`. */
2188
+ textPattern?: number | null;
2189
+ /** Floor of `nimResolvedRate`. */
2190
+ nimResolved?: number | null;
2191
+ /** When the floors were set. */
2192
+ derivedAt?: string;
2193
+ /** The measurements the floors were taken from. */
2194
+ measuredAt?: {
2195
+ rebuild?: string | null;
2196
+ nim?: string | null;
2197
+ };
2198
+ }
2199
+ /**
2200
+ * A jurisdiction's citation graph, as measured (API 2.11.0). Nothing is
2201
+ * estimated: a value that was not measured is `null`.
2202
+ */
2203
+ interface NationalCitationGraph {
2204
+ methods?: NationalCitationGraphMethods | null;
2205
+ /** Edges whose citing document is in this jurisdiction and whose cited document is EU law or in a live jurisdiction. */
2206
+ edges?: number;
2207
+ /** Share of decisions with at least one structured reference that got an edge; `null` when not measured. */
2208
+ decisionResolutionRate?: number | null;
2209
+ /** Share of acts with recorded EU references that got an EU edge; `null` when not measured, and for a text-pattern-only jurisdiction. */
2210
+ actEuRate?: number | null;
2211
+ /** API 2.12.0. Share of EU act numbers found in running text that produced an edge; `null` when not measured. */
2212
+ textPatternRate?: number | null;
2213
+ /** The measures this member state notified to the Commission that Cellar still lists, and how many LexAPI holds. */
2214
+ transposition?: {
2215
+ measures?: number;
2216
+ resolved?: number;
2217
+ };
2218
+ precision?: NationalCitationGraphPrecision;
2219
+ /** When the rebuild rates were measured; `null` without. */
2220
+ measuredAt?: string | null;
2221
+ /** 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. */
2222
+ nimResolvedRate?: number | null;
2223
+ /** API 2.12.0. When that matching run finished. */
2224
+ nimMeasuredAt?: string | null;
2225
+ /** API 2.12.0. `null` until LexAPI has set them. */
2226
+ floors?: NationalCitationGraphFloors | null;
2227
+ }
2228
+ /** One jurisdiction's entry on `GET /national/coverage`. */
2229
+ interface NationalJurisdictionCoverage {
2230
+ /** ISO 3166-1 alpha-2, e.g. `"AT"`. Non-EU legal orders (e.g. `"UK"`) are included too. */
2231
+ code: string;
2232
+ name: string;
2233
+ /** Whether customers can call this jurisdiction's endpoints today. */
2234
+ live: boolean;
2235
+ /** `null` before launch. */
2236
+ launchedAt?: string | null;
2237
+ legislation: NationalCoverageAvailability;
2238
+ caseLaw: NationalCaseLawCoverageAvailability;
2239
+ semanticSearch: NationalSemanticSearchAvailability;
2240
+ sources: NationalSource[];
2241
+ /** When this jurisdiction's corpus was last synced. `null` if never. */
2242
+ lastSyncAt?: string | null;
2243
+ /** 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. */
2244
+ citationGraph?: NationalCitationGraph | null;
2245
+ }
2246
+ /**
2247
+ * `GET /national/coverage` — public, free, no API key or allowance headers
2248
+ * required. Call this before `getNationalDocument` / `listNationalDocuments`
2249
+ * / `nationalSemanticSearch` / `nationalLegislationSemanticSearch` to check
2250
+ * whether a jurisdiction is live, so a 404 is never a surprise.
2251
+ */
2252
+ interface NationalCoverageResponse extends WithResponseHeaders {
2253
+ updatedAt: string;
2254
+ jurisdictions: NationalJurisdictionCoverage[];
2255
+ }
2256
+ /** Known `NationalTextBasis.basis` wire values (snake_case). Open for forward compatibility. */
2257
+ type NationalTextBasisKind = "as_announced" | "official_consolidated" | "official_consolidated_superseded" | "none" | (string & {});
2258
+ /**
2259
+ * `NationalDocument.textBasis` — which text a source says it publishes
2260
+ * (e.g. Poland). `null` (since API 2.8.0, no longer absent) for every
2261
+ * source that does not say.
2262
+ */
2263
+ interface NationalTextBasis {
2264
+ basis: NationalTextBasisKind;
2265
+ /** The date the text speaks for (never "valid until"). */
2266
+ asOf?: string;
2267
+ newerConsolidationExists?: boolean;
2268
+ newestPdfOnlyDate?: string;
2269
+ newerPdfOnly?: string[];
2270
+ amendedSince?: boolean;
2271
+ /** ELI of the act this text was consolidated from, when applicable. */
2272
+ textFrom?: string;
2273
+ }
2274
+ /**
2275
+ * What a national document is, in one vocabulary for every jurisdiction
2276
+ * (API 2.8.0): `"act"` (legislation) or `"decision"` (case law). Use it —
2277
+ * not `documentType`, the source's own label — to tell them apart.
2278
+ */
2279
+ type NationalDocumentKind = "act" | "decision";
2280
+ /**
2281
+ * A national document's metadata, as the listing returns it — the same
2282
+ * fields, types and formats for every jurisdiction (API 2.8.0). Every field
2283
+ * is always present; one the source does not provide is `null`, never
2284
+ * absent.
2285
+ */
2286
+ interface NationalDocumentSummary {
2287
+ /** The national corpus id (e.g. `"AT-NOR-12345"`), analogous to a CELEX number. */
2288
+ id: string;
2289
+ /** ISO 3166-1 alpha-2 jurisdiction code. */
2290
+ jurisdiction: string;
2291
+ /** ISO 639-1 code of the source language. */
2292
+ language: string;
2293
+ /**
2294
+ * `"act"` | `"decision"` — see {@link NationalDocumentKind}. `null` only
2295
+ * for an id that matches no collection LexAPI knows for the jurisdiction.
2296
+ */
2297
+ documentKind: NationalDocumentKind | null;
2298
+ title: string | null;
2299
+ /**
2300
+ * The source's own type label, in its language (`"Bundesgesetz (konsolidiert)"`,
2301
+ * `"Uitspraak (NL)"`) — different in every jurisdiction. Use `documentKind`
2302
+ * for act / decision.
2303
+ */
2304
+ documentType: string | null;
2305
+ /** The decision's ECLI. `null` for acts and where the source gives none. */
2306
+ ecli: string | null;
2307
+ /** The act's ELI (a URI). `null` where the source gives none. */
2308
+ eli: string | null;
2309
+ /** The document's own date, `YYYY-MM-DD`; `null` when the source gives none. */
2310
+ dateOfDocument: string | null;
2311
+ /** LexAPI's version counter for this document (bumped when its text changes). */
2312
+ version: number;
2313
+ /** When LexAPI last stored real content for it (ISO 8601). */
2314
+ fetchedAt: string;
2315
+ /**
2316
+ * Last day in force (`YYYY-MM-DD`), set once the source confirmed the act
2317
+ * is no longer in force. `null` when there is no known end (an act in
2318
+ * force, case law, a source that does not record repeals).
2319
+ */
2320
+ validTo: string | null;
2321
+ /** `false` once `validTo` has passed (UTC), `true` while it is today or later; `null` when `validTo` is `null`. */
2322
+ inForce: boolean | null;
2323
+ }
2324
+ /** Legislation a decision cites — {@link NationalDecision.citedNorms}. */
2325
+ interface NationalCitedNorm {
2326
+ /** The source's citation string (`"§ 62 Abs 1a S 3 EStG 2009"`, `"§ 7 177/1996 Sb."`). */
2327
+ text: string;
2328
+ /**
2329
+ * LexAPI id of the cited act when the source identifies it (CZ, SI, PL,
2330
+ * SE) — whether or not LexAPI holds that act; `null` otherwise.
2331
+ */
2332
+ documentId: string | null;
2333
+ }
2334
+ /**
2335
+ * A decision's case-law metadata (`documentKind: "decision"`). Values are
2336
+ * the source's own (local language and spelling); the field set and types
2337
+ * are the same in every jurisdiction — the server reads them from whichever
2338
+ * field the source uses (Austria's `gericht`, Germany's `aktenzeichen`, …),
2339
+ * so read these, never the raw source keys under `content.details`.
2340
+ */
2341
+ interface NationalDecision {
2342
+ /** The deciding court as the source names it (`"OGH"`, `"BFH 3. Senat"`, `"Gerechtshof Amsterdam"`). */
2343
+ court: string | null;
2344
+ /**
2345
+ * The chamber, section or department, where the source names it apart
2346
+ * from the court (`"Sección Cuarta"`, `"Civilni oddelek"`). `null`
2347
+ * otherwise (Austria and Germany name the panel inside `court`).
2348
+ */
2349
+ chamber: string | null;
2350
+ /** The case (docket) numbers as the source writes them (`["III R 27/24"]`); `[]` when none. */
2351
+ caseNumbers: string[];
2352
+ /** Legislation the decision cites, where the source lists it; `[]` otherwise. */
2353
+ citedNorms: NationalCitedNorm[];
2354
+ }
2355
+ /** One unit of an act (article, section, annex) — the same fields in every jurisdiction. */
2356
+ interface NationalArticle {
2357
+ /** The source's own label (`"§ 1"`, `"Art. 1"`, `"1 kap. 1 §"`); `null` for an unnumbered unit. */
2358
+ number: string | null;
2359
+ /** The unit's heading. */
2360
+ title: string | null;
2361
+ /** The part or chapter it sits in (`"Kapitel 1 — …"`, `"1 luku"`). */
2362
+ section: string | null;
2363
+ /** The unit's text; `null` when the source has no text for it — never an empty provision. */
2364
+ text: string | null;
2365
+ /** The unit's own validity start (`YYYY-MM-DD`), where the source dates units (AT, ES, FR). */
2366
+ inForceFrom: string | null;
2367
+ inForceTo: string | null;
2368
+ /** The source's other unit fields (unit ids, kinds, notes). Source-specific. */
2369
+ details: Record<string, unknown>;
2370
+ }
2371
+ /** `content.repeal` — the source's confirmation behind `validTo`. */
2372
+ interface NationalRepeal {
2373
+ /** Last day in force (`YYYY-MM-DD`). */
2374
+ validTo: string | null;
2375
+ /** What the source says, in its words. */
2376
+ basis: string | null;
2377
+ /** When LexAPI recorded it. */
2378
+ detectedAt: string | null;
2379
+ }
2380
+ /**
2381
+ * The parsed text of a national document — a closed key set, the same in
2382
+ * every jurisdiction (API 2.8.0). What a source adds beyond these keys is
2383
+ * under `source` (provenance) and `details`, both source-specific.
2384
+ */
2385
+ interface NationalDocumentContent {
2386
+ fullText: string;
2387
+ /** The act's units in order. `[]` for decisions and for acts the source publishes without units. */
2388
+ articles: NationalArticle[];
2389
+ /**
2390
+ * The languages the text is in (ISO 639-1). Dutch treaties (`NL-BWBV…`):
2391
+ * the languages BWB publishes the treaty in, in order (`["en", "nl"]`);
2392
+ * otherwise the one language of the text.
2393
+ */
2394
+ textLanguages: string[];
2395
+ /** Set when the whole text is in one language other than the document's `language`; else `null`. */
2396
+ textLanguage: string | null;
2397
+ /** `true` when the text includes text in a language other than the document's `language`. */
2398
+ embeddedForeignText: boolean;
2399
+ /**
2400
+ * Where the text was read from (API 2.9.0): `html` (the source's web
2401
+ * rendition), `pdf-text` (the text layer of the source's PDF) or `ocr`
2402
+ * (machine-read from a scanned page — see `ocr`). `null` for jurisdictions
2403
+ * that do not label it. Treat unknown values as additive.
2404
+ */
2405
+ textSource: NationalTextSource | null;
2406
+ /** `null` unless `textSource` is `ocr` (API 2.9.0). OCR text may contain recognition errors and is never the official text. */
2407
+ ocr: NationalOcrInfo | null;
2408
+ /** The source's confirmation that the act is no longer in force (the basis of `validTo`); `null` otherwise. */
2409
+ repeal: NationalRepeal | null;
2410
+ /** Provenance from the upstream (system, its ids and URLs). Keys vary by jurisdiction. */
2411
+ source: Record<string, unknown>;
2412
+ /** Everything else the source provides, under its own field names. Keys vary by jurisdiction. */
2413
+ details: Record<string, unknown>;
2414
+ }
2415
+ /** Known `NationalDocumentContent.textSource` values. Open for forward compatibility. */
2416
+ type NationalTextSource = "html" | "pdf-text" | "ocr" | (string & {});
2417
+ /** How an OCR'd national text was recognised (API 2.9.0). */
2418
+ interface NationalOcrInfo {
2419
+ engine: string | null;
2420
+ engineVersion: string | null;
2421
+ /** The version of the engine's recognition core. */
2422
+ coreVersion: string | null;
2423
+ /** The recognition model used. */
2424
+ traineddata: string | null;
2425
+ /** Recognition confidence, 0–100, averaged over the recognised characters. */
2426
+ confidence: number | null;
2427
+ /** The lowest page's confidence, 0–100. */
2428
+ minPageConfidence: number | null;
2429
+ /** The PDF pages read by OCR. */
2430
+ pages: number[];
2431
+ /** Pages of the same document read from the PDF's text layer. */
2432
+ textLayerPages: number[];
2433
+ /** Human-readable statement that the text is machine-read and not the official text. */
2434
+ notice: string;
2435
+ }
2436
+ /** Full national document — `GET /{jurisdiction}/documents/{id}` (API 2.8.0 shape). */
2437
+ interface NationalDocument extends NationalDocumentSummary {
2438
+ /**
2439
+ * Case-law metadata when `documentKind` is `"decision"` (served also when
2440
+ * the decision has no text); `null` for acts. See {@link isNationalDecision}.
2441
+ */
2442
+ decision: NationalDecision | null;
2443
+ /** `null` when the jurisdiction's source publishes no text for this id — check `textAvailability`. */
2444
+ content: NationalDocumentContent | null;
2445
+ textAvailability: TextAvailability;
2446
+ /** The jurisdiction's source attribution — always show this to users alongside the text. */
2447
+ attribution: string;
2448
+ /** Only from sources that say which text they publish (e.g. Poland); `null` for every other source. */
2449
+ textBasis: NationalTextBasis | null;
2450
+ }
2451
+ /** A {@link NationalDocument} narrowed to a decision (`decision` is non-null). */
2452
+ type NationalDecisionDocument = NationalDocument & {
2453
+ documentKind: "decision";
2454
+ decision: NationalDecision;
2455
+ };
2456
+ /**
2457
+ * Narrow a national document to a decision: `documentKind === "decision"`
2458
+ * with its `decision` block. Works the same for every jurisdiction.
2459
+ */
2460
+ declare function isNationalDecision(document: NationalDocument): document is NationalDecisionDocument;
2461
+ /**
2462
+ * `GET /{jurisdiction}/documents/{id}`. No `success` field (unlike the EU
2463
+ * document endpoints). Credit cost: every national read is a corpus read
2464
+ * (there is no live-fetch fallback) — reserved at the `document_fetch`
2465
+ * weight (5) and settled to the corpus-hit weight (1).
2466
+ */
2467
+ interface NationalDocumentResponse extends CreditedResponse, WithResponseHeaders {
2468
+ document: NationalDocument;
2469
+ }
2470
+ interface NationalDocumentListParams {
2471
+ /**
2472
+ * 1-based page, within the first `LISTING_MAX_OFFSET` (1,000) rows only —
2473
+ * `(page - 1) * limit >= 1000` is a 400 `InvalidParamsError`. Mutually
2474
+ * exclusive with `cursor`; omit both for page 1. Beyond the first 1,000
2475
+ * rows, page through with `cursor` (each response's `nextCursor`) instead.
2476
+ */
2477
+ page?: number;
2478
+ /**
2479
+ * Opaque keyset cursor from a previous response's `nextCursor`. Works at
2480
+ * any depth (unlike `page`, which only reaches the first 1,000 rows). An
2481
+ * invalid cursor is a 400.
2482
+ */
2483
+ cursor?: string;
2484
+ /** Default 20, max 100. */
2485
+ limit?: number;
2486
+ /** Case-insensitive title search, 3–200 characters (Unicode code points). */
2487
+ q?: string;
2488
+ /** Case-insensitive substring match on `documentType` (wire param: `type`), at most 200 characters. */
2489
+ documentType?: string;
2490
+ /** Repealed acts are hidden by default; `true` includes them. */
2491
+ includeRepealed?: boolean;
2492
+ }
2493
+ /**
2494
+ * `GET /{jurisdiction}/documents`. No `success` field. 3 credits per call
2495
+ * (flat — pagination does not multiply the price, unlike `search`).
2496
+ *
2497
+ * Results are newest-first by the document's own date (undated rows last),
2498
+ * then by id — a total order, so pages never repeat or skip a row even
2499
+ * while the corpus keeps changing underneath the walk.
2500
+ */
2501
+ interface NationalDocumentListResponse extends CreditedResponse, WithResponseHeaders {
2502
+ jurisdiction: string;
2503
+ /** Matching rows, counted up to 10,000 — see `totalExact`. */
2504
+ total: number;
2505
+ /** `false` when `total` is a lower bound (more than 10,000 rows matched, or the count timed out). */
2506
+ totalExact: boolean;
2507
+ /** Present only when the request paged with `page` (absent in cursor mode). */
2508
+ page?: number;
2509
+ limit: number;
2510
+ includeRepealed: boolean;
2511
+ /** `true` when another page follows — page with `nextCursor`. */
2512
+ hasMore: boolean;
2513
+ /** Opaque cursor for the next page (via `cursor`), or `null` on the last page. */
2514
+ nextCursor: string | null;
2515
+ results: NationalDocumentSummary[];
2516
+ }
2517
+ /**
2518
+ * Filters honoured by `POST /{jurisdiction}/search/semantic` — deliberately
2519
+ * an EXACT interface (no index signature): the server 400s any unsupported
2520
+ * key (`"Unsupported filter"`), so a typo here should be a compile error,
2521
+ * not a silent 400 at runtime. `jurisdiction` must equal the path's
2522
+ * jurisdiction, or be omitted.
2523
+ */
2524
+ interface NationalCaseLawFilters {
2525
+ court?: string;
2526
+ date_from?: string;
2527
+ date_to?: string;
2528
+ ecli?: string;
2529
+ language?: string;
2530
+ jurisdiction?: string;
2531
+ }
2532
+ /**
2533
+ * Filters honoured by `POST /{jurisdiction}/legislation/semantic` — exact,
2534
+ * like {@link NationalCaseLawFilters}. `law_id`/`in_force`/`law_type` are
2535
+ * the semantic index's own names, accepted as aliases.
2536
+ */
2537
+ interface NationalLegislationFilters {
2538
+ id?: string;
2539
+ law_id?: string;
2540
+ inForce?: boolean;
2541
+ in_force?: boolean;
2542
+ documentType?: string;
2543
+ law_type?: string;
2544
+ language?: string;
2545
+ jurisdiction?: string;
2546
+ }
2547
+ /**
2548
+ * Options for `nationalSemanticSearch`. `hyde` is accepted for API
2549
+ * compatibility but is always a no-op here: the national index never
2550
+ * rewrites, so the response reports `hyde: false` (never `true`) when the
2551
+ * request set it, and billing stays the flat 5 credits (no 15-credit tier).
2552
+ *
2553
+ * Deliberately NOT `extends SemanticSearchOptions`: `language` here is a
2554
+ * plain `string` (the jurisdiction's own language — anything else is a
2555
+ * 400), not the 10-code EU `SemanticLanguage` enum, and `filters` is the
2556
+ * exact {@link NationalCaseLawFilters} rather than a free-form record.
2557
+ */
2558
+ interface NationalSemanticCaseLawOptions {
2559
+ /** Natural-language query to embed. */
2560
+ query: string;
2561
+ /** Max results. Default 10. */
2562
+ limit?: number;
2563
+ /** Drop results below this cosine similarity (wire: `min_score`). */
2564
+ minScore?: number;
2565
+ /** Omit, or the jurisdiction's own language — any other value is a 400. */
2566
+ language?: string;
2567
+ /** Receive the full matched text per hit (wire: `include: ["text"]`) instead of a `snippet`. */
2568
+ includeText?: boolean;
2569
+ hyde?: boolean;
2570
+ filters?: NationalCaseLawFilters;
2571
+ }
2572
+ /**
2573
+ * Options for `nationalLegislationSemanticSearch`. No `hyde`, no `asOf` —
2574
+ * both are EU-only. See {@link NationalSemanticCaseLawOptions} for why this
2575
+ * does not extend `SemanticSearchOptions`.
2576
+ */
2577
+ interface NationalSemanticLegislationOptions {
2578
+ query: string;
2579
+ limit?: number;
2580
+ minScore?: number;
2581
+ /** Omit, or the jurisdiction's own language — any other value is a 400. */
2582
+ language?: string;
2583
+ includeText?: boolean;
2584
+ filters?: NationalLegislationFilters;
2585
+ }
2586
+ /**
2587
+ * Single hit from `nationalSemanticSearch`, same shape as
2588
+ * {@link SemanticCaseLawResult} (which index metadata fields are filled
2589
+ * depends on the national source) plus national fields. For metadata that
2590
+ * is the same in every jurisdiction, read `document` — the matched decision
2591
+ * as the listing returns it (API 2.8.0).
2592
+ */
2593
+ interface NationalSemanticCaseLawResult extends SemanticCaseLawResult {
2594
+ /** The national corpus id this hit resolved to (also mirrored into `metadata.celex_id`). */
2595
+ documentId: string;
2596
+ /** ISO 3166-1 alpha-2 jurisdiction code. */
2597
+ jurisdiction: string;
2598
+ /**
2599
+ * The matched decision as the listing returns it, from LexAPI's own
2600
+ * record — the same fields in every jurisdiction, whatever metadata the
2601
+ * index carries for it (API 2.8.0).
2602
+ */
2603
+ document: NationalDocumentSummary;
2604
+ /** When the source recorded an end of validity (also a future one). */
2605
+ validTo?: string;
2606
+ /** Only `false`, and only once `validTo` has passed. */
2607
+ inForce?: boolean;
2608
+ attribution: string;
2609
+ }
2610
+ /**
2611
+ * Single hit from `nationalLegislationSemanticSearch`, same shape as
2612
+ * {@link SemanticLegislationResult} plus national fields. Unlike the EU hit,
2613
+ * a national hit always carries `law_title`, `article_ref`, `section`,
2614
+ * `language`, `in_force`, `valid_from`, `valid_to` and `law_type` — `null`
2615
+ * when the index has nothing for the unit (API 2.8.0). NOTE: these index
2616
+ * fields are deliberately snake_case — that is what the server sends — do
2617
+ * not "fix" the casing without changing the server first. The act's
2618
+ * cross-jurisdiction metadata is under `document`.
2619
+ */
2620
+ interface NationalSemanticLegislationResult extends Omit<SemanticLegislationResult, "law_id" | "law_title" | "article_ref" | "section" | "language"> {
2621
+ /** LexAPI id of the act. */
2622
+ law_id: string;
2623
+ /** Same as `law_id`. */
2624
+ documentId: string;
2625
+ jurisdiction: string;
2626
+ law_title: string | null;
2627
+ /** The unit's label, as in `content.articles[].number` of the document. */
2628
+ article_ref: string | null;
2629
+ section: string | null;
2630
+ language: string | null;
2631
+ /**
2632
+ * From the index, as of today; `false` (with `valid_to`) when LexAPI
2633
+ * knows the act is repealed (LexAPI only ever overrides it toward
2634
+ * `false`); `null` when unknown.
2635
+ */
2636
+ in_force: boolean | null;
2637
+ /** The unit's validity start (`YYYY-MM-DD`), where the source dates units. */
2638
+ valid_from: string | null;
2639
+ valid_to: string | null;
2640
+ /** The index's type code of the act. */
2641
+ law_type: string | null;
2642
+ /** The matched act as the listing returns it, from LexAPI's own record (API 2.8.0). */
2643
+ document: NationalDocumentSummary;
2644
+ attribution: string;
2645
+ }
2646
+ /**
2647
+ * Why a national semantic search answer is incomplete. `SEARCH_INCOMPLETE`:
2648
+ * the national index could not complete the search.
2649
+ */
2650
+ type NationalSearchPartialReason = "SEARCH_INCOMPLETE" | (string & {});
2651
+ /**
2652
+ * `POST /{jurisdiction}/search/semantic` — national case-law semantic
2653
+ * search. `credits` is present on the body, like every other credit-metered
2654
+ * route, typed optional only via the shared `CreditedResponse` shape.
2655
+ */
2656
+ interface NationalSemanticCaseLawResponse extends CreditedResponse, WithResponseHeaders {
2657
+ success: boolean;
2658
+ searchType?: "semantic-case-law";
2659
+ jurisdiction?: string;
2660
+ query?: string;
2661
+ resultCount?: number;
2662
+ results: NationalSemanticCaseLawResult[];
2663
+ /** Present only when the request set `hyde: true` — always `false` (see {@link NationalSemanticCaseLawOptions}). */
2664
+ hyde?: boolean;
2665
+ metadata?: Record<string, unknown>;
2666
+ hint?: string;
2667
+ /**
2668
+ * Present (`true`) only when the national index could not complete the
2669
+ * search but some hits are left: the results may be missing better
2670
+ * matches. `hint` says what may complete it — a retry, or a rephrased
2671
+ * query / changed filters. When nothing is left to return the call fails
2672
+ * instead: `NationalSemanticUnavailableError` (503) or
2673
+ * `NationalSemanticFilterUnreachableError` (422).
2674
+ */
2675
+ partial?: true;
2676
+ /** Present with `partial`. */
2677
+ partialReason?: NationalSearchPartialReason;
2678
+ /** The jurisdiction's source attribution — always show this to users alongside results. */
2679
+ attribution?: string;
2680
+ tookMs?: number;
2681
+ semanticUsage?: SemanticUsageInfo;
2682
+ subscription?: {
2683
+ tier?: SubscriptionTier;
919
2684
  maxResults?: number;
920
2685
  };
921
- usage?: UsageInfo;
922
- credits?: CreditsInfo;
923
2686
  }
924
- /** Operational state. `FAILED` is set automatically after repeated delivery errors. */
2687
+ /** `POST /{jurisdiction}/legislation/semantic` — national legislation semantic search. */
2688
+ interface NationalSemanticLegislationResponse extends CreditedResponse, WithResponseHeaders {
2689
+ success: boolean;
2690
+ searchType?: "semantic-legislation";
2691
+ jurisdiction?: string;
2692
+ query?: string;
2693
+ resultCount?: number;
2694
+ results: NationalSemanticLegislationResult[];
2695
+ metadata?: Record<string, unknown>;
2696
+ hint?: string;
2697
+ /**
2698
+ * Present (`true`) only when the national index could not complete the
2699
+ * search but some hits are left: the results may be missing better
2700
+ * matches. `hint` says what may complete it — a retry, or a rephrased
2701
+ * query / changed filters. When nothing is left to return the call fails
2702
+ * instead: `NationalSemanticUnavailableError` (503) or
2703
+ * `NationalSemanticFilterUnreachableError` (422).
2704
+ */
2705
+ partial?: true;
2706
+ /** Present with `partial`. */
2707
+ partialReason?: NationalSearchPartialReason;
2708
+ attribution?: string;
2709
+ tookMs?: number;
2710
+ semanticUsage?: SemanticUsageInfo;
2711
+ subscription?: {
2712
+ tier?: SubscriptionTier;
2713
+ maxResults?: number;
2714
+ };
2715
+ }
2716
+ /** Operational state. `FAILED` is set automatically when one delivery fails all 7 attempts (~24 h). */
925
2717
  type WebhookStatus = "ACTIVE" | "PAUSED" | "FAILED";
926
2718
  type DeliveryStatus = "PENDING" | "SUCCESS" | "FAILED" | "RETRYING";
2719
+ /**
2720
+ * Filters for `documents.new`, in the /search vocabulary but matched against
2721
+ * document TITLES and metadata. Every filter given must match; `{}` matches
2722
+ * every new EU-law document (sectors 1–6), never consolidated texts. A
2723
+ * `subdomain` REPLACES that default (`"consolidated"` alone = consolidated
2724
+ * texts only). Unsupported filters (`procedure`, `textScope: "text"`,
2725
+ * `domain: "NATIONAL_LAW"`, boolean operators, unknown types/authors) are
2726
+ * refused with 400 and a `details` list.
2727
+ */
2728
+ interface WebhookCriteria {
2729
+ /**
2730
+ * Every term (or "quoted phrase") must match whole words of the title
2731
+ * (case/accent-insensitive; 4+ char terms match word starts; `tax*`
2732
+ * matches word starts at any length). `OR`/`NOT`/`NEAR`/`-term` are refused.
2733
+ */
2734
+ query?: string;
2735
+ /** Same values as /search; `regulation`/`directive`/`decision` match every sub-type. */
2736
+ documentType?: OneOrMany<DocumentType | (string & {})>;
2737
+ /**
2738
+ * Same values as /search (`commission`, `council`, `parliament`,
2739
+ * `court-of-justice`/`cjeu`/`ecj`/`court`, `general-court`,
2740
+ * `civil-service-tribunal`, `ecb`, `eca`, `eesc`, `cor`, `efsa`, or codes
2741
+ * like `COM`). `member-states` and `ema` are refused.
2742
+ */
2743
+ author?: OneOrMany<string>;
2744
+ /** Lower-case subdomain names: `treaties`, `international`, `legislation`, `preparatory`, `case-law`, `consolidated`. */
2745
+ subdomain?: OneOrMany<string>;
2746
+ /** Lower bound on the document date (`YYYY-MM-DD`). */
2747
+ dateFrom?: string;
2748
+ dateTo?: string;
2749
+ year?: number | number[];
2750
+ /** Accepted for compatibility — all match titles. */
2751
+ textScope?: "title" | "title-text" | "any";
2752
+ domain?: "EU_LAW" | "ALL";
2753
+ language?: string;
2754
+ }
927
2755
  /** Summary shape used in list responses. The `secret` is never included here. */
928
2756
  interface WebhookListItem {
929
2757
  id?: string;
930
2758
  name?: string;
931
2759
  url?: string;
932
2760
  status?: WebhookStatus;
933
- /** The saved search — same shape as a `/search` request body. */
934
- searchCriteria?: SearchRequest;
2761
+ searchCriteria?: WebhookCriteria | null;
2762
+ /**
2763
+ * What is wrong with the stored `searchCriteria`; empty when nothing is.
2764
+ * Non-empty only for criteria saved before a validation rule existed —
2765
+ * such criteria are skipped (never widened) until fixed with `update`.
2766
+ */
2767
+ criteriaErrors?: string[];
2768
+ /** Watched base-act CELEX numbers (`watchlist.changes`). */
2769
+ watchCelex?: string[];
935
2770
  lastChecked?: string | null;
936
2771
  lastTriggered?: string | null;
937
2772
  consecutiveFailures?: number;
@@ -942,6 +2777,8 @@ interface WebhookListItem {
942
2777
  /** A single delivery attempt. */
943
2778
  interface WebhookDelivery {
944
2779
  id?: string;
2780
+ /** Present on `recentDeliveries` (raw rows); not on `/deliveries` items. */
2781
+ webhookId?: string;
945
2782
  status?: DeliveryStatus;
946
2783
  /** The JSON payload that was POSTed (or queued) to the webhook URL. */
947
2784
  payload?: Record<string, unknown>;
@@ -954,6 +2791,16 @@ interface WebhookDelivery {
954
2791
  nextRetryAt?: string | null;
955
2792
  deliveredAt?: string | null;
956
2793
  createdAt?: string;
2794
+ [key: string]: unknown;
2795
+ }
2796
+ /** Delivery retry schedule reported on `GET /webhooks/{id}`. */
2797
+ interface WebhookRetryPolicy {
2798
+ /** e.g. 7 */
2799
+ maxAttempts?: number;
2800
+ /** e.g. 24 */
2801
+ windowHours?: number;
2802
+ /** e.g. `[1, 5, 30, 120, 360, 900]` */
2803
+ delaysMinutes?: number[];
957
2804
  }
958
2805
  /** Full webhook details (no `secret`). */
959
2806
  interface WebhookDetail {
@@ -961,21 +2808,26 @@ interface WebhookDetail {
961
2808
  name?: string;
962
2809
  url?: string;
963
2810
  status?: WebhookStatus;
964
- searchCriteria?: SearchRequest;
2811
+ searchCriteria?: WebhookCriteria | null;
2812
+ criteriaErrors?: string[];
2813
+ watchCelex?: string[];
965
2814
  lastChecked?: string | null;
966
2815
  lastTriggered?: string | null;
967
2816
  consecutiveFailures?: number;
2817
+ retryPolicy?: WebhookRetryPolicy;
2818
+ /** @deprecated No longer returned by the server — read `retryPolicy.maxAttempts`. */
968
2819
  maxRetries?: number;
969
2820
  createdAt?: string;
970
2821
  updatedAt?: string;
971
2822
  /** Up to 20 most recent delivery attempts, newest first. */
972
2823
  recentDeliveries?: WebhookDelivery[];
973
2824
  }
974
- interface WebhookListResponse {
2825
+ interface WebhookListResponse extends WithResponseHeaders {
975
2826
  success: boolean;
976
2827
  count?: number;
977
2828
  webhooks: WebhookListItem[];
978
2829
  }
2830
+ /** Needs `searchCriteria`, `watchCelex`, or both. */
979
2831
  interface WebhookCreateRequest {
980
2832
  /** User-friendly label for the webhook. */
981
2833
  name: string;
@@ -987,22 +2839,33 @@ interface WebhookCreateRequest {
987
2839
  * time it is exposed. Store it.
988
2840
  */
989
2841
  secret?: string;
990
- /** Documents newly matching these filters trigger a delivery to `url`. */
991
- searchCriteria: SearchRequest;
2842
+ /** New documents matching these filters trigger a `documents.new` delivery. */
2843
+ searchCriteria?: WebhookCriteria;
2844
+ /**
2845
+ * Base-act CELEX numbers to watch — amendments, corrigenda, repeals and
2846
+ * new consolidated versions trigger a `watchlist.changes` delivery. Plan
2847
+ * limit per webhook: STARTER 100, PROFESSIONAL 500, BUSINESS 1000, SCALE
2848
+ * 2000, ENTERPRISE 5000.
2849
+ */
2850
+ watchCelex?: string[];
992
2851
  }
993
2852
  /**
994
- * Partial update — only the supplied fields are changed. Setting `status`
995
- * to `ACTIVE` additionally resets `consecutiveFailures` to 0 (how you
996
- * re-enable an auto-paused webhook).
2853
+ * Partial update — only the supplied fields are changed. `watchCelex`
2854
+ * replaces the whole list; `searchCriteria: null` removes the criteria (one
2855
+ * of the two must remain). Setting `status` to `ACTIVE` resets
2856
+ * `consecutiveFailures`; moving a `FAILED`/`PAUSED` webhook to `ACTIVE`
2857
+ * also re-queues its deliveries from the last 7 days that ran out of
2858
+ * retries (`requeuedDeliveries`).
997
2859
  */
998
2860
  interface WebhookUpdateRequest {
999
2861
  name?: string;
1000
2862
  url?: string;
1001
- searchCriteria?: SearchRequest;
2863
+ searchCriteria?: WebhookCriteria | null;
2864
+ watchCelex?: string[];
1002
2865
  status?: WebhookStatus;
1003
2866
  }
1004
2867
  /** Returned by `POST /webhooks`. The `secret` is included here only. */
1005
- interface WebhookCreateResponse {
2868
+ interface WebhookCreateResponse extends WithResponseHeaders {
1006
2869
  success: boolean;
1007
2870
  message?: string;
1008
2871
  webhook: {
@@ -1012,12 +2875,13 @@ interface WebhookCreateResponse {
1012
2875
  /** HMAC-SHA256 signing secret. Store this — it is not returned again. */
1013
2876
  secret?: string;
1014
2877
  status: WebhookStatus;
1015
- searchCriteria?: SearchRequest;
2878
+ searchCriteria?: WebhookCriteria | null;
2879
+ watchCelex?: string[];
1016
2880
  createdAt: string;
1017
2881
  };
1018
2882
  }
1019
2883
  /** Returned by `PUT /webhooks/{id}` — summary fields only. */
1020
- interface WebhookUpdateResponse {
2884
+ interface WebhookUpdateResponse extends WithResponseHeaders {
1021
2885
  success: boolean;
1022
2886
  message?: string;
1023
2887
  webhook: {
@@ -1025,21 +2889,31 @@ interface WebhookUpdateResponse {
1025
2889
  name?: string;
1026
2890
  url?: string;
1027
2891
  status?: WebhookStatus;
1028
- searchCriteria?: SearchRequest;
2892
+ searchCriteria?: WebhookCriteria | null;
2893
+ criteriaErrors?: string[];
2894
+ watchCelex?: string[];
1029
2895
  updatedAt?: string;
1030
2896
  };
2897
+ /** Present when the request set `status: "ACTIVE"` — deliveries queued again. */
2898
+ requeuedDeliveries?: number;
1031
2899
  }
1032
2900
  /** Returned by `GET /webhooks/{id}`. */
1033
- interface WebhookResponse {
2901
+ interface WebhookResponse extends WithResponseHeaders {
1034
2902
  success: boolean;
1035
2903
  webhook: WebhookDetail;
1036
2904
  }
2905
+ /** Returned by `DELETE /webhooks/{id}`. */
2906
+ interface WebhookDeleteResponse extends WithResponseHeaders {
2907
+ success: boolean;
2908
+ message?: string;
2909
+ }
1037
2910
  /**
1038
2911
  * Result of a synchronous test delivery. `success: true` means the
1039
2912
  * upstream responded 2xx; non-2xx and network errors both yield
1040
- * `success: false` plus a populated `delivery.errorMessage`.
2913
+ * `success: false` plus a populated `delivery.errorMessage`. Test
2914
+ * deliveries are not recorded in the delivery history.
1041
2915
  */
1042
- interface WebhookTestResponse {
2916
+ interface WebhookTestResponse extends WithResponseHeaders {
1043
2917
  success: boolean;
1044
2918
  message?: string;
1045
2919
  delivery: {
@@ -1056,7 +2930,7 @@ interface WebhookDeliveriesParams {
1056
2930
  /** Pagination offset. Default 0. */
1057
2931
  offset?: number;
1058
2932
  }
1059
- interface WebhookDeliveriesResponse {
2933
+ interface WebhookDeliveriesResponse extends WithResponseHeaders {
1060
2934
  success: boolean;
1061
2935
  /** Total deliveries for this webhook (across all pages). */
1062
2936
  total?: number;
@@ -1064,18 +2938,98 @@ interface WebhookDeliveriesResponse {
1064
2938
  offset?: number;
1065
2939
  deliveries: WebhookDelivery[];
1066
2940
  }
2941
+ /** A document as delivered by `documents.new` and `watchlist.changes`. */
2942
+ interface WebhookChangeDocument {
2943
+ celex?: string;
2944
+ /** English title (another official language when no English title exists yet); null if metadata never arrived. */
2945
+ title?: string | null;
2946
+ url?: string;
2947
+ documentType?: string | null;
2948
+ documentTypeCode?: string | null;
2949
+ /** Publications Office resource-type codes, e.g. `["CONS_TEXT"]`. */
2950
+ resourceTypes?: string[];
2951
+ author?: string | null;
2952
+ authorCodes?: string[];
2953
+ dateOfDocumentISO?: string | null;
2954
+ /** The document date as dd/mm/yyyy. */
2955
+ dateOfDocument?: string | null;
2956
+ /** Consolidated versions only — the date the version applies from (may be in the future). */
2957
+ consolidationDate?: string | null;
2958
+ /** When the document appeared on EUR-Lex — the clock webhooks match on. */
2959
+ addedAt?: string | null;
2960
+ /** Upper-case ISO codes with a published expression. Check before fetching a consolidated version. */
2961
+ availableLanguages?: string[];
2962
+ /** Alias of `celex` (earlier payload shape). */
2963
+ celexNumber?: string;
2964
+ /** Alias of `documentType` (earlier payload shape). */
2965
+ form?: string | null;
2966
+ }
2967
+ /** Fields shared by every signed delivery. */
2968
+ interface WebhookDeliveryEnvelope {
2969
+ /** Time of THIS attempt (re-signed on every retry) — use it for a replay window. */
2970
+ timestamp: string;
2971
+ webhook: {
2972
+ id: string;
2973
+ name: string;
2974
+ };
2975
+ /** `id` is stable across retries (also `X-Webhook-Delivery`) — dedupe on it. Absent on `webhook.test`. */
2976
+ delivery?: {
2977
+ id: string;
2978
+ attempt: number;
2979
+ };
2980
+ }
2981
+ interface WebhookDocumentsNewPayload extends WebhookDeliveryEnvelope {
2982
+ event: "documents.new";
2983
+ searchCriteria?: WebhookCriteria | null;
2984
+ data: {
2985
+ /** Documents in this delivery (max 100). */
2986
+ count: number;
2987
+ /** Every new match from the same hourly check — larger than `count` when split across deliveries. */
2988
+ totalAvailable?: number;
2989
+ documents: WebhookChangeDocument[];
2990
+ };
2991
+ }
2992
+ type WatchlistRelation = "amended_by" | "corrected_by" | "repealed_by" | "consolidated_version" | (string & {});
2993
+ interface WebhookWatchlistChange {
2994
+ watchedCelex: string;
2995
+ relation: WatchlistRelation;
2996
+ document: WebhookChangeDocument;
2997
+ }
2998
+ interface WebhookWatchlistChangesPayload extends WebhookDeliveryEnvelope {
2999
+ event: "watchlist.changes";
3000
+ data: {
3001
+ /** Changes in this delivery (max 100). */
3002
+ count: number;
3003
+ changes: WebhookWatchlistChange[];
3004
+ };
3005
+ }
3006
+ /** Sent by `webhooks.test()`. */
3007
+ interface WebhookTestPayload extends WebhookDeliveryEnvelope {
3008
+ event: "webhook.test";
3009
+ data: {
3010
+ message: string;
3011
+ searchCriteria?: WebhookCriteria | null;
3012
+ };
3013
+ }
3014
+ /** Discriminated union of every payload LexAPI delivers — switch on `event`. */
3015
+ type WebhookPayload = WebhookDocumentsNewPayload | WebhookWatchlistChangesPayload | WebhookTestPayload;
1067
3016
  /**
1068
3017
  * One entry in a document's version history.
1069
3018
  *
1070
3019
  * Versions are LexAPI *observation snapshots* (content-hash changes between
1071
- * fetches), not legal in-force reconstructions. `fetchedAt` is when THIS
1072
- * version was fetched — version N is "current" from there until version
1073
- * N+1's `fetchedAt`.
3020
+ * fetches), not legal in-force reconstructions — for the text in force on a
3021
+ * date use a consolidated CELEX, or `semanticLegislationSearch({ asOf })`.
3022
+ * `fetchedAt` is when THIS version was fetched — version N is "current"
3023
+ * from there until version N+1's `fetchedAt`.
1074
3024
  */
1075
3025
  interface VersionEntry {
1076
3026
  version: number;
1077
3027
  isCurrent: boolean;
1078
- /** Equality across versions means no real content change. */
3028
+ /**
3029
+ * Equal hashes mean no text change. A different hash usually means EUR-Lex
3030
+ * changed the text — or the current version was re-parsed in place by an
3031
+ * improved parser.
3032
+ */
1079
3033
  contentHash: string;
1080
3034
  fetchedAt: string;
1081
3035
  title?: string | null;
@@ -1084,7 +3038,7 @@ interface VersionEntry {
1084
3038
  /** Present on single-snapshot responses only (not in history listings). */
1085
3039
  parsedContent?: Record<string, unknown> | null;
1086
3040
  }
1087
- interface DocumentVersionsResponse extends CreditedResponse {
3041
+ interface DocumentVersionsResponse extends CreditedResponse, WithResponseHeaders {
1088
3042
  success: boolean;
1089
3043
  celex: string;
1090
3044
  language: string;
@@ -1096,7 +3050,7 @@ interface DocumentVersionsResponse extends CreditedResponse {
1096
3050
  /** Newest first; the current version is included and flagged. */
1097
3051
  versions: VersionEntry[];
1098
3052
  }
1099
- interface DocumentVersionResponse extends CreditedResponse {
3053
+ interface DocumentVersionResponse extends CreditedResponse, WithResponseHeaders {
1100
3054
  success: boolean;
1101
3055
  celex: string;
1102
3056
  language: string;
@@ -1104,30 +3058,70 @@ interface DocumentVersionResponse extends CreditedResponse {
1104
3058
  asOf?: string;
1105
3059
  semantics: string;
1106
3060
  document: VersionEntry;
1107
- /** Mirrors the `X-Corpus-Version` response header. */
3061
+ /** SDK-added: mirrors the `X-Corpus-Version` response header. */
1108
3062
  corpusVersion?: number;
1109
3063
  }
3064
+ /** Shared params for the version endpoints. */
3065
+ interface VersionParams {
3066
+ /** 2-letter ISO language of the tracked corpus row (default `en`). */
3067
+ language?: string;
3068
+ }
1110
3069
 
3070
+ /** A list filter: an array, or a comma-separated string (`"regulation,directive"`). */
3071
+ type ExportListFilter = string | ReadonlyArray<string>;
3072
+ /**
3073
+ * Filters for `GET /export` (API 2.3.0, lex-api #303). List values are sent
3074
+ * comma-separated and ORed.
3075
+ */
1111
3076
  interface ExportParams {
1112
- /** Comma-separated document types, e.g. `"regulation,directive"`. */
1113
- documentType?: string;
1114
- /** Comma-separated list of authors. */
1115
- author?: string;
1116
- /** Comma-separated subdomains (`legislation`, `case-law`, `treaties`, ...). */
1117
- subdomain?: string;
3077
+ /**
3078
+ * Document types: the stored label, matched exactly ignoring case
3079
+ * (`"regulation"` matches `Regulation`, not `Implementing regulation`).
3080
+ * For a whole family use `documentTypeCode`.
3081
+ */
3082
+ documentType?: ExportListFilter;
3083
+ /**
3084
+ * Type families by the `documentTypeCode` each row carries: `"regulation"`
3085
+ * includes implementing and delegated regulations. Combined with
3086
+ * `documentType`, both must match.
3087
+ */
3088
+ documentTypeCode?: ExportListFilter;
3089
+ /** Authors: whole stored values, ignoring case (a joint act's author string is one value). */
3090
+ author?: ExportListFilter;
3091
+ /** Subdomains (`legislation`, `case-law`, `treaties`, `preparatory`, `international`, `consolidated`, …). */
3092
+ subdomain?: ExportListFilter;
1118
3093
  /** Document language (default `en`). */
1119
3094
  language?: Language;
1120
- /** Earliest `dateOfDocument` to include (inclusive, `YYYY-MM-DD`). */
3095
+ /** Earliest document date to include (inclusive, `YYYY-MM-DD`; anything else is a 400). */
1121
3096
  dateFrom?: string;
1122
- /** Latest `dateOfDocument` to include (inclusive, `YYYY-MM-DD`). */
3097
+ /** Latest document date to include (inclusive, `YYYY-MM-DD`). */
1123
3098
  dateTo?: string;
1124
- /** Only stream rows whose `lastSeenAt` is at or after this ISO timestamp. */
1125
- fetchedSince?: string;
3099
+ /**
3100
+ * Rows whose `lastSeenAt` is at or after this time (any write to the row).
3101
+ * An ISO 8601 date or a date-time WITH a timezone (the API answers 400 to
3102
+ * one without), or a `Date` (sent as UTC).
3103
+ */
3104
+ fetchedSince?: string | Date;
3105
+ /**
3106
+ * Rows whose text changed (`contentChangedAt`) at or after this time — the
3107
+ * cheapest incremental sync. Same format as `fetchedSince`.
3108
+ */
3109
+ changedSince?: string | Date;
1126
3110
  /** Include raw `htmlContent` / `htmlMetadata` per row (large). Default false. */
1127
3111
  includeHtml?: boolean;
1128
3112
  /** Set `false` to omit `parsedContent` from each row. Default true. */
1129
3113
  includeContent?: boolean;
1130
- /** Max rows to stream. Clamped to the server's `EXPORT_MAX_ROWS` ceiling. */
3114
+ /**
3115
+ * Also stream metadata-only rows (documents whose text EUR-Lex does not
3116
+ * publish, or not yet). Default false — skipped rows are counted as
3117
+ * `skippedStubs` on the trailer.
3118
+ */
3119
+ includeStubs?: boolean;
3120
+ /**
3121
+ * Max rows to stream: a positive integer (anything else throws a
3122
+ * `RangeError` before the request — the API answers 400). Clamped to the
3123
+ * server's `EXPORT_MAX_ROWS` ceiling (default 50 000).
3124
+ */
1131
3125
  limit?: number;
1132
3126
  }
1133
3127
  /**
@@ -1170,27 +3164,90 @@ interface ExportRow {
1170
3164
  htmlMetadata?: unknown;
1171
3165
  [key: string]: unknown;
1172
3166
  }
3167
+ /** Body of the leading `{"_meta": {...}}` line. */
3168
+ interface ExportMetaInfo {
3169
+ filters?: {
3170
+ documentType?: string[] | null;
3171
+ author?: string[] | null;
3172
+ subdomain?: string[] | null;
3173
+ language?: string;
3174
+ dateFrom?: string | null;
3175
+ dateTo?: string | null;
3176
+ fetchedSince?: string | null;
3177
+ };
3178
+ /** Rows matching the filters (same as `X-Export-Total`). */
3179
+ totalMatching?: number;
3180
+ /** Rows the server will stream (min of total and limit). */
3181
+ streaming?: number;
3182
+ truncated?: boolean;
3183
+ includeHtml?: boolean;
3184
+ includeContent?: boolean;
3185
+ exportedAt?: string;
3186
+ [key: string]: unknown;
3187
+ }
1173
3188
  /**
1174
- * The leading `_meta` envelope line. The spec does not pin its shape, so
1175
- * beyond the `_meta` marker everything is kept as-is.
3189
+ * The leading `_meta` envelope line. The server nests everything under
3190
+ * `_meta`; the SDK also lifts those fields to the top level for convenience
3191
+ * (`stream.meta.totalMatching`).
1176
3192
  */
1177
- interface ExportMeta {
1178
- _meta?: unknown;
1179
- [key: string]: unknown;
3193
+ interface ExportMeta extends ExportMetaInfo {
3194
+ _meta?: ExportMetaInfo | unknown;
1180
3195
  }
1181
- /** The trailing `_done` line. Reports `truncated: true` when the row cap was hit. */
1182
- interface ExportDone {
1183
- _done?: unknown;
3196
+ /** Body of the trailing `{"_done": {...}}` line. */
3197
+ interface ExportDoneInfo {
3198
+ /** Rows actually written. */
3199
+ written?: number;
3200
+ /**
3201
+ * `true` when matching rows remain that the export did not reach (API
3202
+ * 2.3.0: authoritative, see `truncatedBy`) — narrow the filters or resume
3203
+ * via `changedSince` / `fetchedSince`.
3204
+ */
1184
3205
  truncated?: boolean;
3206
+ /** Metadata-only rows skipped because `includeStubs` was off. */
3207
+ skippedStubs?: number;
3208
+ /** Exactly `false` marks an incomplete export (SDK contract §1.8); absent or `true` = complete. */
3209
+ complete?: boolean;
3210
+ /**
3211
+ * API 2.3.0: what cut the export short — `limit`, `max_rows`, `recovered`
3212
+ * (the server's recovery sweep took the export's billing record mid-stream), `credits`
3213
+ * (the pool could not pay for rows added since the count), or `null`.
3214
+ */
3215
+ truncatedBy?: "limit" | "max_rows" | "credits" | "recovered" | null;
3216
+ /**
3217
+ * API 2.3.0, credit plans: the pool after settlement, plus `reserved`,
3218
+ * `charged` (max(written, 1)) and `refunded`; `refundPending: true` when
3219
+ * the refund is applied later by the server's recovery sweep.
3220
+ */
3221
+ credits?: {
3222
+ reserved?: number;
3223
+ charged?: number;
3224
+ refunded?: number;
3225
+ refundPending?: boolean;
3226
+ remaining?: number;
3227
+ [key: string]: unknown;
3228
+ };
1185
3229
  [key: string]: unknown;
1186
3230
  }
3231
+ /**
3232
+ * The trailing `_done` line. The server nests the fields under `_done`; the
3233
+ * SDK lifts them to the top level so `stream.done?.truncated` works.
3234
+ */
3235
+ interface ExportDone extends ExportDoneInfo {
3236
+ _done?: ExportDoneInfo | unknown;
3237
+ }
1187
3238
  /** Signals lifted from the `X-Export-*` response headers. */
1188
3239
  interface ExportHeaderInfo {
1189
3240
  /** Total rows matching the filters in the database (`X-Export-Total`). */
1190
3241
  total: number | undefined;
1191
- /** Rows actually streamed — min of total and limit (`X-Export-Streaming`). */
3242
+ /**
3243
+ * Rows the server set out to stream — min of total and limit
3244
+ * (`X-Export-Streaming`). Rows written can be lower by `done.skippedStubs`.
3245
+ */
1192
3246
  streaming: number | undefined;
1193
- /** `true` when the row cap was hit (`X-Export-Truncated: 1`). */
3247
+ /**
3248
+ * `X-Export-Truncated: 1` — the up-front count exceeded the row cap. A hint
3249
+ * only; `stream.truncated` prefers `_done.truncated` once it is read.
3250
+ */
1194
3251
  truncated: boolean | undefined;
1195
3252
  }
1196
3253
  /**
@@ -1199,59 +3256,133 @@ interface ExportHeaderInfo {
1199
3256
  * - `meta` is parsed from the leading `_meta` line and available
1200
3257
  * immediately (before iterating).
1201
3258
  * - `done` is populated from the trailing `_done` line once iteration
1202
- * completes; check `done.truncated` (or `headers.truncated`) to detect
1203
- * the row cap — do not assume the stream was complete.
1204
- * - `_meta`/`_done` lines are never yielded as rows.
3259
+ * completes; check `stream.truncated` (`_done.truncated` once read,
3260
+ * else the header / `_meta` hints — SDK contract §1.8) to detect rows the
3261
+ * export did not reach.
3262
+ * - If the body ends WITHOUT the `_done` trailer (the server stopped
3263
+ * mid-export), iteration throws `IncompleteExportError` after yielding the
3264
+ * rows that did arrive (`complete` stays `false`); a dropped connection
3265
+ * throws `NetworkError` (`CONNECTION_ERROR`); no data for `timeoutMs`
3266
+ * throws `TimeoutError` (`REQUEST_TIMEOUT`); the call's `signal` throws
3267
+ * `RequestAbortedError`. In every case the connection is released.
3268
+ * - A `_done` line with `complete: false`, or any line whose only key is
3269
+ * `_error`, also means incomplete: iteration throws `IncompleteExportError`
3270
+ * after the rows that did arrive (the `_error` body is on its `details` and
3271
+ * on `stream.error`). Unknown `_done` fields (`truncatedBy`, `credits`) are
3272
+ * kept on `done`.
3273
+ * - Lines that are not JSON objects are counted in `invalidLines`, not yielded.
3274
+ * - `_meta`/`_done`/`_error` lines are never yielded as rows.
1205
3275
  */
1206
3276
  interface ExportStream extends AsyncIterable<ExportRow> {
1207
3277
  readonly meta: ExportMeta | undefined;
1208
3278
  readonly done: ExportDone | undefined;
1209
3279
  readonly headers: ExportHeaderInfo;
3280
+ /**
3281
+ * `true` once a `_done` trailer was read that does not say
3282
+ * `complete: false`, and no `_error` line arrived — only then is the export
3283
+ * whole (SDK contract §1.8).
3284
+ */
3285
+ readonly complete: boolean;
3286
+ /** The server's `_error` line body, if one arrived (never yielded as a row). */
3287
+ readonly error: Record<string, unknown> | undefined;
3288
+ /** Data rows yielded so far. */
3289
+ readonly rowsRead: number;
3290
+ /** Lines that were not JSON objects (e.g. a half-written last line) — counted, not yielded. */
3291
+ readonly invalidLines: number;
3292
+ /**
3293
+ * Whether matching rows remain that this export did not reach, per SDK
3294
+ * contract §1.8: `_done.truncated` once the trailer has been read (API
3295
+ * 2.3.0: authoritative — set by `limit`, the server maximum or the credit
3296
+ * pool, see `done.truncatedBy`; never derived from the count; skipped stubs
3297
+ * do not count). Before the trailer: the `X-Export-Truncated` header, then
3298
+ * `_meta.truncated` — hints from the up-front count, which may be cached
3299
+ * for up to a minute and never caps the stream. `undefined` when unknown.
3300
+ */
3301
+ readonly truncated: boolean | undefined;
3302
+ /**
3303
+ * Abandon the export and release the connection (e.g. after inspecting
3304
+ * `meta` without iterating). Breaking out of `for await` does this too.
3305
+ */
3306
+ cancel(): Promise<void>;
3307
+ }
3308
+ /** Options for reading an export body. */
3309
+ interface ExportStreamOptions {
3310
+ /** Abort a read that receives no bytes for this long (ms). Default: the client timeout. */
3311
+ idleTimeoutMs?: number;
3312
+ /** Caller cancellation (aborts the read and releases the connection). */
3313
+ signal?: AbortSignal;
1210
3314
  }
1211
3315
 
1212
3316
  /**
1213
- * Webhook subscriptions — notify a URL when newly-published documents
1214
- * match saved `/search` criteria. Accessed as `client.webhooks.*`.
3317
+ * Webhook subscriptions — notify a URL when newly-published documents match
3318
+ * saved criteria (`documents.new`) and/or watched acts change
3319
+ * (`watchlist.changes`). Accessed as `client.webhooks.*`. Webhook management
3320
+ * and deliveries cost no credits.
3321
+ *
3322
+ * Write calls (create / update / delete / test) are never retried on 5xx or
3323
+ * on network errors after the connection was made — only on 429 and on
3324
+ * connect-phase failures (nothing reached the API).
1215
3325
  */
1216
3326
  declare class WebhooksAPI {
1217
3327
  private readonly http;
1218
3328
  constructor(http: HttpClient);
3329
+ private call;
1219
3330
  /**
1220
3331
  * `GET /webhooks` — every webhook owned by the caller, newest first.
1221
3332
  * The `secret` is never returned here (only once, on creation).
1222
3333
  */
1223
3334
  list(options?: CallOptions): Promise<WebhookListResponse>;
1224
3335
  /**
1225
- * `POST /webhooks` — subscribe a URL to documents matching saved search
1226
- * criteria. If `secret` is omitted the server generates one and returns
1227
- * it in this response ONLY — store it. Rejected with 400 when the tier
1228
- * webhook ceiling is reached (FREE=0, STARTER=2, PROFESSIONAL=10,
1229
- * BUSINESS=50).
3336
+ * `POST /webhooks` — needs `searchCriteria`, `watchCelex`, or both. If
3337
+ * `secret` is omitted the server generates one and returns it in this
3338
+ * response ONLY — store it. Rejected with 400 (`InvalidParamsError`):
3339
+ * unsupported criteria or a watch list above the plan limit carry a
3340
+ * `details` list; the tier webhook ceiling (FREE=0, STARTER=2,
3341
+ * PROFESSIONAL=10, BUSINESS=50, SCALE=100, ENTERPRISE=100) has no
3342
+ * `details` — read `current` / `limit` from `error.body`.
1230
3343
  */
1231
3344
  create(request: WebhookCreateRequest, options?: CallOptions): Promise<WebhookCreateResponse>;
1232
- /** `GET /webhooks/{id}` — full details including the 20 most recent deliveries. */
3345
+ /** `GET /webhooks/{id}` — full details incl. `retryPolicy` and the 20 most recent deliveries. */
1233
3346
  get(id: string, options?: CallOptions): Promise<WebhookResponse>;
1234
3347
  /**
1235
3348
  * `PUT /webhooks/{id}` — partial update; only supplied fields change.
1236
- * Setting `status: "ACTIVE"` also resets `consecutiveFailures` to 0
1237
- * (re-enables an auto-paused webhook).
3349
+ * `watchCelex` replaces the whole list; `searchCriteria: null` removes the
3350
+ * criteria (one of the two must remain). Setting `status: "ACTIVE"`
3351
+ * resets `consecutiveFailures`; moving a `FAILED` or `PAUSED` webhook to
3352
+ * `ACTIVE` also re-queues its deliveries from the last 7 days that ran out
3353
+ * of retries (count in `requeuedDeliveries`, 0 otherwise).
1238
3354
  */
1239
3355
  update(id: string, request: WebhookUpdateRequest, options?: CallOptions): Promise<WebhookUpdateResponse>;
1240
3356
  /**
1241
3357
  * `DELETE /webhooks/{id}` — permanently deletes the webhook and its
1242
- * delivery history. Resolves on 204; a repeat delete throws
1243
- * `NotFoundError`.
3358
+ * delivery history. Resolves with the server's `{ success, message }`
3359
+ * (an empty object plus `headers` on a bodiless 204); a repeat delete
3360
+ * throws `NotFoundError`.
1244
3361
  */
1245
- delete(id: string, options?: CallOptions): Promise<void>;
3362
+ delete(id: string, options?: CallOptions): Promise<WebhookDeleteResponse | undefined>;
1246
3363
  /**
1247
3364
  * `POST /webhooks/{id}/test` — synchronously POSTs a `webhook.test`
1248
3365
  * payload (HMAC-SHA256 signed via `X-Webhook-Signature`) to the webhook
1249
3366
  * URL and returns the upstream result. 10 s timeout; redirects are not
1250
- * followed.
3367
+ * followed; not recorded in the delivery history.
1251
3368
  */
1252
3369
  test(id: string, options?: CallOptions): Promise<WebhookTestResponse>;
1253
3370
  /** `GET /webhooks/{id}/deliveries` — delivery history, most recent first. */
1254
3371
  deliveries(id: string, params?: WebhookDeliveriesParams, options?: CallOptions): Promise<WebhookDeliveriesResponse>;
3372
+ /**
3373
+ * Walk the whole delivery history page by page (`limit` per page, default
3374
+ * 50), starting at `offset`, newest first (SDK contract §1.4). Each
3375
+ * delivery is yielded at most once (deduplicated on `id`): a delivery
3376
+ * created during the walk shifts later pages by one. Stops on an empty page
3377
+ * or when the offset reaches `total`. Pages are free (0 credits).
3378
+ *
3379
+ * ```ts
3380
+ * for await (const page of client.webhooks.paginateDeliveries(id)) {
3381
+ * for (const d of page.deliveries) console.log(d.status, d.responseStatus);
3382
+ * }
3383
+ * ```
3384
+ */
3385
+ paginateDeliveries(id: string, params?: WebhookDeliveriesParams, options?: CallOptions): AsyncGenerator<WebhookDeliveriesResponse, void>;
1255
3386
  }
1256
3387
 
1257
3388
  interface LexAPIOptions {
@@ -1263,19 +3394,30 @@ interface LexAPIOptions {
1263
3394
  apiKey?: string;
1264
3395
  /** API base URL. Defaults to production (`https://lex-api.com/api/v1`). */
1265
3396
  baseUrl?: string;
1266
- /** Per-request timeout in milliseconds (per attempt). Default 60_000. */
3397
+ /**
3398
+ * Per-attempt timeout in milliseconds, covering the response body (for
3399
+ * `export`: an idle timeout per read). Default 95_000 — enough for a
3400
+ * single live EUR-Lex fetch (the API caps each at 90 s, then answers with
3401
+ * a typed, refunded 504), and below Cloudflare's 100 s proxy timeout. A
3402
+ * request that needs several upstream fetches can still exceed it.
3403
+ */
1267
3404
  timeoutMs?: number;
1268
3405
  /** Injectable fetch (used for testing / polyfills). Defaults to global fetch. */
1269
3406
  fetch?: typeof fetch;
1270
- /** Retry policy. Default: 3 retries, 500 ms base, 30 s cap. */
3407
+ /** Retry policy. Default: 3 retries, 500 ms base, 30 s cap; read-only POST 5xx retries are opt-in. */
1271
3408
  retry?: RetryOptions;
1272
3409
  /** Optional suffix appended to the `User-Agent` header. */
1273
3410
  userAgentSuffix?: string;
1274
3411
  }
1275
3412
  /** Per-call overrides accepted by every SDK method. */
1276
3413
  interface CallOptions {
1277
- /** Override the client-level timeout for this call only. */
3414
+ /** Override the client-level timeout for this call only (per attempt, covering the response body). */
1278
3415
  timeoutMs?: number;
3416
+ /**
3417
+ * Cancel the call: aborts the in-flight request, any retry wait and (for
3418
+ * `export`) the stream. Rejects with `RequestAbortedError`; never retried.
3419
+ */
3420
+ signal?: AbortSignal;
1279
3421
  }
1280
3422
  /**
1281
3423
  * LexAPI client — European legal data, made queryable.
@@ -1283,6 +3425,10 @@ interface CallOptions {
1283
3425
  * Server-side only: API keys are secrets and browsers additionally forbid
1284
3426
  * setting the `User-Agent` header this SDK sends.
1285
3427
  *
3428
+ * Every JSON result carries the raw `subscription` / `usage` / `credits`
3429
+ * blocks plus an SDK-added `headers` object (`X-Source`, rate limits,
3430
+ * `X-Warning`, …) — see `ResponseHeaders`.
3431
+ *
1286
3432
  * ```ts
1287
3433
  * const client = new LexAPI({ apiKey: "lex_..." }); // or set LEXAPI_API_KEY
1288
3434
  * const info = await client.getInfo();
@@ -1293,6 +3439,10 @@ declare class LexAPI {
1293
3439
  /** Webhook subscriptions (`client.webhooks.list/create/get/update/delete/test/deliveries`). */
1294
3440
  readonly webhooks: WebhooksAPI;
1295
3441
  constructor(options?: LexAPIOptions);
3442
+ /** Redacted view for `JSON.stringify` — never includes the API key. */
3443
+ toJSON(): Record<string, unknown>;
3444
+ /** Perform a JSON request and attach the parsed response headers (+ legacy header fields). */
3445
+ private call;
1296
3446
  /**
1297
3447
  * `GET /info` — API capabilities, subscription tier, and current usage.
1298
3448
  * Free operation (0 credits); useful as a connection probe.
@@ -1301,178 +3451,390 @@ declare class LexAPI {
1301
3451
  /**
1302
3452
  * `POST /search` — search EUR-Lex with structured filters.
1303
3453
  *
3454
+ * **Cost: 3 credits per result page** (`maxPages`, tier-clamped), charged
3455
+ * upfront and refunded for pages never fetched; a search that fails
3456
+ * before its first page is refunded in full. Identical searches within
3457
+ * 60 minutes are served from a result cache (`headers.searchCache: "hit"`,
3458
+ * same price) — pass `fresh: true` to force a re-fetch.
3459
+ *
1304
3460
  * At least one filter is required. Truncation and partial-result signals
1305
- * are surfaced on the response rather than hidden: check `truncated` /
1306
- * `truncatedAt` / `truncatedReason` (tier-capped pagination), `partial` /
1307
- * `partialReason` (an upstream page timed out), `postFilteredBy`
1308
- * (controller-side post-filter dropped rows — `"date"` means raising
1309
- * `maxPages` widens recall), `ignoredDocumentTypes`, and `xWarning`
1310
- * (the `X-Warning` response header, e.g. `maxPages` tier clamping).
3461
+ * are surfaced, not hidden: `truncated` / `truncatedAt` / `truncatedReason`
3462
+ * (tier-capped pagination), `partial` / `partialReason` (an upstream page
3463
+ * timed out, or `source: "corpus"` — EUR-Lex unreachable, answered from
3464
+ * the corpus mirror), `postFilteredBy` (`"date"` → raise `maxPages`),
3465
+ * `ignoredDocumentTypes`, `hint` (zero results → try semantic search), and
3466
+ * `xWarning` (the `X-Warning` header, e.g. `maxPages` clamped).
1311
3467
  */
1312
3468
  search(request: SearchRequest, options?: CallOptions): Promise<SearchResponse>;
1313
3469
  /**
1314
3470
  * `POST /documentContent` — fetch a single fully-parsed document by CELEX.
1315
3471
  *
1316
- * Corpus-first with live-scrape fallback (`bypassCorpus: true` forces a
1317
- * live read). Use `include`/`fields`/`articleId` to trim the payload.
3472
+ * **Cost: 5 credits, settled by source** — 1 from the LexAPI corpus
3473
+ * (`headers.source === "corpus"`), 4 from the Publications Office Cellar
3474
+ * API (`"cellar"` / `"cellar-oj"`), 5 for a browser fetch (`"live"`).
3475
+ *
3476
+ * Check `document.textAvailability.available` before reading
3477
+ * `document.content`: a document whose text EUR-Lex does not publish is a
3478
+ * 200 with metadata and `content: null` (billed 1 credit), with the reason
3479
+ * and — for base acts — a pointer to the consolidated version. Use
3480
+ * `language` / `acceptLanguages` for other renditions and
3481
+ * `include`/`fields`/`articleId` to trim the payload.
1318
3482
  */
1319
3483
  getDocument(request: DocumentContentRequest, options?: CallOptions): Promise<DocumentContentResponse>;
1320
3484
  /**
1321
3485
  * `POST /documentContent/batch` — fetch multiple documents in one request.
1322
3486
  *
1323
- * The batch is clamped to the tier ceiling (FREE=1, STARTER=5,
1324
- * PROFESSIONAL=20, BUSINESS=50). Clamping is surfaced, not silent: check
1325
- * `trimmed` / `trimmedTo` / `trimmedReason` on the body and `xWarning`
1326
- * (the `X-Warning` header). Per-CELEX failures are collected in `errors`
1327
- * instead of aborting the batch.
3487
+ * **Cost: 5 credits per processed item, settled by source** (corpus 1,
3488
+ * Cellar / OJ 4, browser 5; `headers.batch` has the source counts). The
3489
+ * batch is clamped to the tier ceiling (FREE=1, STARTER=5,
3490
+ * PROFESSIONAL=20, BUSINESS+=50); trimmed items are not charged. Clamping
3491
+ * is surfaced: `trimmed` / `trimmedTo` / `trimmedReason` and `xWarning`.
3492
+ * Per-CELEX failures are collected in `errors`; text-unavailable items
3493
+ * stay in `documents` (counted in `textUnavailable`).
1328
3494
  */
1329
3495
  getDocumentsBatch(request: DocumentContentBatchRequest, options?: CallOptions): Promise<DocumentContentBatchResponse>;
1330
3496
  /**
1331
3497
  * `GET /documents/recent` — recently-published documents (last `days`
1332
- * days, default 7). Page fetching is tier-clamped like `/search`;
1333
- * `xWarning` carries the `X-Warning` header when clamping fired, and
1334
- * `languageFilter` reports rows dropped by the language post-filter.
3498
+ * days, default 7; up to `limit`, default 50).
3499
+ *
3500
+ * **Cost: 3 credits per result page** (~10 results each, tier-capped);
3501
+ * unfiltered requests are answered from Cellar in one query
3502
+ * (`headers.source === "cellar"`) and settle at a single page. `author`
3503
+ * arrays are sent as repeated query parameters; `documentType` and
3504
+ * `subdomain` take ONE value — EUR-Lex applies only the first of several
3505
+ * on this path (use `search` for multi-type / multi-subdomain queries). `languageFilter`
3506
+ * reports rows dropped by the language post-filter.
1335
3507
  */
1336
3508
  getRecentDocuments(params?: RecentDocumentsParams, options?: CallOptions): Promise<RecentDocumentsResponse>;
1337
3509
  /**
1338
- * `POST /documents/url` — fetch a document by any EUR-Lex URL. The
1339
- * response is shaped like `getDocument` plus `sourceUrl` and
1340
- * `extractedCelex` echo-backs.
3510
+ * `POST /documents/url` — fetch a document by any EUR-Lex URL. Shaped like
3511
+ * `getDocument` plus `sourceUrl` and `extractedCelex` echo-backs. Same
3512
+ * settle-by-source pricing (corpus 1, Cellar 4, browser 5).
1341
3513
  */
1342
3514
  getDocumentByUrl(request: DocumentByUrlRequest, options?: CallOptions): Promise<DocumentByUrlResponse>;
1343
3515
  /**
1344
3516
  * `POST /documents/metadata` — metadata only (title, dates, ECLI/ELI,
1345
- * keywords, subjects). Skips the body parse: significantly faster and
1346
- * cheaper than `getDocument`.
3517
+ * keywords, subjects, URLs). Skips the body parse: faster than
3518
+ * `getDocument`. **Cost: 5 credits, settled by source** (corpus 1, Cellar 4).
1347
3519
  */
1348
3520
  getDocumentMetadata(request: DocumentMetadataRequest, options?: CallOptions): Promise<DocumentMetadataResponse>;
1349
3521
  /**
1350
3522
  * `POST /resolve` — resolve any legal identifier (bare CELEX, EUR-Lex
1351
3523
  * URL, ELI URI, or ECLI) to the canonical CELEX plus access URLs.
3524
+ * 1 credit. ECLIs (and unmappable ELIs) resolve via the corpus
3525
+ * (`resolvedVia: "ecli-corpus"` / `"eli-corpus"`).
1352
3526
  */
1353
3527
  resolve(identifier: string, options?: CallOptions): Promise<ResolveResponse>;
1354
3528
  /**
1355
3529
  * `GET /documents/{celex}/versions` — version history, newest first,
1356
3530
  * current version included and flagged. 1 credit.
1357
3531
  */
1358
- listDocumentVersions(celex: string, params?: {
1359
- language?: string;
1360
- }, options?: CallOptions): Promise<DocumentVersionsResponse>;
3532
+ listDocumentVersions(celex: string, params?: VersionParams, options?: CallOptions): Promise<DocumentVersionsResponse>;
1361
3533
  /**
1362
3534
  * `GET /documents/{celex}/versions/{version}` — one immutable snapshot
1363
3535
  * including `parsedContent`. `corpusVersion` mirrors the
1364
3536
  * `X-Corpus-Version` response header. 1 credit.
1365
3537
  */
1366
- getDocumentVersion(celex: string, version: number, params?: {
1367
- language?: string;
1368
- }, options?: CallOptions): Promise<DocumentVersionResponse>;
3538
+ getDocumentVersion(celex: string, version: number, params?: VersionParams, options?: CallOptions): Promise<DocumentVersionResponse>;
1369
3539
  /**
1370
3540
  * `GET /documents/{celex}/at/{date}` — the snapshot LexAPI observed as
1371
3541
  * current on `date` (`YYYY-MM-DD`, end-of-day UTC inclusive). Dates
1372
3542
  * before the document entered the corpus reject with `NotFoundError`
1373
3543
  * carrying the tracking start date. 1 credit.
1374
3544
  */
1375
- getDocumentAtDate(celex: string, date: string, params?: {
1376
- language?: string;
1377
- }, options?: CallOptions): Promise<DocumentVersionResponse>;
3545
+ getDocumentAtDate(celex: string, date: string, params?: VersionParams, options?: CallOptions): Promise<DocumentVersionResponse>;
1378
3546
  /**
1379
3547
  * `POST /citations/extract` — crawl a document's EUR-Lex metadata page
1380
3548
  * for citations and persist them into the graph. Idempotent: an already
1381
- * processed document returns immediately with `alreadyExtracted: true`.
3549
+ * processed document returns `alreadyExtracted: true`. 5 credits,
3550
+ * refunded to 1 on `alreadyExtracted`.
1382
3551
  */
1383
3552
  extractCitations(celexNumber: string, options?: CallOptions): Promise<CitationExtractResponse>;
1384
3553
  /**
1385
3554
  * `GET /citations/cites/{celexNumber}` — documents this one cites
1386
3555
  * (outbound edges), grouped by target. The document must first have been
1387
- * crawled via `extractCitations` to appear here.
3556
+ * crawled via `extractCitations` to appear here. 1 credit.
3557
+ *
3558
+ * `celexNumber` may be a national document id (e.g. `AT-NOR-10001597`);
3559
+ * `params.includeNational` also pulls in national neighbours of live
3560
+ * jurisdictions — BUSINESS, SCALE and ENTERPRISE only (`403
3561
+ * TierForbiddenError` below that, refunded in full). A national id whose
3562
+ * jurisdiction is not live is `404 NotFoundError`.
3563
+ *
3564
+ * Filters (API 2.11.0): `citationType`, `provenance`, `jurisdictions` and
3565
+ * `resolution` each take one value or a list (sent comma-separated). On a
3566
+ * national id, `unresolved: true` also returns the references the
3567
+ * document records that could not be turned into an edge
3568
+ * (`unresolved` / `unresolvedTruncated`), at no extra cost.
1388
3569
  */
1389
- getCites(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): Promise<CitesResponse>;
3570
+ getCites(celexNumber: string, params?: CitesParams, options?: CallOptions): Promise<CitesResponse>;
1390
3571
  /**
1391
3572
  * `GET /citations/cited-by/{celexNumber}` — documents that cite this one
1392
- * (inbound edges), grouped by source.
3573
+ * (inbound edges), grouped by source. 1 credit. For legislation, inbound
3574
+ * amendment / corrigendum / repeal edges are refreshed from Cellar when
3575
+ * older than 7 days (waits ≤ ~2.5 s) — see `relationSync`.
3576
+ *
3577
+ * `celexNumber` may be a national document id; `params.includeNational`
3578
+ * also pulls in national neighbours of live jurisdictions — BUSINESS+
3579
+ * only (`403 TierForbiddenError` below that). Filters as on `getCites`.
1393
3580
  */
1394
3581
  getCitedBy(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): Promise<CitedByResponse>;
3582
+ /**
3583
+ * Walk every page of `getCites` (offset in edge rows) until a short or
3584
+ * empty page (SDK contract §1.4). Each page is a billed call (1 credit).
3585
+ * Edges are ordered by extraction time only, so edges extracted at the
3586
+ * same instant or during the walk can shift: an edge may repeat or be
3587
+ * missed. A target's edges can straddle a page boundary, so the same
3588
+ * `celexNumber` may appear in two consecutive pages — merge by
3589
+ * `celexNumber` if you need one group per document.
3590
+ */
3591
+ paginateCites(celexNumber: string, params?: CitesParams, options?: CallOptions): AsyncGenerator<CitesResponse, void>;
3592
+ /**
3593
+ * Walk every page of `getCitedBy` (offset in edge rows) until a short or
3594
+ * empty page (SDK contract §1.4). Each page is a billed call (1 credit);
3595
+ * edges may repeat or be missed if extractions happen during the walk. A source's edges can straddle a page boundary, so the same
3596
+ * `celexNumber` may appear in two consecutive pages.
3597
+ */
3598
+ paginateCitedBy(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): AsyncGenerator<CitedByResponse, void>;
1395
3599
  /**
1396
3600
  * `GET /citations/network/{celexNumber}` — inbound and outbound
1397
- * neighbourhood in one call, paginated per direction.
3601
+ * neighbourhood in one call, paginated per direction. 20 credits.
1398
3602
  *
1399
3603
  * If the server-side wall-clock budget expires the endpoint still
1400
3604
  * returns 200 with `partial: true`, an EMPTY `network`, and `null`
1401
3605
  * paging totals — check `partial` before treating the network as empty.
3606
+ *
3607
+ * `celexNumber` may be a national document id; `params.includeNational`
3608
+ * also pulls in national neighbours of live jurisdictions — BUSINESS+
3609
+ * only (`403 TierForbiddenError` below that). See `getCites`.
1402
3610
  */
1403
3611
  getCitationNetwork(celexNumber: string, params?: CitationNetworkParams, options?: CallOptions): Promise<CitationNetworkResponse>;
1404
3612
  /**
1405
3613
  * `GET /citations/path/{from}/{to}` — shortest citation path (BFS over
1406
- * outbound edges). `found: false` is a graceful HTTP 200, not an error.
1407
- * Default `maxDepth` 3 (max 8); the visited set is bounded to 5000 nodes.
3614
+ * outbound edges). 20 credits. `found: false` is a graceful HTTP 200,
3615
+ * not an error. Default `maxDepth` 3 (max 8); the visited set is bounded
3616
+ * to 5000 nodes.
3617
+ *
3618
+ * `from`/`to` may be national document ids; `params.includeNational` also
3619
+ * follows national documents of live jurisdictions along the way —
3620
+ * BUSINESS+ only (`403 TierForbiddenError` below that). See `getCites`.
1408
3621
  */
1409
- getCitationPath(from: string, to: string, params?: {
1410
- maxDepth?: number;
1411
- }, options?: CallOptions): Promise<CitationPathResponse>;
3622
+ getCitationPath(from: string, to: string, params?: CitationPathParams, options?: CallOptions): Promise<CitationPathResponse>;
1412
3623
  /**
1413
3624
  * `GET /citations/related/{celexNumber}` — bibliographic-coupling
1414
3625
  * neighbours (documents sharing the most outbound citation targets with
1415
- * the seed). Returns a graceful empty list with `message` when the seed
1416
- * has no outbound citations to couple on.
3626
+ * the seed). 20 credits. Returns a graceful empty list with `message`
3627
+ * when the seed has no outbound citations to couple on.
3628
+ *
3629
+ * `celexNumber` may be a national document id; `params.includeNational`
3630
+ * also considers national documents of live jurisdictions — BUSINESS+
3631
+ * only (`403 TierForbiddenError` below that). See `getCites`.
3632
+ */
3633
+ getRelatedDocuments(celexNumber: string, params?: RelatedDocumentsParams, options?: CallOptions): Promise<RelatedDocumentsResponse>;
3634
+ /**
3635
+ * `GET /citations/stats` — global citation graph statistics. 20 credits.
3636
+ *
3637
+ * `params.includeNational` also counts national documents of live
3638
+ * jurisdictions — BUSINESS+ only (`403 TierForbiddenError` below that).
3639
+ *
3640
+ * **Back-compat:** 0.2.0's signature was `getCitationStats(options?:
3641
+ * CallOptions)`. Both the single-argument form (`getCitationStats({
3642
+ * timeoutMs, signal })`) and the current two-argument form
3643
+ * (`getCitationStats(params, options)`) keep working — overloaded here so
3644
+ * TypeScript callers on either shape type-check, and a first argument
3645
+ * that looks like `CallOptions` rather than `CitationStatsParams` is also
3646
+ * detected at runtime (for a non-literal variable or a JS caller, which
3647
+ * the overloads alone can't catch) and honoured as the per-call options
3648
+ * rather than silently read as `params` with the timeout or abort signal
3649
+ * dropped.
1417
3650
  */
1418
- getRelatedDocuments(celexNumber: string, params?: {
1419
- limit?: number;
1420
- }, options?: CallOptions): Promise<RelatedDocumentsResponse>;
1421
- /** `GET /citations/stats` — global citation graph statistics. */
1422
3651
  getCitationStats(options?: CallOptions): Promise<CitationStatsResponse>;
3652
+ getCitationStats(params: CitationStatsParams, options?: CallOptions): Promise<CitationStatsResponse>;
3653
+ /**
3654
+ * `GET /citations/transposition/{celexNumber}` — the measures the member
3655
+ * states notified to the Commission for an EU act (CELEX sector 3),
3656
+ * grouped by country, from the Publications Office's Cellar records of the
3657
+ * notifications (API 2.11.0). **A notification is not a finding that the
3658
+ * measure transposes the act, or transposes it completely** — `note` says
3659
+ * so on every answer. 5 credits, every plan; a 5xx is refunded.
3660
+ *
3661
+ * On BUSINESS, SCALE and ENTERPRISE, for live jurisdictions, the answer
3662
+ * also says which measures LexAPI holds (`id`, `resolved`, `resolution`,
3663
+ * `resolutionBasis`, `counts.resolved`, `source.lanes`) and adds the
3664
+ * documents whose national source records that they transpose or
3665
+ * implement the act (`provenance: "source"`); `resolvedOnly: true` keeps
3666
+ * only the held ones. Below BUSINESS, for a jurisdiction that is not live,
3667
+ * and while the national-source terms are not accepted (`termsRequired:
3668
+ * true` — never a 403) those fields are `null`.
3669
+ *
3670
+ * A CELEX that is not an EU act (sector 3) is `404 NotFoundError`.
3671
+ */
3672
+ getTransposition(celexNumber: string, params?: TranspositionParams, options?: CallOptions): Promise<TranspositionResponse>;
3673
+ /**
3674
+ * `GET /citations/counterparts/{id}` — a national document's counterparts
3675
+ * in the other live jurisdictions, through the EU acts it transposes or
3676
+ * implements (API 2.11.0). Each `via[]` entry is one EU act, with the
3677
+ * other jurisdictions' measures for it ranked `1` (the national source
3678
+ * records the relation), `2` (a notified measure LexAPI holds) or `3` (a
3679
+ * notified Cellar record LexAPI does not hold, `id: null`). An EU act
3680
+ * CELEX as `id` lists its own measures the same way.
3681
+ *
3682
+ * **20 credits; BUSINESS, SCALE and ENTERPRISE only** (`403
3683
+ * TierForbiddenError` below that, refunded). A lookup past its 20-second
3684
+ * server-side budget throws `TimeoutError` (503, `err.partial === true`),
3685
+ * refunded. The SDK does not retry it (the same lookup would hit the same
3686
+ * budget); retry yourself, or narrow with `jurisdictions`.
3687
+ */
3688
+ getCounterparts(id: string, params?: CounterpartsParams, options?: CallOptions): Promise<CounterpartsResponse>;
3689
+ /**
3690
+ * `GET /national/coverage` — which jurisdictions are live, what each one
3691
+ * covers (legislation / case law, semantic search, sources with their
3692
+ * attribution), and when each was last synced. Public: no API key or
3693
+ * allowance required, free.
3694
+ */
3695
+ getNationalCoverage(options?: CallOptions): Promise<NationalCoverageResponse>;
3696
+ /**
3697
+ * `GET /{jurisdiction}/documents/{id}` — one national document by its
3698
+ * corpus id (e.g. `"AT-NOR-12345"`), analogous to `getDocument`.
3699
+ *
3700
+ * **Cost: 1 credit** — every national read is a corpus read (there is no
3701
+ * live-fetch fallback), so the 5-credit upfront reservation always
3702
+ * settles to 1 (an unknown id too). Check
3703
+ * `document.textAvailability.available` before reading `content`, and
3704
+ * always show `document.attribution` to the user alongside the text.
3705
+ * The document has one shape for every jurisdiction (API 2.8.0):
3706
+ * `documentKind` (`act` | `decision`), `decision` (court, chamber,
3707
+ * caseNumbers, citedNorms — `null` for acts; see `isNationalDecision`)
3708
+ * and the closed `content` key set.
3709
+ *
3710
+ * A document its source withdrew (a takedown, a pseudonymisation fix)
3711
+ * throws `DocumentWithdrawnError` (410) instead of answering — nothing of
3712
+ * it is served, not even the title; drop any copy you hold.
3713
+ */
3714
+ getNationalDocument(jurisdiction: string, id: string, params?: {
3715
+ language?: string;
3716
+ }, options?: CallOptions): Promise<NationalDocumentResponse>;
3717
+ /**
3718
+ * `GET /{jurisdiction}/documents` — browse a jurisdiction's corpus by
3719
+ * title (`q`), type, and in-force status. Newest-first by the document's
3720
+ * own date.
3721
+ *
3722
+ * **Cost: 3 credits per call** — flat; pagination does not multiply the
3723
+ * price, unlike `search`. **Paging:** `page` only reaches the first 1,000
3724
+ * rows (a 400 past that); page further with `cursor` (each response's
3725
+ * `nextCursor`), which works at any depth — see
3726
+ * `paginateNationalDocuments` for a ready-made walk. A slow page is a
3727
+ * retry-safe `TimeoutError` (504, refunded); the `total` count is capped
3728
+ * at 10,000 and flagged `totalExact: false` past that or on a slow count.
3729
+ */
3730
+ listNationalDocuments(jurisdiction: string, params?: NationalDocumentListParams, options?: CallOptions): Promise<NationalDocumentListResponse>;
3731
+ /**
3732
+ * Walk every page of `listNationalDocuments` via `cursor` (works past the
3733
+ * 1,000-row `page` ceiling, unlike passing `page` yourself). Each page is
3734
+ * a separate billed call. Stops after a page with `hasMore: false` (or an
3735
+ * empty page). Any `params.page` is ignored and never sent — pass
3736
+ * `params.cursor` only to resume a walk you saved partway through;
3737
+ * `page` together with `cursor` is a 400 ("Use either cursor or page,
3738
+ * not both"), so this strips `page` at runtime, not just in the type
3739
+ * (`Omit` alone only guards TypeScript callers — a JS caller, or one
3740
+ * using `as`, could otherwise still pass it through).
3741
+ */
3742
+ paginateNationalDocuments(jurisdiction: string, params?: Omit<NationalDocumentListParams, "page">, options?: CallOptions): AsyncGenerator<NationalDocumentListResponse, void>;
3743
+ /**
3744
+ * `POST /{jurisdiction}/search/semantic` — embedding-based semantic
3745
+ * search over a jurisdiction's case law. Same request/response shape as
3746
+ * `semanticSearch`, plus `jurisdiction`/`documentId`/`attribution` and
3747
+ * `document` (the matched decision as the listing returns it — the same
3748
+ * fields in every jurisdiction, API 2.8.0) on every hit.
3749
+ *
3750
+ * **Cost: a flat 5 credits** — `hyde` is accepted but never changes the
3751
+ * price or the billing tier here: the national index never rewrites, so
3752
+ * the response reports `hyde: false` (never `true`) when requested.
3753
+ */
3754
+ nationalSemanticSearch(jurisdiction: string, request: NationalSemanticCaseLawOptions, options?: CallOptions): Promise<NationalSemanticCaseLawResponse>;
3755
+ /**
3756
+ * `POST /{jurisdiction}/legislation/semantic` — embedding-based semantic
3757
+ * search over a jurisdiction's legislation; article-level matches. Same
3758
+ * shape as `semanticLegislationSearch`, plus `jurisdiction`/`documentId`/
3759
+ * `attribution` and `document` (the matched act's listing summary) on
3760
+ * every hit; the index fields (`law_title`, `article_ref`, `section`,
3761
+ * `language`, `in_force`, `valid_from`, `valid_to`, `law_type`) are
3762
+ * always present, `null` when the index has nothing (API 2.8.0). No `hyde`, no `asOf` — both are EU-only.
3763
+ * `NationalSemanticLegislationOptions` has no `hyde` field, and this SDK
3764
+ * never forwards one on this call even if a caller bypasses the type
3765
+ * system — the server now validates `hyde` as a boolean on this route too
3766
+ * (400 otherwise), so a stray non-boolean value would 400 for nothing.
3767
+ *
3768
+ * **Cost: 5 credits.**
3769
+ */
3770
+ nationalLegislationSemanticSearch(jurisdiction: string, request: NationalSemanticLegislationOptions, options?: CallOptions): Promise<NationalSemanticLegislationResponse>;
1423
3771
  /**
1424
3772
  * `POST /search/semantic` — embedding-based semantic search over CJEU
1425
3773
  * case law. Use this (not `search`) for *concept* queries; EUR-Lex
1426
3774
  * keyword matching is literal.
1427
3775
  *
1428
3776
  * **Billing:** 5 credits per call — **15 credits with `hyde: true`**
1429
- * (HyDE query rewriting: an LLM drafts the passage a relevant judgment
1430
- * would contain and retrieval fuses both rankings; ~1–3 s extra
1431
- * latency). HyDE is best-effort: on LLM failure the search falls back
1432
- * to plain retrieval, the response reports `hyde: false`, and the
1433
- * 10-credit premium is **refunded automatically** — verify via
1434
- * `credits.operation_weight`.
1435
- *
1436
- * The response exposes `hint` (present only on low-confidence,
1437
- * best-effort result sets — its presence is itself the signal), `hyde`
1438
- * (whether HyDE actually ran), and `hypotheticalDocument` (the drafted
1439
- * passage, present only when HyDE ran).
3777
+ * (HyDE query rewriting; ~1–3 s extra latency). HyDE is best-effort: on
3778
+ * LLM failure the search falls back to plain retrieval, the response
3779
+ * reports `hyde: false`, and the 10-credit premium is **refunded
3780
+ * automatically**.
1440
3781
  *
1441
- * Fewer results than `limit`? The upstream's ~0.7 default relevance
1442
- * floor cut in — pass `minScore: 0.5` (or `0`) to widen recall.
3782
+ * Hits carry a ~600-char `snippet` by default; `includeText: true`
3783
+ * returns the full text instead. `hint` is present only on
3784
+ * low-confidence result sets. Fewer results than `limit`? The ~0.7
3785
+ * default relevance floor cut in — pass `minScore: 0.5` (or `0`).
1443
3786
  *
1444
3787
  * Persistent document identity is `(metadata.celex_id,
1445
- * metadata.document_type)`; `case_id` is snapshot-scoped and does not
1446
- * survive index rebuilds.
3788
+ * metadata.document_type)`; `case_id` is snapshot-scoped.
1447
3789
  */
1448
3790
  semanticSearch(request: SemanticCaseLawSearchOptions, options?: CallOptions): Promise<SemanticCaseLawSearchResponse>;
1449
3791
  /**
1450
3792
  * `POST /legislation/semantic` — embedding-based semantic search over EU
1451
3793
  * legislation; results are article-level matches (`article_ref`,
1452
- * `law_id`, `law_title`, `score`).
3794
+ * `law_id`, `law_title`, `score`). `limit` is never above 50 here.
1453
3795
  *
1454
- * Costs 5 credits. The `hyde` option is case-law only and is therefore
1455
- * not accepted here (the server ignores it on this endpoint). The same
1456
- * ~0.7 default relevance floor applies — lower `minScore` to widen
1457
- * recall; `hint` is present only on low-confidence result sets.
3796
+ * **Consolidated texts:** when an act and its consolidated version match
3797
+ * the same article you get ONE hit — the consolidated article, labelled
3798
+ * `consolidated` / `consolidatedAsOf` / `baseCelex` / `consolidatedNote`,
3799
+ * with the authentic act's own match under `baseAct`. Consolidated texts
3800
+ * are not authentic; cite `baseCelex`.
3801
+ *
3802
+ * **`asOf` (YYYY-MM-DD):** each hit answers with the version in force on
3803
+ * that date (`asOfResolved`, `asOfVersion`, `matchedVersion`); a hit that
3804
+ * cannot be answered keeps its latest text with `asOfResolved: false` and
3805
+ * an `asOfReason`. The response adds `asOf` and `asOfSummary`.
3806
+ *
3807
+ * **Cost:** 5 credits for the search; with `asOf`, each live fetch of a
3808
+ * version the corpus does not hold reserves 5 and settles by outcome
3809
+ * (Cellar 4, browser 5, no text 1, failed 0) — at most 3 per request by
3810
+ * default. Corpus reads are free; an unaffordable fetch is skipped
3811
+ * (`insufficient_credits`), never a 402. The `hyde` option is case-law only.
1458
3812
  */
1459
- semanticLegislationSearch(request: SemanticSearchOptions, options?: CallOptions): Promise<SemanticLegislationSearchResponse>;
3813
+ semanticLegislationSearch(request: SemanticLegislationSearchOptions, options?: CallOptions): Promise<SemanticLegislationSearchResponse>;
1460
3814
  /**
1461
- * `GET /export` — stream matching corpus rows as NDJSON (BUSINESS tier;
1462
- * 402 `TierForbidden`/`CreditsExhausted`-style envelope otherwise).
3815
+ * `GET /export` — stream matching corpus rows as NDJSON (BUSINESS, SCALE
3816
+ * and ENTERPRISE; lower tiers get 403 `TierForbiddenError`). Metadata-only
3817
+ * rows are skipped unless `includeStubs: true`.
3818
+ *
3819
+ * Billing (credit plans, API 2.3.0): 1 credit per row written, at least 1
3820
+ * per export. The call is admitted for 1 credit, the matching rows are
3821
+ * counted, and the rest of 1 credit per row it can return is reserved; a
3822
+ * pool that cannot cover it throws `CreditsExhaustedError` before anything
3823
+ * streams. Unwritten rows are refunded when the stream ends; the settled
3824
+ * charge is `stream.done?.credits` (`charged`).
1463
3825
  *
1464
3826
  * Returns a single-pass async iterator over document rows. The leading
1465
3827
  * `_meta` envelope is parsed before this resolves (`stream.meta`); the
1466
- * trailing `_done` line is exposed as `stream.done` after iteration
1467
- * finishes — check `done.truncated` / `headers.truncated` to detect the
1468
- * server row cap (`X-Export-Truncated: 1`) instead of assuming the
1469
- * export was complete.
3828
+ * trailing `_done` line is exposed as `stream.done` after iteration —
3829
+ * check `stream.truncated` (`_done.truncated` once read; the header / `_meta`
3830
+ * hints before) to detect rows the export did not reach instead of assuming
3831
+ * it was complete.
1470
3832
  *
1471
3833
  * ```ts
1472
- * const stream = await client.export({ documentType: "regulation", limit: 1000 });
1473
- * console.log(stream.meta, stream.headers.total);
3834
+ * const stream = await client.export({ documentTypeCode: "regulation", limit: 1000 });
3835
+ * console.log(stream.meta?.totalMatching, stream.headers.total);
1474
3836
  * for await (const row of stream) process(row.celex, row.parsedContent);
1475
- * if (stream.done?.truncated) console.warn("row cap hit — paginate with fetchedSince");
3837
+ * if (stream.truncated) console.warn(`not every row reached (${stream.done?.truncatedBy}) — narrow the filters or resume with changedSince`);
1476
3838
  * ```
1477
3839
  */
1478
3840
  export(params?: ExportParams, options?: CallOptions): Promise<ExportStream>;
@@ -1486,10 +3848,10 @@ declare class LexAPI {
1486
3848
  interface CreditUsage {
1487
3849
  /**
1488
3850
  * Credits this specific request cost, mapped from
1489
- * `credits.operation_weight`. `0` for free operations such as `/info`;
1490
- * `undefined` when the account has no credit pool (legacy accounts).
3851
+ * `credits.operation_weight`. `0` for free operations such as `/info`
3852
+ * and for legacy accounts without a credit pool (SDK contract §1.5).
1491
3853
  */
1492
- unitsCharged: number | undefined;
3854
+ unitsCharged: number;
1493
3855
  /** `credits.remaining`, falling back to `usage.remaining`. */
1494
3856
  creditsRemaining: number | undefined;
1495
3857
  /** When the quota window resets — `credits.resetsAt` falling back to `usage.resetsAt`. */
@@ -1506,6 +3868,74 @@ interface CreditUsage {
1506
3868
  */
1507
3869
  declare function getCreditUsage(response: CreditedResponse): CreditUsage;
1508
3870
 
1509
- declare const VERSION = "0.1.0";
3871
+ /**
3872
+ * Verifying incoming LexAPI webhook deliveries.
3873
+ *
3874
+ * LexAPI signs every delivery with `X-Webhook-Signature`: the hex-encoded
3875
+ * HMAC-SHA256 of the raw request body, keyed with the webhook's `secret`.
3876
+ * Verify against the raw body bytes exactly as received — never a
3877
+ * re-serialised parse (key order / whitespace changes break the digest).
3878
+ *
3879
+ * The signature covers only the body and there is no nonce, so also enforce
3880
+ * a freshness window on the signed `timestamp` and dedupe on `delivery.id`.
3881
+ *
3882
+ * Uses the Web Crypto API (`crypto.subtle`), available in Node ≥ 18, Deno
3883
+ * and Bun — no dependency.
3884
+ */
3885
+ /** Header names LexAPI sends on deliveries (lower-case, as most frameworks expose them). */
3886
+ declare const WEBHOOK_SIGNATURE_HEADER = "x-webhook-signature";
3887
+ declare const WEBHOOK_DELIVERY_HEADER = "x-webhook-delivery";
3888
+ declare const WEBHOOK_ID_HEADER = "x-webhook-id";
3889
+ type WebhookBody = string | Uint8Array | ArrayBuffer;
3890
+ interface VerifyWebhookOptions {
3891
+ /**
3892
+ * Reject deliveries whose signed `timestamp` is further than this from
3893
+ * now (replay guard). Default 300 000 ms (5 minutes). `0` disables the check.
3894
+ */
3895
+ toleranceMs?: number;
3896
+ /** Clock override (testing). Default `Date.now()`. */
3897
+ now?: number;
3898
+ }
3899
+ /**
3900
+ * Thrown by {@link verifyWebhook} when a delivery fails verification,
3901
+ * and by every helper when the `secret` is empty (`missing_secret`).
3902
+ * `instanceof` works across the ESM and CommonJS builds (shared brand).
3903
+ */
3904
+ declare class WebhookSignatureError extends Error {
3905
+ readonly reason: "missing_secret" | "missing_signature" | "invalid_signature" | "malformed_body" | "stale_timestamp";
3906
+ static [Symbol.hasInstance](value: unknown): boolean;
3907
+ constructor(reason: WebhookSignatureError["reason"], message: string);
3908
+ }
3909
+ /** Compute the expected `X-Webhook-Signature` (hex HMAC-SHA256) for a raw body. */
3910
+ declare function computeSignature(rawBody: WebhookBody, secret: string): Promise<string>;
3911
+ /**
3912
+ * `true` when `signature` (the `X-Webhook-Signature` header) is the
3913
+ * HMAC-SHA256 of `rawBody` under `secret`. Constant-time comparison.
3914
+ * Signature only — use {@link verifyWebhook} to also check freshness.
3915
+ * Throws `WebhookSignatureError("missing_secret")` for an empty secret
3916
+ * (a configuration error, not a bad delivery).
3917
+ */
3918
+ declare function verifySignature(rawBody: WebhookBody, signature: string | null | undefined, secret: string): Promise<boolean>;
3919
+ /**
3920
+ * Verify a delivery and parse it into a typed {@link WebhookPayload}
3921
+ * (switch on `event`). Throws {@link WebhookSignatureError} on a missing
3922
+ * or invalid signature, a non-JSON body, or a `timestamp` outside
3923
+ * `toleranceMs` (default 5 minutes).
3924
+ *
3925
+ * ```ts
3926
+ * app.post("/lexapi-webhook", express.raw({ type: "application/json" }), async (req, res) => {
3927
+ * try {
3928
+ * const event = await verifyWebhook(req.body, req.get("x-webhook-signature"), secret);
3929
+ * if (event.event === "watchlist.changes") handle(event.data.changes);
3930
+ * res.sendStatus(200);
3931
+ * } catch {
3932
+ * res.sendStatus(401);
3933
+ * }
3934
+ * });
3935
+ * ```
3936
+ */
3937
+ declare function verifyWebhook(rawBody: WebhookBody, signature: string | null | undefined, secret: string, options?: VerifyWebhookOptions): Promise<WebhookPayload>;
3938
+
3939
+ declare const VERSION = "0.4.0";
1510
3940
 
1511
- export { type Annex, type Article, AuthenticationError, type Author, type BatchDocumentError, type CallOptions, type CitationEdgeDetail, type CitationEdgeParams, type CitationEdgeSummary, type CitationExtractResponse, type CitationNeighbour, type CitationNetworkParams, type CitationNetworkResponse, type CitationPathNode, type CitationPathResponse, type CitationStatsResponse, type CitationStatsTopCited, type CitationStatsTopCiting, type CitationType, type CitedByResponse, type CitedDocumentGroup, type CitesResponse, type CitingDocumentGroup, type CreditUsage, type CreditedResponse, 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 DocumentVersionResponse, type DocumentVersionsResponse, type Domain, type ErrorCode, type ExportDone, type ExportHeaderInfo, type ExportMeta, type ExportParams, type ExportRow, type ExportStream, type IdentifierType, type IncludeSelection, type IncludeToken, type InfoResponse, type InfoSearchFilters, InternalServerError, InvalidCelexError, InvalidParamsError, InvalidUrlError, type Language, LexAPI, LexAPIError, type LexAPIOptions, NetworkError, NotFoundError, type Procedure, RateLimitedError, type RecentDocumentsParams, type RecentDocumentsResponse, type Recital, type RelatedDocument, type RelatedDocumentsResponse, type ResolveResponse, type RetryOptions, type SearchRequest, type SearchResponse, type SearchResult, type Section, type SemanticCaseLawResult, type SemanticCaseLawSearchOptions, type SemanticCaseLawSearchResponse, type SemanticLanguage, type SemanticLegislationResult, type SemanticLegislationSearchResponse, type SemanticSearchOptions, type SemanticUsageInfo, type Subdomain, type SubscriptionInfo, type SubscriptionTier, type Table, type TextScope, TierForbiddenError, TimeoutError, UpstreamError, type UsageInfo, VERSION, type VersionEntry, type WebhookCreateRequest, type WebhookCreateResponse, type WebhookDeliveriesParams, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDetail, type WebhookListItem, type WebhookListResponse, type WebhookResponse, type WebhookStatus, type WebhookTestResponse, type WebhookUpdateRequest, type WebhookUpdateResponse, WebhooksAPI, getCreditUsage };
3941
+ export { AS_OF_REASONS, type AcceptLanguages, type Annex, type Article, 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 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 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, type NationalAllowanceExhaustedDetails, NationalAllowanceExhaustedError, type NationalArticle, 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 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, 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, isNationalDecision, normalizeRetryAfterSeconds, parseResponseHeaders, verifySignature, verifyWebhook };