@lexapi/client 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,3 +1,103 @@
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
+ /** Minimal `Headers` surface (works with polyfilled / injected fetch implementations). */
93
+ interface HeaderGetter {
94
+ get(name: string): string | null;
95
+ }
96
+ /** Parse the LexAPI headers off a fetch `Response` (or any `Headers`). */
97
+ declare function parseResponseHeaders(source: {
98
+ headers: HeaderGetter;
99
+ } | HeaderGetter): ResponseHeaders;
100
+
1
101
  /**
2
102
  * Typed errors mirroring the LexAPI error envelope:
3
103
  *
@@ -8,10 +108,21 @@
8
108
  * codes never crash the parser — the raw code string is preserved on the
9
109
  * base `LexAPIError` (forward compatibility).
10
110
  */
111
+
11
112
  /** 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 & {});
113
+ type ErrorCode = "NOT_FOUND" | "INVALID_CELEX" | "INVALID_URL" | "INVALID_PARAMS" | "RATE_LIMITED" | "QUOTA_EXHAUSTED" | "TIER_FORBIDDEN" | "CREDITS_EXHAUSTED" | "UPSTREAM_ERROR" | "TIMEOUT" | "INTERNAL" | "UNAUTHORIZED" | "SERVICE_UNAVAILABLE" | "CONNECTION_ERROR" | "REQUEST_TIMEOUT" | "ABORTED" | "INVALID_RESPONSE" | "INCOMPLETE_EXPORT" | (string & {});
114
+ /** Extra context attached to errors built from an HTTP response. */
115
+ interface LexAPIErrorContext {
116
+ /** The parsed JSON error body, verbatim (e.g. legacy `upgradeUrl`, `current`/`limit`). */
117
+ body?: unknown;
118
+ /** Parsed response headers (rate limits, source, …). */
119
+ headers?: ResponseHeaders;
120
+ }
13
121
  /** Base class for every error thrown by the SDK. */
14
122
  declare class LexAPIError extends Error {
123
+ /** Stable class tag used by the cross-build `instanceof` brand check. */
124
+ static readonly kind: string;
125
+ static [Symbol.hasInstance](value: unknown): boolean;
15
126
  /** Stable machine-readable code (`error.code`, or derived from the HTTP status for legacy bodies). */
16
127
  readonly code: ErrorCode;
17
128
  /** HTTP status. `0` for client-side failures (network error, client-side timeout). */
@@ -26,71 +137,198 @@ declare class LexAPIError extends Error {
26
137
  * normalized to a delta).
27
138
  */
28
139
  readonly retryAfter: number | undefined;
29
- constructor(code: ErrorCode, message: string, status: number, details?: unknown, retryAfter?: number);
140
+ /**
141
+ * The parsed JSON error body, verbatim. Useful for legacy-shape fields the
142
+ * typed properties don't cover (`upgradeUrl` on tier gates, `current` /
143
+ * `limit` on the webhook ceiling, `usage` on legacy quota 429s).
144
+ */
145
+ readonly body: unknown;
146
+ /** Parsed response headers, when the error came from an HTTP response. */
147
+ readonly headers: ResponseHeaders | undefined;
148
+ constructor(code: ErrorCode, message: string, status: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
30
149
  /**
31
150
  * Build the most specific error subclass for a non-2xx response.
32
151
  * Accepts both the typed envelope and the legacy bare `{error, message}` shape.
33
152
  */
34
- static fromResponse(status: number, body: unknown, headerRetryAfter?: number): LexAPIError;
153
+ static fromResponse(status: number, body: unknown, headerRetryAfter?: number, headers?: ResponseHeaders): LexAPIError;
35
154
  }
36
155
  /** 404 — document or resource missing (`NOT_FOUND`). */
37
156
  declare class NotFoundError extends LexAPIError {
38
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
157
+ static readonly kind: string;
158
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
39
159
  }
40
160
  /** 400 — CELEX failed validation (`INVALID_CELEX`). */
41
161
  declare class InvalidCelexError extends LexAPIError {
42
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
162
+ static readonly kind: string;
163
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
43
164
  }
44
165
  /** 400 — URL had no resolvable CELEX (`INVALID_URL`). */
45
166
  declare class InvalidUrlError extends LexAPIError {
46
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
167
+ static readonly kind: string;
168
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
47
169
  }
48
170
  /** 400 — missing or malformed params (`INVALID_PARAMS`). */
49
171
  declare class InvalidParamsError extends LexAPIError {
50
- 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);
51
174
  }
52
175
  /** 401 — missing, invalid, or revoked API key. */
53
176
  declare class AuthenticationError extends LexAPIError {
54
- 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);
55
179
  }
56
- /** 429 — quota or rate ceiling hit (`RATE_LIMITED`). Check `retryAfter`. */
180
+ /**
181
+ * 429 — per-minute rate limit (`RATE_LIMITED`), or, on legacy daily plans,
182
+ * the used-up daily / monthly-semantic quota (`QUOTA_EXHAUSTED`; `code`
183
+ * tells them apart). 429s use the legacy `{error, message, retryAfter}` body
184
+ * (with a top-level `code` from lex-api #304 on); the `Retry-After` header is
185
+ * authoritative and is what `retryAfter` reads first.
186
+ */
57
187
  declare class RateLimitedError extends LexAPIError {
58
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
188
+ static readonly kind: string;
189
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext, code?: "RATE_LIMITED" | "QUOTA_EXHAUSTED");
190
+ /** `RateLimit-*` headers from the 429 response (limit / remaining / reset seconds). */
191
+ get rateLimit(): RateLimitInfo | undefined;
192
+ /**
193
+ * `true` for a legacy-plan quota 429 (daily call quota, or the monthly
194
+ * semantic quota) rather than the per-minute limiter (SDK contract §1.2):
195
+ * `code` is `QUOTA_EXHAUSTED`, or — servers before lex-api #304, which
196
+ * send no code — the body carries `usage.resetsAt` with neither a
197
+ * `Retry-After` header nor a `retryAfter` body field. It cannot succeed
198
+ * before `resetsAt`, so the SDK does not retry it and `retryAfter` is
199
+ * `undefined`.
200
+ */
201
+ get quotaExhausted(): boolean;
202
+ /** When a legacy quota resets: the body's `resetsAt`, else `usage.resetsAt`. */
203
+ get resetsAt(): string | undefined;
59
204
  }
60
205
  /** 403 — tier-gated endpoint (`TIER_FORBIDDEN`). Retrying cannot help; upgrade the plan. */
61
206
  declare class TierForbiddenError extends LexAPIError {
62
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
207
+ static readonly kind: string;
208
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
209
+ }
210
+ /** `error.details` on a 402 `CREDITS_EXHAUSTED` envelope. */
211
+ interface CreditsExhaustedDetails {
212
+ /** The operation that was refused, e.g. `"semantic_case_law"`. */
213
+ operation?: string;
214
+ /** Its upfront credit weight (variable-priced operations are admitted against their upfront weight). */
215
+ weight?: number;
216
+ /** Credits left in the pool (monthly + top-up − used). `weight − available` is the shortfall. */
217
+ available?: number;
218
+ /** Monthly allowance. */
219
+ included?: number;
220
+ /** Top-up credits. */
221
+ topup?: number;
222
+ /** Credits used this window. */
223
+ used?: number;
224
+ /** When the monthly pool refills. */
225
+ resetsAt?: string | null;
226
+ [key: string]: unknown;
63
227
  }
64
- /** 402 — monthly credit pool exhausted (`CREDITS_EXHAUSTED`). Not retried. */
228
+ /**
229
+ * 402 — monthly credit pool (incl. top-ups) cannot cover the operation
230
+ * (`CREDITS_EXHAUSTED`). Not retried: wait for `resetsAt`, buy a top-up, or
231
+ * upgrade. A cheaper operation may still succeed — compare `weight` to `available`.
232
+ */
65
233
  declare class CreditsExhaustedError extends LexAPIError {
234
+ static readonly kind: string;
66
235
  /** When the monthly credit allowance resets (ISO date-time), when the server said so. */
67
236
  readonly resetsAt: string | undefined;
68
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number, resetsAt?: string);
237
+ /** Typed view of `error.details` (operation, weight, available, included, topup, used, resetsAt). */
238
+ readonly details: CreditsExhaustedDetails | undefined;
239
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, resetsAt?: string, context?: LexAPIErrorContext);
240
+ /** The refused operation's credit weight (`details.weight`). */
241
+ get weight(): number | undefined;
242
+ /** Credits left in the pool (`details.available`). */
243
+ get available(): number | undefined;
244
+ /** The refused operation (`details.operation`). */
245
+ get operation(): string | undefined;
69
246
  }
70
247
  /** 502 — EUR-Lex returned an error (`UPSTREAM_ERROR`). Retry-safe on GETs. */
71
248
  declare class UpstreamError extends LexAPIError {
72
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
249
+ static readonly kind: string;
250
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
73
251
  }
74
252
  /**
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.
253
+ * A timeout. Two cases, told apart by `code` / `status`:
254
+ * - `TIMEOUT` (504, 524): the server or Cloudflare gave up on the upstream.
255
+ * - `REQUEST_TIMEOUT` (`status === 0`): the SDK's own response timeout —
256
+ * no bytes for `timeoutMs` (SDK contract §1.6).
78
257
  */
79
258
  declare class TimeoutError extends LexAPIError {
80
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
259
+ static readonly kind: string;
260
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
261
+ }
262
+ /**
263
+ * 503 — service temporarily unavailable (e.g. a deploy's drain window).
264
+ * Derived from the status (no typed code). Retried like 502/504.
265
+ */
266
+ declare class ServiceUnavailableError extends LexAPIError {
267
+ static readonly kind: string;
268
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
81
269
  }
82
270
  /** 500 — unexpected server failure (`INTERNAL`). Not retried by default. */
83
271
  declare class InternalServerError extends LexAPIError {
84
- constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
272
+ static readonly kind: string;
273
+ constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
85
274
  }
86
275
  /** Transport-level failure: DNS, connection reset, etc. No HTTP response was received. */
87
276
  declare class NetworkError extends LexAPIError {
277
+ static readonly kind: string;
88
278
  readonly cause: unknown;
89
279
  constructor(message: string, cause?: unknown);
90
280
  }
281
+ /** The caller's `AbortSignal` fired (status 0). Never retried. `cause` is the signal's reason. */
282
+ declare class RequestAbortedError extends LexAPIError {
283
+ static readonly kind: string;
284
+ readonly cause: unknown;
285
+ constructor(message: string, cause?: unknown);
286
+ }
287
+ /**
288
+ * A 2xx response whose body was not the JSON LexAPI sends (e.g. an HTML page
289
+ * from a proxy). `body` holds the first 500 characters of the raw text.
290
+ */
291
+ declare class InvalidResponseError extends LexAPIError {
292
+ static readonly kind: string;
293
+ constructor(message: string, status: number, rawText?: string, context?: LexAPIErrorContext);
294
+ }
295
+ /**
296
+ * An export stream ended (cleanly, at EOF) without its trailing `_done` line —
297
+ * the server stopped mid-export (SDK contract §1.8). Raised after the rows
298
+ * that did arrive were yielded; they are NOT a complete export.
299
+ */
300
+ declare class IncompleteExportError extends LexAPIError {
301
+ static readonly kind: string;
302
+ /** Rows yielded before the stream ended. */
303
+ readonly rowsRead: number;
304
+ /**
305
+ * @param details the server's `_error` line body (`{ code, message }`) when
306
+ * one arrived; `undefined` for a missing or `complete: false` trailer.
307
+ */
308
+ constructor(message: string, rowsRead: number, details?: unknown);
309
+ }
310
+ /**
311
+ * `true` for any error thrown by this SDK — from either build (ESM or
312
+ * CommonJS) or another installed copy. Pass a class to narrow:
313
+ * `isLexAPIError(err, NotFoundError)`.
314
+ */
315
+ declare function isLexAPIError<T extends LexAPIError = LexAPIError>(value: unknown, errorClass?: abstract new (...args: never[]) => T): value is T;
316
+ /**
317
+ * Normalize a JSON `retryAfter` body value. The field historically carried
318
+ * buggy absolute epoch values instead of delta-seconds (pending server fix);
319
+ * epoch-looking values are converted to a non-negative delta in seconds.
320
+ */
321
+ declare function normalizeRetryAfterSeconds(value: number): number;
91
322
 
92
323
  declare const DEFAULT_BASE_URL = "https://lex-api.com/api/v1";
93
- declare const DEFAULT_TIMEOUT_MS = 60000;
324
+ /**
325
+ * 95 s per attempt: above the 90 s hard timeout the API puts on a single live
326
+ * EUR-Lex fetch (so such a fetch ends in the server's typed, refunded 504
327
+ * rather than a client abort that may still be billed), and below
328
+ * Cloudflare's 100 s proxy timeout. A request that runs several upstream
329
+ * fetches (Cellar, then the browser; a batch) can still exceed it.
330
+ */
331
+ declare const DEFAULT_TIMEOUT_MS = 95000;
94
332
  /** Retry policy knobs (SDK contract §1.2). */
95
333
  interface RetryOptions {
96
334
  /** Max retries after the initial attempt. Default 3. Set 0 to disable retries. */
@@ -99,6 +337,17 @@ interface RetryOptions {
99
337
  baseDelayMs?: number;
100
338
  /** Cap on any single wait (computed or server-directed). Default 30 000 ms. */
101
339
  maxDelayMs?: number;
340
+ /**
341
+ * SDK contract §1.2 opt-in (default `false`): also retry the eight
342
+ * read-only POSTs (`search`, `getDocument`, `getDocumentsBatch`,
343
+ * `getDocumentByUrl`, `getDocumentMetadata`, `resolve`, `semanticSearch`,
344
+ * `semanticLegislationSearch`) on an **app-origin** 502/503/504 — those
345
+ * are refunded in full, so the retry is billing-safe. App-origin = a
346
+ * non-empty `X-LexAPI-Version` or a `RateLimit-Limit` header; anything
347
+ * else is treated as a proxy answer and never retried on a billed call. Never applies to mutating calls (webhook
348
+ * writes, `extractCitations`).
349
+ */
350
+ retryReadOnlyPosts?: boolean;
102
351
  }
103
352
  interface HttpClientOptions {
104
353
  apiKey: string;
@@ -108,57 +357,100 @@ interface HttpClientOptions {
108
357
  retry: Required<RetryOptions>;
109
358
  userAgentSuffix?: string | undefined;
110
359
  }
111
- type QueryParams = Record<string, string | number | boolean | undefined>;
360
+ /** Query values; arrays are sent as repeated parameters (`?a=x&a=y`). */
361
+ type QueryParams = Record<string, string | number | boolean | undefined | ReadonlyArray<string | number | boolean>>;
112
362
  interface RequestOptions {
113
363
  method: "GET" | "POST" | "PUT" | "DELETE";
114
364
  path: string;
115
365
  query?: QueryParams;
116
366
  body?: unknown;
117
- /** Per-call timeout override. */
367
+ /** Per-call timeout override (per attempt, covering the response body). */
118
368
  timeoutMs?: number | undefined;
369
+ /** Caller cancellation: aborts the in-flight attempt and any retry wait. */
370
+ signal?: AbortSignal | undefined;
371
+ /** `Accept` header override (default `application/json`). */
372
+ accept?: string;
373
+ /**
374
+ * One of the eight read-only POSTs of SDK contract §1.2 — retried on
375
+ * app-origin 502/503/504 when `retryReadOnlyPosts` is on.
376
+ */
377
+ idempotent?: boolean;
378
+ /**
379
+ * A free operation (0 credits: `/info`, webhook reads). A retry cannot
380
+ * charge, so proxy-origin 5xx/520/524 and post-send transport errors are
381
+ * retried too (SDK contract §1.2).
382
+ */
383
+ free?: boolean;
119
384
  }
385
+ declare const INSPECT: unique symbol;
120
386
  /**
121
387
  * Single request core used by every SDK method.
122
388
  *
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.
389
+ * - `x-api-key` auth + `User-Agent: lexapi-typescript/<version>` on every
390
+ * request (UA omitted on browser runtimes, where it cannot be set). The key
391
+ * lives in a private field and never appears in `util.inspect`,
392
+ * `console.log` or `JSON.stringify` output.
393
+ * - One inactivity timeout per attempt (SDK contract §1.6): it runs until
394
+ * the response head arrives and restarts on every body chunk, for JSON
395
+ * bodies and export streams alike.
396
+ * - Caller `AbortSignal`: aborts the attempt and any retry wait; throws
397
+ * `RequestAbortedError`, never retried.
398
+ * - Retries follow the billing-safety rule of SDK contract §1.2 — only when
399
+ * a retry cannot charge twice (see `shouldRetryStatus` and PLAN.md §1.2).
400
+ * - Server-directed waits: `Retry-After` on any status; on a 429 only, then
401
+ * `RateLimit-Reset` and the JSON `retryAfter` field. `X-RateLimit-*` is
402
+ * never read.
134
403
  */
135
404
  declare class HttpClient {
405
+ #private;
136
406
  private readonly opts;
137
407
  private readonly userAgent;
138
408
  constructor(opts: HttpClientOptions);
139
- /** Perform a request and parse the JSON body (204 yields `undefined`). */
409
+ /** API base URL. */
410
+ get baseUrl(): string;
411
+ /** Client-level per-attempt timeout (ms). */
412
+ get timeoutMs(): number;
413
+ /** Redacted view for `JSON.stringify` — never includes the API key. */
414
+ toJSON(): Record<string, unknown>;
415
+ /** Redacted view for `util.inspect` / `console.log`. */
416
+ [INSPECT](): string;
417
+ /** Perform a request and parse the JSON body (204 / empty body yields `{}`). */
140
418
  requestJson<T>(options: RequestOptions): Promise<T>;
141
- /** Like `requestJson`, but also exposes the raw `Response` (for header signals). */
419
+ /**
420
+ * Like `requestJson`, but also exposes the raw `Response` (for header
421
+ * signals). The body is read inside the attempt, under its timeout.
422
+ */
142
423
  requestJsonWithResponse<T>(options: RequestOptions): Promise<{
143
424
  data: T;
144
425
  response: Response;
145
426
  }>;
146
427
  /**
147
428
  * 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.
429
+ * consuming the body (streaming endpoints such as `/export`). The attempt
430
+ * timeout covers only the response headers; the caller applies its own
431
+ * idle timeout to body reads. Non-2xx responses are parsed and thrown as
432
+ * typed errors; the retry policy applies before the first body byte.
151
433
  */
152
434
  requestRaw(options: RequestOptions): Promise<Response>;
153
- private fetchWithTimeout;
435
+ private execute;
154
436
  }
155
437
 
156
438
  /**
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.
439
+ * Hand-curated types mirroring LexAPI's `openapi.yaml` (LexAPI 2.0.0) and
440
+ * `docs.md`, cross-checked against the server's controllers.
441
+ *
442
+ * Validated against: lex-api `main` @ 633eb67 (2026-10-26, PR #298).
443
+ *
444
+ * Conventions:
445
+ * - `type: [X, 'null']` becomes `X | null`; properties outside a `required`
446
+ * list are optional.
447
+ * - Open string enums (`"a" | "b" | (string & {})`) are used where the server
448
+ * may add values (forward compatibility) — known values still autocomplete.
449
+ * - Fields the SDK adds from response headers are documented as "SDK-added".
160
450
  */
161
- type SubscriptionTier = "FREE" | "STARTER" | "PROFESSIONAL" | "BUSINESS" | "ENTERPRISE";
451
+
452
+ /** Subscription tiers. `SCALE` was added with the 2026-07 pricing. */
453
+ type SubscriptionTier = "FREE" | "STARTER" | "PROFESSIONAL" | "BUSINESS" | "SCALE" | "ENTERPRISE" | (string & {});
162
454
  /** ISO 639-1 code (24 official EU languages). */
163
455
  type Language = "en" | "fr" | "de" | "es" | "it" | "pl" | "nl" | "pt" | "ro" | "bg" | "cs" | "da" | "el" | "et" | "fi" | "ga" | "hr" | "hu" | "lt" | "lv" | "mt" | "sk" | "sl" | "sv";
164
456
  type Domain = "EU_LAW" | "NATIONAL_LAW" | "ALL";
@@ -168,32 +460,39 @@ type DocumentType = "judgment" | "opinion" | "order" | "regulation" | "directive
168
460
  type Author = "commission" | "council" | "parliament" | "court-of-justice" | "general-court" | "ecb" | "eca" | "eesc" | "cor" | "ema" | "efsa";
169
461
  type Procedure = "ordinary" | "codecision" | "consent" | "consultation" | "budget" | "implementing" | "delegated" | "comitology" | "appointment" | "non-legislative";
170
462
  type TextScope = "title" | "text" | "title-text" | "any";
463
+ /** A single value or a list of values (the API accepts both on list filters). */
464
+ type OneOrMany<T> = T | T[];
171
465
  interface SubscriptionInfo {
172
466
  tier?: SubscriptionTier;
173
467
  maxPages?: number;
174
468
  maxBatchSize?: number;
175
469
  maxWebhooks?: number;
470
+ /** Semantic endpoints only: the effective result cap for this call. */
471
+ maxResults?: number;
176
472
  /** `credits` = monthly credit pool (pricing v2); `daily` = legacy daily-call model. */
177
473
  pricingMode?: "credits" | "daily";
178
474
  /** Legacy daily-call ceiling. `null` for credit-pool (v2) accounts. */
179
475
  dailyLimit?: number | null;
180
476
  /** Monthly credit allowance. `null` for legacy daily-call accounts. */
181
477
  monthlyCredits?: number | null;
182
- /** e.g. "120 requests/minute" */
478
+ /** e.g. `"120 requests/minute"`. `"0 requests/minute"` means unlimited (hand-priced plans). */
183
479
  rateLimit?: string;
184
480
  }
185
481
  /**
186
482
  * Caller's current usage counters at request time. Dual-mode: credits over
187
483
  * the monthly window for v2 accounts, API calls for the day on legacy
188
- * accounts — read `unit` to disambiguate.
484
+ * accounts. Prefer the richer `credits` block on v2 responses.
189
485
  */
190
486
  interface UsageInfo {
191
487
  current?: number;
192
488
  limit?: number;
193
489
  remaining?: number;
490
+ /** Documented by the spec; not currently emitted by the server. */
194
491
  unit?: "credits" | "calls";
195
492
  /** When the counter resets (ISO date-time). */
196
- resetsAt?: string;
493
+ resetsAt?: string | null;
494
+ /** Legacy daily-call plans only: calls this request counted (always 1). */
495
+ unitsCharged?: number;
197
496
  }
198
497
  /**
199
498
  * Pricing-v2 credit-pool state. Present on responses for credit-pool
@@ -201,7 +500,12 @@ interface UsageInfo {
201
500
  * daily-call accounts.
202
501
  */
203
502
  interface CreditsInfo {
204
- /** Credits this specific request cost (0 for free operations such as /info). */
503
+ /**
504
+ * Credits this request cost (0 for free operations such as /info). On
505
+ * operations that settle by source (document reads, searches, HyDE, asOf
506
+ * fetches) refunds are applied after the response is sent, so this can
507
+ * show the upfront charge; the next call's envelope reflects the refund.
508
+ */
205
509
  operation_weight?: number;
206
510
  /** Credits used in the current monthly window. */
207
511
  current?: number;
@@ -221,6 +525,14 @@ interface CreditedResponse {
221
525
  usage?: UsageInfo;
222
526
  credits?: CreditsInfo;
223
527
  }
528
+ /**
529
+ * Parsed response headers attached by the SDK to every JSON response
530
+ * (`result.headers`). See {@link ResponseHeaders}.
531
+ */
532
+ interface WithResponseHeaders {
533
+ /** SDK-added: parsed LexAPI response headers (source, rate limits, warnings, …). */
534
+ headers?: ResponseHeaders;
535
+ }
224
536
  interface InfoSearchFilters {
225
537
  textScope?: TextScope[];
226
538
  domain?: Domain[];
@@ -229,7 +541,7 @@ interface InfoSearchFilters {
229
541
  author?: Author[];
230
542
  procedure?: Procedure[];
231
543
  }
232
- interface InfoResponse extends CreditedResponse {
544
+ interface InfoResponse extends CreditedResponse, WithResponseHeaders {
233
545
  service?: string;
234
546
  version?: string;
235
547
  description?: string;
@@ -241,17 +553,21 @@ interface InfoResponse extends CreditedResponse {
241
553
  /**
242
554
  * `include` / `fields` token. The spec's enum lists
243
555
  * metadata/fullText/articles/recitals/sections/tables/annexes; the
244
- * `DocumentContent` description additionally documents `paragraphs` as
245
- * part of the accepted include set.
556
+ * `DocumentContent` description additionally documents `paragraphs`.
246
557
  */
247
558
  type IncludeToken = "metadata" | "fullText" | "articles" | "recitals" | "paragraphs" | "sections" | "tables" | "annexes";
248
559
  /** Array form, or a comma-separated string like `"metadata,articles"`. */
249
560
  type IncludeSelection = IncludeToken[] | string;
561
+ /**
562
+ * Opt-in language fallback for documents with no text in the requested
563
+ * language: an ordered list of ISO codes the caller can consume, or `"any"`.
564
+ */
565
+ type AcceptLanguages = Language[] | "any";
250
566
  /** A top-level article extracted from the document body. */
251
567
  interface Article {
252
- /** Stable id from the EUR-Lex `eli-subdivision` (e.g. `art_17`). */
568
+ /** Stable id (e.g. `art_17`, `art_6a` for an inserted article). */
253
569
  id?: string;
254
- /** e.g. `"Article 17"` */
570
+ /** e.g. `"Article 17"` — the heading as published. */
255
571
  number: string;
256
572
  title?: string | null;
257
573
  /** Plain-text body of the article (paragraphs joined). */
@@ -264,13 +580,16 @@ interface Article {
264
580
  */
265
581
  interface Section {
266
582
  type: "chapter" | "section";
267
- number: string;
268
- title: string;
583
+ /** `null` for an unnumbered section heading. */
584
+ number: string | null;
585
+ /** `null` when the heading has no title text. */
586
+ title: string | null;
269
587
  articleRange?: [string, string] | null;
270
588
  }
271
589
  /** Preamble recital — also the element type of `paragraphs[]` (numbered prose). */
272
590
  interface Recital {
273
- number: number;
591
+ /** `null` when the recital's number could not be read from the markup. */
592
+ number: number | null;
274
593
  text: string;
275
594
  }
276
595
  interface Annex {
@@ -285,21 +604,60 @@ interface Table {
285
604
  /**
286
605
  * Structured document body. Case-law CELEXes (sector 6) emit numbered
287
606
  * 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.
607
+ * `recitals[]`. With `include`/`fields` selection any key can be omitted.
290
608
  */
291
609
  interface DocumentContent {
292
610
  fullText?: string;
293
611
  articles?: Article[];
294
612
  /** Legislative preamble recitals. Empty `[]` on case-law — see `paragraphs`. */
295
613
  recitals?: Recital[];
296
- /** Judgment grounds (case-law) or fullText splits when no structured extractor matched. */
614
+ /** Judgment grounds (case-law), text outside articles, or fullText splits. */
297
615
  paragraphs?: Recital[];
298
616
  sections?: Section[];
299
617
  /** Genuine data tables only (layout-table noise is filtered out server-side). */
300
618
  tables?: Table[];
301
619
  annexes?: Annex[];
302
620
  }
621
+ /** Why a document response carries no text. */
622
+ type TextUnavailableReason = "not_in_language" | "not_published_yet" | "no_machine_readable_rendition" | "too_large" | "unknown" | (string & {});
623
+ /** Pointer to a consolidated version (CONSLEG, CELEX sector 0) of a base act. */
624
+ interface ConsolidatedVersionHint {
625
+ /** e.g. `"02006R1907-20260622"` — pass back to `getDocument` (a normal, separately charged read). */
626
+ celex: string;
627
+ /** Consolidation date (`YYYY-MM-DD`), from the CELEX suffix. */
628
+ date: string;
629
+ /** `cellar` — Publications Office list; `corpus` — Cellar was unreachable, newest version LexAPI holds. */
630
+ source: "cellar" | "corpus" | (string & {});
631
+ /** `newestConsolidated` only — lower-case ISO codes the version exists in. */
632
+ availableLanguages?: string[];
633
+ }
634
+ /**
635
+ * Whether a document response carries its text, and if not, why. Present on
636
+ * every document response. A text-unavailable document is a `200` with
637
+ * metadata and `content: null` (billed 1 credit), not a 404.
638
+ */
639
+ interface TextAvailability {
640
+ available: boolean;
641
+ /** Absent when `available` is true. */
642
+ reason?: TextUnavailableReason;
643
+ retryable?: boolean;
644
+ /**
645
+ * ISO codes whose text could be served. `null` = unknown; `[]` = known to
646
+ * be none. Those are different facts — do not collapse them.
647
+ */
648
+ availableLanguages?: string[] | null;
649
+ /** Where EUR-Lex itself points for the text (e.g. the European Parliament site). */
650
+ externalSource?: string;
651
+ /** e.g. `"cellar-manifestations"`, `"parse-worker"` (our own `too_large` verdict). */
652
+ source?: string;
653
+ checkedAt?: string;
654
+ /** Base acts only: newest consolidated version dated on or before today, in the requested language. */
655
+ latestConsolidated?: ConsolidatedVersionHint;
656
+ /** Base acts only: the next consolidated version dated after today, in the requested language. */
657
+ upcomingConsolidated?: ConsolidatedVersionHint;
658
+ /** Base acts only: the newest consolidated version when it has NO text in the requested language. */
659
+ newestConsolidated?: ConsolidatedVersionHint;
660
+ }
303
661
  /** Normalized metadata for a single document. */
304
662
  interface DocumentMetadata {
305
663
  /** Canonical CELEX. Always present on metadata responses. */
@@ -308,11 +666,18 @@ interface DocumentMetadata {
308
666
  celexNumber?: string;
309
667
  /** `null` when the document is genuinely sparse — never `"Unknown Title"`. */
310
668
  title?: string | null;
669
+ /**
670
+ * Present only when `title` is NOT in the requested language: the ISO
671
+ * 639-1 code of the language it is in (`en` for the English fallback).
672
+ * Absent means the title is in the requested language.
673
+ */
674
+ titleLanguage?: string;
311
675
  /** Prose form of the document, e.g. `"Regulation"`. */
312
676
  documentType?: string | null;
313
677
  /** Stable enum slug for `documentType` (e.g. `"regulation"`). */
314
678
  documentTypeCode?: DocumentTypeCode | null;
315
- author?: string;
679
+ /** `null` for placeholder authors (e.g. consolidated texts' "Provisional data"). */
680
+ author?: string | null;
316
681
  /** Legacy DD/MM/YYYY string as published by EUR-Lex. Prefer `dateOfDocumentISO`. */
317
682
  dateOfDocument?: string | null;
318
683
  /** ISO-8601 date parsed from `dateOfDocument`. */
@@ -337,40 +702,59 @@ interface DocumentMetadata {
337
702
  directoryCodes?: string[];
338
703
  subject?: string[];
339
704
  }
705
+ /** Canonical EUR-Lex URLs for a document. */
706
+ interface DocumentUrls {
707
+ html?: string;
708
+ metadata?: string;
709
+ pdf?: string;
710
+ xml?: string;
711
+ }
340
712
  /** Fully-parsed document: metadata + structured content. */
341
713
  interface Document extends DocumentMetadata {
342
714
  /** ISO code of the language rendition actually served. */
343
715
  language?: string;
344
716
  /** Present only on a fallback — the language originally requested. */
345
717
  languageRequested?: string;
346
- /** Present only on a fallback — the language served instead (`en`). */
718
+ /** Present only on a fallback — the language served instead. */
347
719
  languageFallback?: string;
348
- content?: DocumentContent;
349
- urls?: {
350
- html?: string;
351
- metadata?: string;
352
- };
720
+ /**
721
+ * `null` when EUR-Lex publishes this document's notice but not its text —
722
+ * check `textAvailability.available` before reading it.
723
+ */
724
+ content?: DocumentContent | null;
725
+ /** Present on every document response. */
726
+ textAvailability?: TextAvailability;
727
+ urls?: DocumentUrls;
728
+ fetchedAt?: string;
729
+ /** Monotonic corpus version of this CELEX (corpus-served documents). */
730
+ version?: number;
353
731
  }
354
732
  /**
355
733
  * Response-side document-type slug. The spec enumerates the known values,
356
734
  * but unknown prose is slugified server-side (e.g. `staff working document`
357
735
  * → `staff_working_document`), so unknown strings must be tolerated.
358
736
  */
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 & {});
737
+ 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
738
  /** A single entry in a search results page. */
361
739
  interface SearchResult {
362
740
  /** Title with HTML entities decoded and sentence-spacing restored. */
363
741
  title?: string;
364
- /** Legacy field. Same value as `celex`. */
742
+ /** Legacy field. Same value as `celex`. May be `""` for rare listings without a parseable CELEX. */
365
743
  celexNumber?: string;
366
- /** Canonical CELEX alias. */
367
- celex?: string;
744
+ /** Canonical CELEX alias. `null` for rare listings without a parseable CELEX. */
745
+ celex?: string | null;
368
746
  /** Legacy field. Same value as `documentType`. */
369
747
  form?: string | null;
370
748
  documentType?: string | null;
371
749
  documentTypeCode?: DocumentTypeCode | null;
372
750
  date?: string;
751
+ dateOfDocument?: string | null;
373
752
  dateOfDocumentISO?: string | null;
753
+ /** Qualifier EUR-Lex appends to the date (e.g. `"Date of signature"`). */
754
+ dateType?: string | null;
755
+ ecli?: string | null;
756
+ /** EUR-Lex internal reference number, when listed. */
757
+ internalNumber?: string | null;
374
758
  author?: string | null;
375
759
  /**
376
760
  * Upper-case 2-letter ISO codes the document is published in. Empty `[]`
@@ -385,29 +769,43 @@ interface SearchResult {
385
769
  * is required — a completely empty body fails with 400.
386
770
  */
387
771
  interface SearchRequest {
388
- /** Free-text search. Prefer 1–3 distinctive terms; quotes force exact-phrase matching. */
772
+ /**
773
+ * Free-text search. Prefer 1–3 distinctive terms; quotes force
774
+ * exact-phrase matching. `"*"` (or only wildcard/quote characters) means
775
+ * no text constraint — a filter-only search.
776
+ */
389
777
  query?: string;
778
+ /** Bypass the 60-minute result cache and re-fetch from EUR-Lex. Same price. Default `false`. */
779
+ fresh?: boolean;
390
780
  textScope?: TextScope;
391
781
  dateFrom?: string;
392
782
  dateTo?: string;
393
783
  year?: number | number[];
394
784
  month?: number | number[];
395
785
  /** 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[];
786
+ documentType?: OneOrMany<DocumentType>;
787
+ author?: OneOrMany<Author>;
788
+ procedure?: OneOrMany<Procedure>;
399
789
  domain?: Domain;
400
- subdomain?: Subdomain | Subdomain[];
790
+ /**
791
+ * One subdomain or several. Several are ORed when the EUR-Lex web service
792
+ * answers (`headers.searchSource === "soap"`, the normal path). If the
793
+ * search falls back to EUR-Lex result pages (no `searchSource`), EUR-Lex
794
+ * applies only the FIRST subdomain; the Cellar listing fallback does not
795
+ * take several at all. Pass one subdomain when the result set must be exact.
796
+ */
797
+ subdomain?: OneOrMany<Subdomain>;
401
798
  language?: Language;
402
799
  /**
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`).
800
+ * EUR-Lex result pages to fetch (3 credits per page, unfetched pages
801
+ * refunded). Clamped to the subscription tier (FREE=1, STARTER=5,
802
+ * PROFESSIONAL=20, BUSINESS/SCALE/ENTERPRISE=100); if clamped, the response
803
+ * carries an `X-Warning` header (surfaced as `xWarning`).
406
804
  */
407
805
  maxPages?: number;
408
806
  }
409
- interface SearchResponse extends CreditedResponse {
410
- searchParameters?: SearchRequest;
807
+ interface SearchResponse extends CreditedResponse, WithResponseHeaders {
808
+ searchParameters?: Omit<SearchRequest, "fresh" | "maxPages">;
411
809
  /** Total matching documents on EUR-Lex. */
412
810
  totalResults?: number;
413
811
  /** Total result pages available on EUR-Lex. */
@@ -416,6 +814,17 @@ interface SearchResponse extends CreditedResponse {
416
814
  /** Number of results in this response. */
417
815
  resultCount?: number;
418
816
  results?: SearchResult[];
817
+ /**
818
+ * Present only when the search returned nothing: routes the caller to
819
+ * semantic search (EUR-Lex keyword search is literal).
820
+ */
821
+ hint?: string;
822
+ /**
823
+ * `"corpus"` when EUR-Lex was unreachable and the answer came from the
824
+ * LexAPI corpus mirror — always with `partial: true` (possibly incomplete,
825
+ * title-only text matching).
826
+ */
827
+ source?: "corpus" | (string & {});
419
828
  /**
420
829
  * Present and `true` when the result set was capped by the tier
421
830
  * `maxPages` limit and more pages exist on EUR-Lex. Check
@@ -427,65 +836,73 @@ interface SearchResponse extends CreditedResponse {
427
836
  truncatedReason?: string;
428
837
  /**
429
838
  * 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`.
839
+ * requested pages, or the answer came from the corpus fallback. Check
840
+ * `partialReason`.
432
841
  */
433
842
  partial?: boolean;
434
843
  partialReason?: string;
435
844
  /**
436
845
  * 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.
846
+ * rows (`author`, `date`). `"date"` signals the recall-vs-pagination
847
+ * trade-off: raise `maxPages` to widen recall on tight date filters.
440
848
  */
441
849
  postFilteredBy?: string;
442
850
  /** Requested types that resolve to no EUR-Lex form code (reported, not silently dropped). */
443
851
  ignoredDocumentTypes?: string[];
444
852
  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
- */
853
+ /** SDK-added: the `X-Warning` response header (e.g. `maxPages` clamped). */
449
854
  xWarning?: string;
450
855
  }
451
856
  interface DocumentContentRequest {
857
+ /** CELEX, incl. corrigenda (`32013R0952R(04)`) and consolidated forms (`02016R0679-20180524`). */
452
858
  celexNumber: string;
453
- /** Force a live scrape, bypassing the corpus cache. */
859
+ /** Force a fresh upstream read, bypassing the corpus row and the HTML fetch cache (billed at the live rate). */
454
860
  bypassCorpus?: boolean;
455
861
  /**
456
862
  * Language rendition to return (whole document). Falls back to English
457
- * when unavailable — see `languageRequested`/`languageFallback` on the
458
- * document.
863
+ * when unavailable — see `languageRequested`/`languageFallback`.
459
864
  */
460
865
  language?: Language;
866
+ /**
867
+ * Opt-in fallback when the requested language has no text: the first
868
+ * accepted language that does is served instead (labelled like the
869
+ * automatic English fallback).
870
+ */
871
+ acceptLanguages?: AcceptLanguages;
461
872
  /** Trim the response payload to the listed pieces. */
462
873
  include?: IncludeSelection;
463
874
  /** Alias accepted alongside `include`. */
464
875
  fields?: IncludeSelection;
465
- /** Narrow `content.articles` to a single article (`art_17`, `17`, or `Article 17`). */
876
+ /** Narrow `content.articles` to one article (`art_17`, `17`, `Article 17`, `6a`). */
466
877
  articleId?: string;
467
878
  }
468
- interface DocumentContentResponse extends CreditedResponse {
879
+ interface DocumentContentResponse extends CreditedResponse, WithResponseHeaders {
469
880
  success: boolean;
470
881
  document: Document;
471
882
  }
472
883
  interface DocumentContentBatchRequest {
473
- /** Truncated to the tier batch ceiling (FREE=1, STARTER=5, PROFESSIONAL=20, BUSINESS=50). */
884
+ /** Truncated to the tier batch ceiling (FREE=1, STARTER=5, PROFESSIONAL=20, BUSINESS+=50). */
474
885
  celexNumbers: string[];
475
886
  bypassCorpus?: boolean;
476
887
  language?: Language;
888
+ acceptLanguages?: AcceptLanguages;
477
889
  include?: IncludeSelection;
478
890
  fields?: IncludeSelection;
479
891
  articleId?: string;
480
892
  }
481
- /** One failed CELEX from a batch fetch. */
893
+ /** One failed CELEX from a batch fetch — as the server sends it: `{ celex, error }`. */
482
894
  interface BatchDocumentError {
483
- celexNumber?: string;
484
- /** Short error slug (includes upstream timeouts as `"FetchTimeoutError" | "TIMEOUT"`). */
895
+ /** The CELEX that failed. */
896
+ celex?: string;
897
+ /** Free-text failure message (not a stable slug). */
485
898
  error?: string;
899
+ /** @deprecated Never sent by the server — read `celex`. */
900
+ celexNumber?: string;
901
+ /** @deprecated Never sent by the server — read `error`. */
486
902
  message?: string;
903
+ [key: string]: unknown;
487
904
  }
488
- interface DocumentContentBatchResponse extends CreditedResponse {
905
+ interface DocumentContentBatchResponse extends CreditedResponse, WithResponseHeaders {
489
906
  success: boolean;
490
907
  /** Number of CELEX numbers in the request body. */
491
908
  requested: number;
@@ -493,11 +910,15 @@ interface DocumentContentBatchResponse extends CreditedResponse {
493
910
  processed: number;
494
911
  successful: number;
495
912
  failed: number;
913
+ /**
914
+ * Returned documents that carry metadata but no text (`content: null`).
915
+ * They stay in `documents[]`, not `errors[]`.
916
+ */
917
+ textUnavailable?: number;
496
918
  /**
497
919
  * 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.
920
+ * Check `trimmedTo`/`trimmedReason` — trimmed entries were dropped
921
+ * server-side (and not charged).
501
922
  */
502
923
  trimmed?: boolean;
503
924
  trimmedTo?: number;
@@ -511,26 +932,36 @@ interface DocumentContentBatchResponse extends CreditedResponse {
511
932
  interface RecentDocumentsParams {
512
933
  /** How many days back from today to include. Default 7. */
513
934
  days?: number;
935
+ /**
936
+ * ONE document type. The endpoint applies only the first type of a list
937
+ * (no fan-out, unlike `/search`), so the SDK accepts a single value.
938
+ */
514
939
  documentType?: DocumentType;
515
- author?: Author;
940
+ /** One author or several (sent as repeated params; EUR-Lex ORs them). */
941
+ author?: OneOrMany<Author>;
516
942
  domain?: Domain;
943
+ /**
944
+ * ONE subdomain. A subdomain filter sends the request to EUR-Lex result
945
+ * pages, where EUR-Lex reads only the first `DTS_SUBDOM` value
946
+ * (lex-api `server/utils/urlBuilder.js`), so the SDK accepts a single value.
947
+ */
517
948
  subdomain?: Subdomain;
518
949
  /** Result language (default `en`). */
519
950
  language?: Language;
520
- /** Maximum number of results to return. Default 50. */
951
+ /** Maximum number of results to return. Default 50 (3 credits per ~10 results, tier-capped). */
521
952
  limit?: number;
522
953
  }
523
- interface RecentDocumentsResponse extends CreditedResponse {
954
+ interface RecentDocumentsResponse extends CreditedResponse, WithResponseHeaders {
524
955
  success: boolean;
525
956
  /** Echo of the resolved query parameters (with computed `dateFrom`/`dateTo`). */
526
957
  parameters?: {
527
958
  days?: number;
528
959
  dateFrom?: string;
529
960
  dateTo?: string;
530
- documentType?: string | null;
531
- author?: string | null;
961
+ documentType?: string | string[] | null;
962
+ author?: string | string[] | null;
532
963
  domain?: string | null;
533
- subdomain?: string | null;
964
+ subdomain?: string | string[] | null;
534
965
  language?: string;
535
966
  limit?: number;
536
967
  };
@@ -542,6 +973,8 @@ interface RecentDocumentsResponse extends CreditedResponse {
542
973
  requested: string;
543
974
  kept: number;
544
975
  beforeFilter: number;
976
+ /** Rows kept leniently because their language list was too short to trust. */
977
+ partialMetadataKept?: number;
545
978
  };
546
979
  fetchedAt?: string;
547
980
  /** SDK-added: `X-Warning` response header, when present. */
@@ -550,11 +983,13 @@ interface RecentDocumentsResponse extends CreditedResponse {
550
983
  interface DocumentByUrlRequest {
551
984
  /** Any `eur-lex.europa.eu` URL containing a CELEX (path segment or `uri=` param). */
552
985
  url: string;
986
+ /** Force a fresh upstream read (accepted by the server; billed at the live rate). */
987
+ bypassCorpus?: boolean;
553
988
  include?: IncludeSelection;
554
989
  fields?: IncludeSelection;
555
990
  articleId?: string;
556
991
  }
557
- interface DocumentByUrlResponse extends CreditedResponse {
992
+ interface DocumentByUrlResponse extends CreditedResponse, WithResponseHeaders {
558
993
  success: boolean;
559
994
  /** The exact URL passed in the request body. */
560
995
  sourceUrl: string;
@@ -566,44 +1001,76 @@ interface DocumentMetadataRequest {
566
1001
  celexNumber: string;
567
1002
  bypassCorpus?: boolean;
568
1003
  }
569
- interface DocumentMetadataResponse extends CreditedResponse {
1004
+ interface DocumentMetadataResponse extends CreditedResponse, WithResponseHeaders {
570
1005
  success: boolean;
571
1006
  /** Metadata-only — no `content`. Includes the canonical EUR-Lex URLs. */
572
1007
  metadata: DocumentMetadata & {
573
- urls?: {
574
- html?: string;
575
- metadata?: string;
576
- pdf?: string;
577
- xml?: string;
578
- };
1008
+ /**
1009
+ * Sector-3 base acts only, and only when a recent document read already
1010
+ * looked it up (cached ~24 h). Absent means "not looked up", not "none exists".
1011
+ */
1012
+ latestConsolidated?: ConsolidatedVersionHint;
1013
+ upcomingConsolidated?: ConsolidatedVersionHint;
1014
+ newestConsolidated?: ConsolidatedVersionHint;
1015
+ urls?: DocumentUrls;
579
1016
  };
580
1017
  }
581
1018
  type IdentifierType = "celex" | "url" | "eli" | "ecli";
582
- interface ResolveResponse {
1019
+ /**
1020
+ * Which resolution path matched. `celex`/`url`/`eli` resolve purely from the
1021
+ * identifier; `ecli-corpus` / `eli-corpus` mean a corpus lookup answered.
1022
+ */
1023
+ type ResolvedVia = "celex" | "url" | "eli" | "ecli-corpus" | "eli-corpus" | (string & {});
1024
+ interface ResolveResponse extends CreditedResponse, WithResponseHeaders {
583
1025
  success: boolean;
584
1026
  /** Echo of the caller's input. */
585
1027
  identifier: string;
586
1028
  identifierType: IdentifierType;
587
- /** Which resolution path matched. Pure path for celex/url/eli; corpus lookup for ecli. */
588
- resolvedVia: IdentifierType;
1029
+ resolvedVia: ResolvedVia;
589
1030
  celex: string;
590
- urls: {
591
- metadata?: string;
592
- html?: string;
593
- pdf?: string;
594
- xml?: string;
595
- };
1031
+ urls: DocumentUrls;
1032
+ }
1033
+ /**
1034
+ * Classification of a citation edge. `amendment`, `repeal` and
1035
+ * `corrigendum` are structural relations (from Cellar for legislation).
1036
+ */
1037
+ type CitationType = "reference" | "amendment" | "repeal" | "corrigendum" | "implementation" | "legal-basis" | "proposal";
1038
+ /**
1039
+ * Where a neighbour's title came from: the corpus (in the requested
1040
+ * language, or another language), a citation row, the edge itself, or
1041
+ * `unknown` (no title anywhere).
1042
+ */
1043
+ type TitleSource = "corpus" | "corpus-fallback-lang" | "citation-source" | "citation-target" | "edge" | "unknown" | (string & {});
1044
+ /**
1045
+ * Freshness of the target's inbound structural edges (amendment /
1046
+ * corrigendum / repeal), refreshed from Cellar at most once every 7 days.
1047
+ */
1048
+ interface RelationSync {
1049
+ source?: "cellar";
1050
+ /**
1051
+ * `fresh` (nothing to do), `refreshed` (during this request), `pending`
1052
+ * (refresh took >2.5 s and finishes in the background — this response
1053
+ * shows the previously stored edges), `cooldown`/`error` (Cellar failed
1054
+ * recently), `skipped` (see `reason`).
1055
+ */
1056
+ status?: "fresh" | "refreshed" | "pending" | "cooldown" | "error" | "skipped" | (string & {});
1057
+ /** Present when `status` is `skipped`. */
1058
+ reason?: "not-applicable" | "disabled" | "busy" | "budget" | (string & {});
1059
+ /** Last completed refresh when known; null when never refreshed. */
1060
+ syncedAt?: string | null;
596
1061
  }
597
- /** Classification of a citation edge. */
598
- type CitationType = "reference" | "amendment" | "repeal" | "implementation" | "legal-basis" | "proposal";
599
1062
  /** Edge shape emitted on fresh extraction. */
600
1063
  interface CitationEdgeSummary {
1064
+ /** The citing document. */
1065
+ sourceCelex?: string;
601
1066
  targetCelex?: string;
1067
+ /** Whether the edge was found pointing out of (`outbound`) or into (`inbound`) the extracted document. */
1068
+ direction?: "outbound" | "inbound" | (string & {});
602
1069
  citationType?: CitationType;
603
1070
  /** Surrounding text around the citation on the source metadata page, when available. */
604
1071
  contextSnippet?: string | null;
605
1072
  }
606
- interface CitationExtractResponse {
1073
+ interface CitationExtractResponse extends CreditedResponse, WithResponseHeaders {
607
1074
  success: boolean;
608
1075
  message?: string;
609
1076
  /** Present on fresh extraction. Omitted when `alreadyExtracted` is true. */
@@ -613,9 +1080,9 @@ interface CitationExtractResponse {
613
1080
  };
614
1081
  /** Number of citation edges persisted (or already on file). */
615
1082
  citationCount?: number;
616
- /** Edges that were just extracted. Empty array when `alreadyExtracted: true`. */
1083
+ /** Edges that were just extracted. Omitted when `alreadyExtracted: true`. */
617
1084
  citations?: CitationEdgeSummary[];
618
- /** True when the document had already been processed (extraction is idempotent). */
1085
+ /** True when the document had already been processed (settles at 1 credit). */
619
1086
  alreadyExtracted?: boolean;
620
1087
  }
621
1088
  /** A single citation edge with classification, context, and timestamp. */
@@ -628,13 +1095,20 @@ interface CitationEdgeDetail {
628
1095
  interface CitingDocumentGroup {
629
1096
  celexNumber?: string;
630
1097
  title?: string | null;
1098
+ titleSource?: TitleSource;
1099
+ /** Edges of this source in THIS page (raw citation rows). */
631
1100
  citationCount?: number;
1101
+ /** A `…_RES` variant of the source was collapsed into this group. */
1102
+ hasResume?: boolean;
1103
+ /** A `…_SUM` variant of the source was collapsed into this group. */
1104
+ hasSummary?: boolean;
632
1105
  citations?: CitationEdgeDetail[];
633
1106
  }
634
1107
  /** All edges from the source document into one target (cites grouping). */
635
1108
  interface CitedDocumentGroup {
636
1109
  celexNumber?: string;
637
1110
  title?: string | null;
1111
+ titleSource?: TitleSource;
638
1112
  citationCount?: number;
639
1113
  citations?: CitationEdgeDetail[];
640
1114
  }
@@ -646,23 +1120,28 @@ interface CitationEdgeParams {
646
1120
  limit?: number;
647
1121
  /** Pagination offset (in edges, not documents). Default 0. */
648
1122
  offset?: number;
1123
+ /** Language preferred for neighbour titles (default `en`). */
1124
+ language?: Language;
649
1125
  }
650
- interface CitedByResponse {
1126
+ interface CitedByResponse extends CreditedResponse, WithResponseHeaders {
651
1127
  success: boolean;
652
1128
  /** The CELEX whose inbound edges are being listed. */
653
1129
  targetDocument: string;
654
1130
  /** Total inbound edges matching the filter (across all pages). */
655
1131
  totalCitations?: number;
1132
+ /** Citing documents in THIS page (not the global distinct total). */
656
1133
  uniqueDocuments?: number;
657
1134
  limit?: number;
658
1135
  offset?: number;
659
1136
  citedBy: CitingDocumentGroup[];
1137
+ relationSync?: RelationSync;
660
1138
  }
661
- interface CitesResponse {
1139
+ interface CitesResponse extends CreditedResponse, WithResponseHeaders {
662
1140
  success: boolean;
663
1141
  /** The CELEX whose outbound edges are being listed. */
664
1142
  sourceDocument: string;
665
1143
  totalCitations?: number;
1144
+ /** Cited documents in THIS page (not the global distinct total). */
666
1145
  uniqueDocuments?: number;
667
1146
  limit?: number;
668
1147
  offset?: number;
@@ -672,6 +1151,7 @@ interface CitesResponse {
672
1151
  interface CitationNeighbour {
673
1152
  celexNumber?: string;
674
1153
  title?: string | null;
1154
+ titleSource?: TitleSource;
675
1155
  /** Number of edges to/from this neighbour. */
676
1156
  count?: number;
677
1157
  /** Union of `citationType` values across all edges to/from it. */
@@ -684,8 +1164,10 @@ interface CitationNetworkParams {
684
1164
  limit?: number;
685
1165
  /** Pagination offset (in edges, applied to both directions). */
686
1166
  offset?: number;
1167
+ /** Language preferred for neighbour titles (default `en`). */
1168
+ language?: Language;
687
1169
  }
688
- interface CitationNetworkResponse {
1170
+ interface CitationNetworkResponse extends CreditedResponse, WithResponseHeaders {
689
1171
  success: boolean;
690
1172
  /** The centre CELEX. */
691
1173
  document: string;
@@ -709,8 +1191,7 @@ interface CitationNetworkResponse {
709
1191
  };
710
1192
  /**
711
1193
  * 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
1194
+ * `network` arrays are empty and paging totals `null`. Do not treat an
714
1195
  * empty partial network as "no citations".
715
1196
  */
716
1197
  partial?: boolean;
@@ -718,6 +1199,7 @@ interface CitationNetworkResponse {
718
1199
  message?: string;
719
1200
  /** The server-side budget that expired (only on partial responses). */
720
1201
  timeoutMs?: number;
1202
+ relationSync?: RelationSync;
721
1203
  }
722
1204
  interface CitationStatsTopCited {
723
1205
  celexNumber?: string;
@@ -729,7 +1211,7 @@ interface CitationStatsTopCiting {
729
1211
  title?: string | null;
730
1212
  citesCount?: number;
731
1213
  }
732
- interface CitationStatsResponse {
1214
+ interface CitationStatsResponse extends CreditedResponse, WithResponseHeaders {
733
1215
  success: boolean;
734
1216
  stats: {
735
1217
  totalCitations: number;
@@ -740,13 +1222,24 @@ interface CitationStatsResponse {
740
1222
  /** Top-10 documents with the most outbound citations. */
741
1223
  mostCiting: CitationStatsTopCiting[];
742
1224
  };
1225
+ /** When these (cached) statistics were computed. */
1226
+ cachedAt?: string;
1227
+ /** How long the statistics are cached, in seconds. */
1228
+ cacheTtlSeconds?: number;
743
1229
  }
744
1230
  interface CitationPathNode {
745
1231
  celexNumber: string;
746
1232
  /** Enriched at read time from the corpus where available. */
747
1233
  title: string | null;
1234
+ titleSource?: TitleSource;
748
1235
  }
749
- interface CitationPathResponse {
1236
+ interface CitationPathParams {
1237
+ /** Hop budget (default 3, max 8). */
1238
+ maxDepth?: number;
1239
+ /** Language preferred for node titles (default `en`). */
1240
+ language?: Language;
1241
+ }
1242
+ interface CitationPathResponse extends CreditedResponse, WithResponseHeaders {
750
1243
  success: boolean;
751
1244
  from: string;
752
1245
  to: string;
@@ -763,11 +1256,18 @@ interface CitationPathResponse {
763
1256
  interface RelatedDocument {
764
1257
  celexNumber: string;
765
1258
  title?: string | null;
1259
+ titleSource?: TitleSource;
766
1260
  /** Number of citation targets the related document shares with the seed. */
767
1261
  sharedCount: number;
768
1262
  sharedTargets?: string[];
769
1263
  }
770
- interface RelatedDocumentsResponse {
1264
+ interface RelatedDocumentsParams {
1265
+ /** Max neighbours (default 10, max 50). */
1266
+ limit?: number;
1267
+ /** Language preferred for titles (default `en`). */
1268
+ language?: Language;
1269
+ }
1270
+ interface RelatedDocumentsResponse extends CreditedResponse, WithResponseHeaders {
771
1271
  success: boolean;
772
1272
  celexNumber: string;
773
1273
  method: "bibliographic-coupling";
@@ -787,7 +1287,7 @@ type SemanticLanguage = "en" | "fr" | "de" | "es" | "it" | "sl" | "el" | "nl" |
787
1287
  interface SemanticSearchOptions {
788
1288
  /** Natural-language query to embed. */
789
1289
  query: string;
790
- /** Max results. Clamped to the caller's tier ceiling. Default 10. */
1290
+ /** Max results. Clamped to the tier ceiling (legislation: never above 50). Default 10. */
791
1291
  limit?: number;
792
1292
  /**
793
1293
  * Drop results below this cosine similarity (wire: `min_score`).
@@ -796,11 +1296,11 @@ interface SemanticSearchOptions {
796
1296
  * to widen recall, `0` to disable the floor entirely.
797
1297
  */
798
1298
  minScore?: number;
799
- /** Language of returned content. Default `en`. */
1299
+ /** Language of returned content (a preference on legislation). Default `en`. */
800
1300
  language?: SemanticLanguage;
801
1301
  /**
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
1302
+ * Set `true` to receive the full text in each hit (wire:
1303
+ * `include: ["text"]`). By default each hit carries a ~600-char `snippet`
804
1304
  * instead — about a 10-50x payload reduction.
805
1305
  */
806
1306
  includeText?: boolean;
@@ -810,128 +1310,288 @@ interface SemanticSearchOptions {
810
1310
  /** Options for `semanticSearch` (case law) — adds HyDE query rewriting. */
811
1311
  interface SemanticCaseLawSearchOptions extends SemanticSearchOptions {
812
1312
  /**
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.
818
- *
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).
1313
+ * Enable HyDE query rewriting (case-law endpoint only): an LLM drafts the
1314
+ * passage a relevant judgment would contain and retrieval fuses
1315
+ * plain-query and hypothetical-passage rankings.
824
1316
  *
825
- * Must be a JSON boolean — string values are rejected with 400.
1317
+ * **Billing: 15 credits instead of 5**, and adds ~1–3 s of latency.
1318
+ * Best-effort: if generation fails the search falls back to plain
1319
+ * retrieval, the response reports `hyde: false`, and the 10-credit
1320
+ * premium is **automatically refunded**.
826
1321
  */
827
1322
  hyde?: boolean;
828
1323
  }
1324
+ /** Options for `semanticLegislationSearch` — adds point-in-time `asOf`. */
1325
+ interface SemanticLegislationSearchOptions extends SemanticSearchOptions {
1326
+ /**
1327
+ * Answer each hit with the version in force on this date (`YYYY-MM-DD`,
1328
+ * 1952-01-01 … today UTC): the act as published before its first
1329
+ * consolidation, otherwise the consolidated version in force on that
1330
+ * date. Omit for the latest version.
1331
+ *
1332
+ * **Billing:** 5 credits for the search; each live fetch of a version the
1333
+ * corpus does not hold reserves 5 just before it starts and settles by
1334
+ * outcome (Cellar 4, browser 5, no text 1, failed/timed out 0) — at most
1335
+ * `SEMANTIC_ASOF_MAX_FETCHES` (default 3) per request. A fetch the pool
1336
+ * cannot cover is skipped (`asOfReason: "insufficient_credits"`). An
1337
+ * invalid `asOf` is a 400 (refunded in full).
1338
+ */
1339
+ asOf?: string;
1340
+ }
829
1341
  /** Single case-law match from `/search/semantic`. */
830
1342
  interface SemanticCaseLawResult {
831
1343
  /**
832
- * Snapshot-scoped UUID — regenerated when the upstream index is rebuilt.
1344
+ * Snapshot-scoped id — regenerated when the upstream index is rebuilt.
833
1345
  * Do NOT store as a long-term identifier; use
834
1346
  * `(metadata.celex_id, metadata.document_type)` for persistent joins.
835
1347
  */
836
1348
  case_id?: string | null;
837
1349
  /** Cosine similarity, 0–1. */
838
1350
  score?: number;
839
- /** Matching passage; replaced with the full document text when a parsed copy is available. */
1351
+ /** Full matched-document text — present ONLY with `includeText: true`. */
840
1352
  text?: string;
1353
+ /** ~600-character preview — present by default (replaced by `text` with `includeText`). */
1354
+ snippet?: string;
841
1355
  case_name?: string | null;
842
1356
  case_number?: string | null;
843
1357
  ecli?: string | null;
844
1358
  court?: string | null;
1359
+ parties?: string | null;
1360
+ /** LLM-generated digest of the ruling. */
1361
+ summary?: string | null;
1362
+ decision_date?: string | null;
1363
+ jurisdiction?: string | null;
1364
+ language?: string | null;
1365
+ /**
1366
+ * Structured analytics — present ONLY where the upstream extractor was
1367
+ * confident; omitted otherwise (never `null`).
1368
+ */
1369
+ outcome?: string;
1370
+ outcome_detail?: string;
1371
+ party_role?: string;
1372
+ claimed_amount?: number;
1373
+ awarded_amount?: number;
1374
+ currency?: string;
1375
+ award_percentage?: number;
1376
+ legal_area?: string | string[];
1377
+ legislation_cited?: string[];
1378
+ duration_days?: number;
1379
+ was_appealed?: boolean;
1380
+ appeal_outcome?: string;
1381
+ extraction_confidence?: number;
1382
+ extraction_model?: string;
1383
+ extracted_at?: string;
845
1384
  /** Always includes `celex_id` when available — the persistent identity key. */
846
1385
  metadata?: {
847
1386
  celex_id?: string;
848
1387
  document_type?: string | null;
1388
+ /** Position of the match within the judgment, when available. */
1389
+ paragraph_number?: number;
849
1390
  [key: string]: unknown;
850
1391
  };
1392
+ [key: string]: unknown;
851
1393
  }
852
1394
  /** Semantic-specific quota counters (legacy daily-call plans only). */
853
1395
  interface SemanticUsageInfo {
854
1396
  current?: number;
855
1397
  limit?: number;
856
1398
  remaining?: number;
1399
+ /** Semantic-quota units this call consumed (always 1). */
1400
+ unitsCharged?: number;
857
1401
  }
858
- interface SemanticCaseLawSearchResponse {
1402
+ interface SemanticCaseLawSearchResponse extends CreditedResponse, WithResponseHeaders {
859
1403
  success: boolean;
860
1404
  searchType?: "semantic-case-law";
861
1405
  query?: string;
862
1406
  resultCount?: number;
863
1407
  results: SemanticCaseLawResult[];
864
1408
  /**
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.
1409
+ * Present only on best-effort responses (low-confidence hits) — its
1410
+ * presence is itself the low-confidence signal. Omitted (never `null`) otherwise.
868
1411
  */
869
1412
  hint?: string;
870
1413
  /**
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.
1414
+ * Present only when the request set `hyde: true`. `false` means generation
1415
+ * failed, the search fell back to plain retrieval, and the 10-credit
1416
+ * premium was refunded.
874
1417
  */
875
1418
  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
- */
1419
+ /** Present only when HyDE ran: the LLM-drafted hypothetical judgment passage. */
881
1420
  hypotheticalDocument?: string;
882
1421
  /** Opaque upstream pass-through; shape not stable — use `tookMs` for timing. */
883
1422
  metadata?: Record<string, unknown>;
884
1423
  /** Server-measured wall-clock time for this request, in ms. */
885
1424
  tookMs?: number;
1425
+ /** Legacy daily-call plans only. */
886
1426
  semanticUsage?: SemanticUsageInfo;
887
- subscription?: SubscriptionInfo & {
888
- maxResults?: number;
889
- };
890
- usage?: UsageInfo;
891
- credits?: CreditsInfo;
1427
+ }
1428
+ /**
1429
+ * Why an `asOf` hit could not be answered for that date; the hit then keeps
1430
+ * its latest text (`asOfResolved: false`). Never silently wrong text.
1431
+ *
1432
+ * - `not_yet_adopted` — `asOf` is before the date of the act.
1433
+ * - `not_yet_in_force` — the act existed but had not yet entered into force.
1434
+ * - `no_longer_in_force` — `asOf` is after the act's end of validity.
1435
+ * - `in_force_dates_unknown` — the act's in-force dates could not be established.
1436
+ * - `not_in_language` — the version in force has no text in that language.
1437
+ * - `text_unavailable` — the version in force has no text.
1438
+ * - `article_not_in_version` — that article/annex/recital does not exist in the version in force.
1439
+ * - `part_not_resolvable` — the match is a part that cannot be looked up by date (e.g. a table).
1440
+ * - `article_unknown` — the hit has no article identity.
1441
+ * - `version_list_unavailable` — the list of consolidated versions could not be read.
1442
+ * - `version_lookup_cap` — too many version-list lookups (per request, or per account per minute).
1443
+ * - `fetch_budget_exhausted` — this request's live-fetch limit was reached.
1444
+ * - `fetch_pending` — that version is already being fetched; ask again shortly.
1445
+ * - `fetch_capacity` — too many live fetches in flight; ask again shortly.
1446
+ * - `fetch_failed` / `fetch_timeout` — the live fetch failed or ran out of time.
1447
+ * - `request_deadline` — the request ran out of time.
1448
+ * - `insufficient_credits` — the credit pool could not cover that fetch.
1449
+ * - `credit_check_failed` — the credit check did not answer; no fetch was made.
1450
+ */
1451
+ type AsOfReason = "not_yet_adopted" | "not_yet_in_force" | "no_longer_in_force" | "in_force_dates_unknown" | "not_in_language" | "text_unavailable" | "article_not_in_version" | "part_not_resolvable" | "article_unknown" | "version_list_unavailable" | "version_lookup_cap" | "fetch_budget_exhausted" | "fetch_pending" | "fetch_capacity" | "fetch_failed" | "fetch_timeout" | "request_deadline" | "insufficient_credits" | "credit_check_failed" | (string & {});
1452
+ /** Every documented {@link AsOfReason} value, in spec order (runtime list). */
1453
+ declare const AS_OF_REASONS: readonly ["not_yet_adopted", "not_yet_in_force", "no_longer_in_force", "in_force_dates_unknown", "not_in_language", "text_unavailable", "article_not_in_version", "part_not_resolvable", "article_unknown", "version_list_unavailable", "version_lookup_cap", "fetch_budget_exhausted", "fetch_pending", "fetch_capacity", "fetch_failed", "fetch_timeout", "request_deadline", "insufficient_credits", "credit_check_failed"];
1454
+ /** The version an `asOf` hit's text comes from. */
1455
+ interface AsOfVersion {
1456
+ celex?: string;
1457
+ /** Consolidation date; `null` for the act as published. */
1458
+ date?: string | null;
1459
+ kind?: "consolidated" | "as_published" | (string & {});
892
1460
  }
893
1461
  /** Single article-level match from `/legislation/semantic`. */
894
1462
  interface SemanticLegislationResult {
895
- /** Cosine similarity, 0–1. */
1463
+ /** Index hit id (snapshot-scoped; `asof:<celex>:<ref>` when `asOf` swapped the text). */
1464
+ id?: string;
1465
+ /** Cosine similarity, 0–1 (of the indexed text — see `matchedVersion`). */
896
1466
  score?: number;
897
- /** Matching article text from the embedding index. */
1467
+ /** Full article text — present ONLY with `includeText: true`. */
898
1468
  text?: string;
899
- /** Article identifier (e.g. `Article 17`). */
1469
+ /** Compact preview of the matched text — present by default. */
1470
+ snippet?: string;
1471
+ /** Article identifier (e.g. `art_17`) — usable as `articleId` on `getDocument`. */
900
1472
  article_ref?: string | null;
901
1473
  /** CELEX identifier of the parent legal act. */
902
1474
  law_id?: string | null;
903
1475
  law_title?: string | null;
1476
+ /** Language of the matched text (the request's `language` is a preference). */
1477
+ language?: string;
1478
+ section?: string | null;
1479
+ chapter?: string | null;
1480
+ exact_match_law_id?: boolean;
1481
+ /** `true` on a consolidated text; absent otherwise. */
1482
+ consolidated?: boolean;
1483
+ /** Consolidated texts only — the consolidation date (`YYYY-MM-DD`). */
1484
+ consolidatedAsOf?: string;
1485
+ /** Consolidated texts only — the act this text consolidates; cite it as the authentic source. */
1486
+ baseCelex?: string;
1487
+ /**
1488
+ * Consolidated texts only — "The act as amended, consolidated as of
1489
+ * <date>; not the authentic text. …" Only the Official Journal text is authentic.
1490
+ */
1491
+ consolidatedNote?: string;
1492
+ /** Present when the act as published matched the same article; its own match. */
1493
+ baseAct?: {
1494
+ law_id?: string;
1495
+ article_ref?: string | null;
1496
+ score?: number | null;
1497
+ };
1498
+ /** `asOf` requests only — echo of the request's `asOf`. */
1499
+ asOf?: string;
1500
+ /** `asOf` requests only — whether this hit carries the text in force on `asOf`. */
1501
+ asOfResolved?: boolean;
1502
+ /** Why `asOfResolved` is false; the hit then keeps its latest text. */
1503
+ asOfReason?: AsOfReason;
1504
+ /** `asOf` requests only — the version this hit's text comes from. */
1505
+ asOfVersion?: AsOfVersion;
1506
+ /**
1507
+ * Present when `asOf` swapped the text — the version the index matched
1508
+ * (`score` is its similarity, not the in-force text's).
1509
+ */
1510
+ matchedVersion?: {
1511
+ id?: string | null;
1512
+ law_id?: string;
1513
+ consolidatedAsOf?: string | null;
1514
+ };
904
1515
  metadata?: Record<string, unknown>;
1516
+ [key: string]: unknown;
905
1517
  }
906
- interface SemanticLegislationSearchResponse {
1518
+ interface SemanticLegislationSearchResponse extends CreditedResponse, WithResponseHeaders {
907
1519
  success: boolean;
908
1520
  searchType?: "semantic-legislation";
909
1521
  query?: string;
910
1522
  resultCount?: number;
911
1523
  results: SemanticLegislationResult[];
1524
+ /** `asOf` requests only — echo of the request's `asOf`. */
1525
+ asOf?: string;
1526
+ /** `asOf` requests only. */
1527
+ asOfSummary?: {
1528
+ /** Live fetches attempted, including failed and timed-out ones (those cost 0). */
1529
+ liveFetches?: number;
1530
+ /** Hits returned with `asOfResolved: false`. */
1531
+ unresolved?: number;
1532
+ };
912
1533
  /** Present only on best-effort responses — see `SemanticCaseLawSearchResponse.hint`. */
913
1534
  hint?: string;
914
1535
  /** Opaque upstream pass-through; shape not stable — use `tookMs` for timing. */
915
1536
  metadata?: Record<string, unknown>;
916
1537
  tookMs?: number;
1538
+ /** Legacy daily-call plans only. */
917
1539
  semanticUsage?: SemanticUsageInfo;
918
- subscription?: SubscriptionInfo & {
919
- maxResults?: number;
920
- };
921
- usage?: UsageInfo;
922
- credits?: CreditsInfo;
923
1540
  }
924
- /** Operational state. `FAILED` is set automatically after repeated delivery errors. */
1541
+ /** Operational state. `FAILED` is set automatically when one delivery fails all 7 attempts (~24 h). */
925
1542
  type WebhookStatus = "ACTIVE" | "PAUSED" | "FAILED";
926
1543
  type DeliveryStatus = "PENDING" | "SUCCESS" | "FAILED" | "RETRYING";
1544
+ /**
1545
+ * Filters for `documents.new`, in the /search vocabulary but matched against
1546
+ * document TITLES and metadata. Every filter given must match; `{}` matches
1547
+ * every new EU-law document (sectors 1–6), never consolidated texts. A
1548
+ * `subdomain` REPLACES that default (`"consolidated"` alone = consolidated
1549
+ * texts only). Unsupported filters (`procedure`, `textScope: "text"`,
1550
+ * `domain: "NATIONAL_LAW"`, boolean operators, unknown types/authors) are
1551
+ * refused with 400 and a `details` list.
1552
+ */
1553
+ interface WebhookCriteria {
1554
+ /**
1555
+ * Every term (or "quoted phrase") must match whole words of the title
1556
+ * (case/accent-insensitive; 4+ char terms match word starts; `tax*`
1557
+ * matches word starts at any length). `OR`/`NOT`/`NEAR`/`-term` are refused.
1558
+ */
1559
+ query?: string;
1560
+ /** Same values as /search; `regulation`/`directive`/`decision` match every sub-type. */
1561
+ documentType?: OneOrMany<DocumentType | (string & {})>;
1562
+ /**
1563
+ * Same values as /search (`commission`, `council`, `parliament`,
1564
+ * `court-of-justice`/`cjeu`/`ecj`/`court`, `general-court`,
1565
+ * `civil-service-tribunal`, `ecb`, `eca`, `eesc`, `cor`, `efsa`, or codes
1566
+ * like `COM`). `member-states` and `ema` are refused.
1567
+ */
1568
+ author?: OneOrMany<string>;
1569
+ /** Lower-case subdomain names: `treaties`, `international`, `legislation`, `preparatory`, `case-law`, `consolidated`. */
1570
+ subdomain?: OneOrMany<string>;
1571
+ /** Lower bound on the document date (`YYYY-MM-DD`). */
1572
+ dateFrom?: string;
1573
+ dateTo?: string;
1574
+ year?: number | number[];
1575
+ /** Accepted for compatibility — all match titles. */
1576
+ textScope?: "title" | "title-text" | "any";
1577
+ domain?: "EU_LAW" | "ALL";
1578
+ language?: string;
1579
+ }
927
1580
  /** Summary shape used in list responses. The `secret` is never included here. */
928
1581
  interface WebhookListItem {
929
1582
  id?: string;
930
1583
  name?: string;
931
1584
  url?: string;
932
1585
  status?: WebhookStatus;
933
- /** The saved search — same shape as a `/search` request body. */
934
- searchCriteria?: SearchRequest;
1586
+ searchCriteria?: WebhookCriteria | null;
1587
+ /**
1588
+ * What is wrong with the stored `searchCriteria`; empty when nothing is.
1589
+ * Non-empty only for criteria saved before a validation rule existed —
1590
+ * such criteria are skipped (never widened) until fixed with `update`.
1591
+ */
1592
+ criteriaErrors?: string[];
1593
+ /** Watched base-act CELEX numbers (`watchlist.changes`). */
1594
+ watchCelex?: string[];
935
1595
  lastChecked?: string | null;
936
1596
  lastTriggered?: string | null;
937
1597
  consecutiveFailures?: number;
@@ -942,6 +1602,8 @@ interface WebhookListItem {
942
1602
  /** A single delivery attempt. */
943
1603
  interface WebhookDelivery {
944
1604
  id?: string;
1605
+ /** Present on `recentDeliveries` (raw rows); not on `/deliveries` items. */
1606
+ webhookId?: string;
945
1607
  status?: DeliveryStatus;
946
1608
  /** The JSON payload that was POSTed (or queued) to the webhook URL. */
947
1609
  payload?: Record<string, unknown>;
@@ -954,6 +1616,16 @@ interface WebhookDelivery {
954
1616
  nextRetryAt?: string | null;
955
1617
  deliveredAt?: string | null;
956
1618
  createdAt?: string;
1619
+ [key: string]: unknown;
1620
+ }
1621
+ /** Delivery retry schedule reported on `GET /webhooks/{id}`. */
1622
+ interface WebhookRetryPolicy {
1623
+ /** e.g. 7 */
1624
+ maxAttempts?: number;
1625
+ /** e.g. 24 */
1626
+ windowHours?: number;
1627
+ /** e.g. `[1, 5, 30, 120, 360, 900]` */
1628
+ delaysMinutes?: number[];
957
1629
  }
958
1630
  /** Full webhook details (no `secret`). */
959
1631
  interface WebhookDetail {
@@ -961,21 +1633,26 @@ interface WebhookDetail {
961
1633
  name?: string;
962
1634
  url?: string;
963
1635
  status?: WebhookStatus;
964
- searchCriteria?: SearchRequest;
1636
+ searchCriteria?: WebhookCriteria | null;
1637
+ criteriaErrors?: string[];
1638
+ watchCelex?: string[];
965
1639
  lastChecked?: string | null;
966
1640
  lastTriggered?: string | null;
967
1641
  consecutiveFailures?: number;
1642
+ retryPolicy?: WebhookRetryPolicy;
1643
+ /** @deprecated No longer returned by the server — read `retryPolicy.maxAttempts`. */
968
1644
  maxRetries?: number;
969
1645
  createdAt?: string;
970
1646
  updatedAt?: string;
971
1647
  /** Up to 20 most recent delivery attempts, newest first. */
972
1648
  recentDeliveries?: WebhookDelivery[];
973
1649
  }
974
- interface WebhookListResponse {
1650
+ interface WebhookListResponse extends WithResponseHeaders {
975
1651
  success: boolean;
976
1652
  count?: number;
977
1653
  webhooks: WebhookListItem[];
978
1654
  }
1655
+ /** Needs `searchCriteria`, `watchCelex`, or both. */
979
1656
  interface WebhookCreateRequest {
980
1657
  /** User-friendly label for the webhook. */
981
1658
  name: string;
@@ -987,22 +1664,33 @@ interface WebhookCreateRequest {
987
1664
  * time it is exposed. Store it.
988
1665
  */
989
1666
  secret?: string;
990
- /** Documents newly matching these filters trigger a delivery to `url`. */
991
- searchCriteria: SearchRequest;
1667
+ /** New documents matching these filters trigger a `documents.new` delivery. */
1668
+ searchCriteria?: WebhookCriteria;
1669
+ /**
1670
+ * Base-act CELEX numbers to watch — amendments, corrigenda, repeals and
1671
+ * new consolidated versions trigger a `watchlist.changes` delivery. Plan
1672
+ * limit per webhook: STARTER 100, PROFESSIONAL 500, BUSINESS 1000, SCALE
1673
+ * 2000, ENTERPRISE 5000.
1674
+ */
1675
+ watchCelex?: string[];
992
1676
  }
993
1677
  /**
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).
1678
+ * Partial update — only the supplied fields are changed. `watchCelex`
1679
+ * replaces the whole list; `searchCriteria: null` removes the criteria (one
1680
+ * of the two must remain). Setting `status` to `ACTIVE` resets
1681
+ * `consecutiveFailures`; moving a `FAILED`/`PAUSED` webhook to `ACTIVE`
1682
+ * also re-queues its deliveries from the last 7 days that ran out of
1683
+ * retries (`requeuedDeliveries`).
997
1684
  */
998
1685
  interface WebhookUpdateRequest {
999
1686
  name?: string;
1000
1687
  url?: string;
1001
- searchCriteria?: SearchRequest;
1688
+ searchCriteria?: WebhookCriteria | null;
1689
+ watchCelex?: string[];
1002
1690
  status?: WebhookStatus;
1003
1691
  }
1004
1692
  /** Returned by `POST /webhooks`. The `secret` is included here only. */
1005
- interface WebhookCreateResponse {
1693
+ interface WebhookCreateResponse extends WithResponseHeaders {
1006
1694
  success: boolean;
1007
1695
  message?: string;
1008
1696
  webhook: {
@@ -1012,12 +1700,13 @@ interface WebhookCreateResponse {
1012
1700
  /** HMAC-SHA256 signing secret. Store this — it is not returned again. */
1013
1701
  secret?: string;
1014
1702
  status: WebhookStatus;
1015
- searchCriteria?: SearchRequest;
1703
+ searchCriteria?: WebhookCriteria | null;
1704
+ watchCelex?: string[];
1016
1705
  createdAt: string;
1017
1706
  };
1018
1707
  }
1019
1708
  /** Returned by `PUT /webhooks/{id}` — summary fields only. */
1020
- interface WebhookUpdateResponse {
1709
+ interface WebhookUpdateResponse extends WithResponseHeaders {
1021
1710
  success: boolean;
1022
1711
  message?: string;
1023
1712
  webhook: {
@@ -1025,21 +1714,31 @@ interface WebhookUpdateResponse {
1025
1714
  name?: string;
1026
1715
  url?: string;
1027
1716
  status?: WebhookStatus;
1028
- searchCriteria?: SearchRequest;
1717
+ searchCriteria?: WebhookCriteria | null;
1718
+ criteriaErrors?: string[];
1719
+ watchCelex?: string[];
1029
1720
  updatedAt?: string;
1030
1721
  };
1722
+ /** Present when the request set `status: "ACTIVE"` — deliveries queued again. */
1723
+ requeuedDeliveries?: number;
1031
1724
  }
1032
1725
  /** Returned by `GET /webhooks/{id}`. */
1033
- interface WebhookResponse {
1726
+ interface WebhookResponse extends WithResponseHeaders {
1034
1727
  success: boolean;
1035
1728
  webhook: WebhookDetail;
1036
1729
  }
1730
+ /** Returned by `DELETE /webhooks/{id}`. */
1731
+ interface WebhookDeleteResponse extends WithResponseHeaders {
1732
+ success: boolean;
1733
+ message?: string;
1734
+ }
1037
1735
  /**
1038
1736
  * Result of a synchronous test delivery. `success: true` means the
1039
1737
  * upstream responded 2xx; non-2xx and network errors both yield
1040
- * `success: false` plus a populated `delivery.errorMessage`.
1738
+ * `success: false` plus a populated `delivery.errorMessage`. Test
1739
+ * deliveries are not recorded in the delivery history.
1041
1740
  */
1042
- interface WebhookTestResponse {
1741
+ interface WebhookTestResponse extends WithResponseHeaders {
1043
1742
  success: boolean;
1044
1743
  message?: string;
1045
1744
  delivery: {
@@ -1056,7 +1755,7 @@ interface WebhookDeliveriesParams {
1056
1755
  /** Pagination offset. Default 0. */
1057
1756
  offset?: number;
1058
1757
  }
1059
- interface WebhookDeliveriesResponse {
1758
+ interface WebhookDeliveriesResponse extends WithResponseHeaders {
1060
1759
  success: boolean;
1061
1760
  /** Total deliveries for this webhook (across all pages). */
1062
1761
  total?: number;
@@ -1064,18 +1763,98 @@ interface WebhookDeliveriesResponse {
1064
1763
  offset?: number;
1065
1764
  deliveries: WebhookDelivery[];
1066
1765
  }
1766
+ /** A document as delivered by `documents.new` and `watchlist.changes`. */
1767
+ interface WebhookChangeDocument {
1768
+ celex?: string;
1769
+ /** English title (another official language when no English title exists yet); null if metadata never arrived. */
1770
+ title?: string | null;
1771
+ url?: string;
1772
+ documentType?: string | null;
1773
+ documentTypeCode?: string | null;
1774
+ /** Publications Office resource-type codes, e.g. `["CONS_TEXT"]`. */
1775
+ resourceTypes?: string[];
1776
+ author?: string | null;
1777
+ authorCodes?: string[];
1778
+ dateOfDocumentISO?: string | null;
1779
+ /** The document date as dd/mm/yyyy. */
1780
+ dateOfDocument?: string | null;
1781
+ /** Consolidated versions only — the date the version applies from (may be in the future). */
1782
+ consolidationDate?: string | null;
1783
+ /** When the document appeared on EUR-Lex — the clock webhooks match on. */
1784
+ addedAt?: string | null;
1785
+ /** Upper-case ISO codes with a published expression. Check before fetching a consolidated version. */
1786
+ availableLanguages?: string[];
1787
+ /** Alias of `celex` (earlier payload shape). */
1788
+ celexNumber?: string;
1789
+ /** Alias of `documentType` (earlier payload shape). */
1790
+ form?: string | null;
1791
+ }
1792
+ /** Fields shared by every signed delivery. */
1793
+ interface WebhookDeliveryEnvelope {
1794
+ /** Time of THIS attempt (re-signed on every retry) — use it for a replay window. */
1795
+ timestamp: string;
1796
+ webhook: {
1797
+ id: string;
1798
+ name: string;
1799
+ };
1800
+ /** `id` is stable across retries (also `X-Webhook-Delivery`) — dedupe on it. Absent on `webhook.test`. */
1801
+ delivery?: {
1802
+ id: string;
1803
+ attempt: number;
1804
+ };
1805
+ }
1806
+ interface WebhookDocumentsNewPayload extends WebhookDeliveryEnvelope {
1807
+ event: "documents.new";
1808
+ searchCriteria?: WebhookCriteria | null;
1809
+ data: {
1810
+ /** Documents in this delivery (max 100). */
1811
+ count: number;
1812
+ /** Every new match from the same hourly check — larger than `count` when split across deliveries. */
1813
+ totalAvailable?: number;
1814
+ documents: WebhookChangeDocument[];
1815
+ };
1816
+ }
1817
+ type WatchlistRelation = "amended_by" | "corrected_by" | "repealed_by" | "consolidated_version" | (string & {});
1818
+ interface WebhookWatchlistChange {
1819
+ watchedCelex: string;
1820
+ relation: WatchlistRelation;
1821
+ document: WebhookChangeDocument;
1822
+ }
1823
+ interface WebhookWatchlistChangesPayload extends WebhookDeliveryEnvelope {
1824
+ event: "watchlist.changes";
1825
+ data: {
1826
+ /** Changes in this delivery (max 100). */
1827
+ count: number;
1828
+ changes: WebhookWatchlistChange[];
1829
+ };
1830
+ }
1831
+ /** Sent by `webhooks.test()`. */
1832
+ interface WebhookTestPayload extends WebhookDeliveryEnvelope {
1833
+ event: "webhook.test";
1834
+ data: {
1835
+ message: string;
1836
+ searchCriteria?: WebhookCriteria | null;
1837
+ };
1838
+ }
1839
+ /** Discriminated union of every payload LexAPI delivers — switch on `event`. */
1840
+ type WebhookPayload = WebhookDocumentsNewPayload | WebhookWatchlistChangesPayload | WebhookTestPayload;
1067
1841
  /**
1068
1842
  * One entry in a document's version history.
1069
1843
  *
1070
1844
  * 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`.
1845
+ * fetches), not legal in-force reconstructions — for the text in force on a
1846
+ * date use a consolidated CELEX, or `semanticLegislationSearch({ asOf })`.
1847
+ * `fetchedAt` is when THIS version was fetched — version N is "current"
1848
+ * from there until version N+1's `fetchedAt`.
1074
1849
  */
1075
1850
  interface VersionEntry {
1076
1851
  version: number;
1077
1852
  isCurrent: boolean;
1078
- /** Equality across versions means no real content change. */
1853
+ /**
1854
+ * Equal hashes mean no text change. A different hash usually means EUR-Lex
1855
+ * changed the text — or the current version was re-parsed in place by an
1856
+ * improved parser.
1857
+ */
1079
1858
  contentHash: string;
1080
1859
  fetchedAt: string;
1081
1860
  title?: string | null;
@@ -1084,7 +1863,7 @@ interface VersionEntry {
1084
1863
  /** Present on single-snapshot responses only (not in history listings). */
1085
1864
  parsedContent?: Record<string, unknown> | null;
1086
1865
  }
1087
- interface DocumentVersionsResponse extends CreditedResponse {
1866
+ interface DocumentVersionsResponse extends CreditedResponse, WithResponseHeaders {
1088
1867
  success: boolean;
1089
1868
  celex: string;
1090
1869
  language: string;
@@ -1096,7 +1875,7 @@ interface DocumentVersionsResponse extends CreditedResponse {
1096
1875
  /** Newest first; the current version is included and flagged. */
1097
1876
  versions: VersionEntry[];
1098
1877
  }
1099
- interface DocumentVersionResponse extends CreditedResponse {
1878
+ interface DocumentVersionResponse extends CreditedResponse, WithResponseHeaders {
1100
1879
  success: boolean;
1101
1880
  celex: string;
1102
1881
  language: string;
@@ -1104,30 +1883,70 @@ interface DocumentVersionResponse extends CreditedResponse {
1104
1883
  asOf?: string;
1105
1884
  semantics: string;
1106
1885
  document: VersionEntry;
1107
- /** Mirrors the `X-Corpus-Version` response header. */
1886
+ /** SDK-added: mirrors the `X-Corpus-Version` response header. */
1108
1887
  corpusVersion?: number;
1109
1888
  }
1889
+ /** Shared params for the version endpoints. */
1890
+ interface VersionParams {
1891
+ /** 2-letter ISO language of the tracked corpus row (default `en`). */
1892
+ language?: string;
1893
+ }
1110
1894
 
1895
+ /** A list filter: an array, or a comma-separated string (`"regulation,directive"`). */
1896
+ type ExportListFilter = string | ReadonlyArray<string>;
1897
+ /**
1898
+ * Filters for `GET /export` (API 2.3.0, lex-api #303). List values are sent
1899
+ * comma-separated and ORed.
1900
+ */
1111
1901
  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;
1902
+ /**
1903
+ * Document types: the stored label, matched exactly ignoring case
1904
+ * (`"regulation"` matches `Regulation`, not `Implementing regulation`).
1905
+ * For a whole family use `documentTypeCode`.
1906
+ */
1907
+ documentType?: ExportListFilter;
1908
+ /**
1909
+ * Type families by the `documentTypeCode` each row carries: `"regulation"`
1910
+ * includes implementing and delegated regulations. Combined with
1911
+ * `documentType`, both must match.
1912
+ */
1913
+ documentTypeCode?: ExportListFilter;
1914
+ /** Authors: whole stored values, ignoring case (a joint act's author string is one value). */
1915
+ author?: ExportListFilter;
1916
+ /** Subdomains (`legislation`, `case-law`, `treaties`, `preparatory`, `international`, `consolidated`, …). */
1917
+ subdomain?: ExportListFilter;
1118
1918
  /** Document language (default `en`). */
1119
1919
  language?: Language;
1120
- /** Earliest `dateOfDocument` to include (inclusive, `YYYY-MM-DD`). */
1920
+ /** Earliest document date to include (inclusive, `YYYY-MM-DD`; anything else is a 400). */
1121
1921
  dateFrom?: string;
1122
- /** Latest `dateOfDocument` to include (inclusive, `YYYY-MM-DD`). */
1922
+ /** Latest document date to include (inclusive, `YYYY-MM-DD`). */
1123
1923
  dateTo?: string;
1124
- /** Only stream rows whose `lastSeenAt` is at or after this ISO timestamp. */
1125
- fetchedSince?: string;
1924
+ /**
1925
+ * Rows whose `lastSeenAt` is at or after this time (any write to the row).
1926
+ * An ISO 8601 date or a date-time WITH a timezone (the API answers 400 to
1927
+ * one without), or a `Date` (sent as UTC).
1928
+ */
1929
+ fetchedSince?: string | Date;
1930
+ /**
1931
+ * Rows whose text changed (`contentChangedAt`) at or after this time — the
1932
+ * cheapest incremental sync. Same format as `fetchedSince`.
1933
+ */
1934
+ changedSince?: string | Date;
1126
1935
  /** Include raw `htmlContent` / `htmlMetadata` per row (large). Default false. */
1127
1936
  includeHtml?: boolean;
1128
1937
  /** Set `false` to omit `parsedContent` from each row. Default true. */
1129
1938
  includeContent?: boolean;
1130
- /** Max rows to stream. Clamped to the server's `EXPORT_MAX_ROWS` ceiling. */
1939
+ /**
1940
+ * Also stream metadata-only rows (documents whose text EUR-Lex does not
1941
+ * publish, or not yet). Default false — skipped rows are counted as
1942
+ * `skippedStubs` on the trailer.
1943
+ */
1944
+ includeStubs?: boolean;
1945
+ /**
1946
+ * Max rows to stream: a positive integer (anything else throws a
1947
+ * `RangeError` before the request — the API answers 400). Clamped to the
1948
+ * server's `EXPORT_MAX_ROWS` ceiling (default 50 000).
1949
+ */
1131
1950
  limit?: number;
1132
1951
  }
1133
1952
  /**
@@ -1170,27 +1989,90 @@ interface ExportRow {
1170
1989
  htmlMetadata?: unknown;
1171
1990
  [key: string]: unknown;
1172
1991
  }
1992
+ /** Body of the leading `{"_meta": {...}}` line. */
1993
+ interface ExportMetaInfo {
1994
+ filters?: {
1995
+ documentType?: string[] | null;
1996
+ author?: string[] | null;
1997
+ subdomain?: string[] | null;
1998
+ language?: string;
1999
+ dateFrom?: string | null;
2000
+ dateTo?: string | null;
2001
+ fetchedSince?: string | null;
2002
+ };
2003
+ /** Rows matching the filters (same as `X-Export-Total`). */
2004
+ totalMatching?: number;
2005
+ /** Rows the server will stream (min of total and limit). */
2006
+ streaming?: number;
2007
+ truncated?: boolean;
2008
+ includeHtml?: boolean;
2009
+ includeContent?: boolean;
2010
+ exportedAt?: string;
2011
+ [key: string]: unknown;
2012
+ }
1173
2013
  /**
1174
- * The leading `_meta` envelope line. The spec does not pin its shape, so
1175
- * beyond the `_meta` marker everything is kept as-is.
2014
+ * The leading `_meta` envelope line. The server nests everything under
2015
+ * `_meta`; the SDK also lifts those fields to the top level for convenience
2016
+ * (`stream.meta.totalMatching`).
1176
2017
  */
1177
- interface ExportMeta {
1178
- _meta?: unknown;
1179
- [key: string]: unknown;
2018
+ interface ExportMeta extends ExportMetaInfo {
2019
+ _meta?: ExportMetaInfo | unknown;
1180
2020
  }
1181
- /** The trailing `_done` line. Reports `truncated: true` when the row cap was hit. */
1182
- interface ExportDone {
1183
- _done?: unknown;
2021
+ /** Body of the trailing `{"_done": {...}}` line. */
2022
+ interface ExportDoneInfo {
2023
+ /** Rows actually written. */
2024
+ written?: number;
2025
+ /**
2026
+ * `true` when matching rows remain that the export did not reach (API
2027
+ * 2.3.0: authoritative, see `truncatedBy`) — narrow the filters or resume
2028
+ * via `changedSince` / `fetchedSince`.
2029
+ */
1184
2030
  truncated?: boolean;
2031
+ /** Metadata-only rows skipped because `includeStubs` was off. */
2032
+ skippedStubs?: number;
2033
+ /** Exactly `false` marks an incomplete export (SDK contract §1.8); absent or `true` = complete. */
2034
+ complete?: boolean;
2035
+ /**
2036
+ * API 2.3.0: what cut the export short — `limit`, `max_rows`, `recovered`
2037
+ * (the server's recovery sweep took the export's billing record mid-stream), `credits`
2038
+ * (the pool could not pay for rows added since the count), or `null`.
2039
+ */
2040
+ truncatedBy?: "limit" | "max_rows" | "credits" | "recovered" | null;
2041
+ /**
2042
+ * API 2.3.0, credit plans: the pool after settlement, plus `reserved`,
2043
+ * `charged` (max(written, 1)) and `refunded`; `refundPending: true` when
2044
+ * the refund is applied later by the server's recovery sweep.
2045
+ */
2046
+ credits?: {
2047
+ reserved?: number;
2048
+ charged?: number;
2049
+ refunded?: number;
2050
+ refundPending?: boolean;
2051
+ remaining?: number;
2052
+ [key: string]: unknown;
2053
+ };
1185
2054
  [key: string]: unknown;
1186
2055
  }
2056
+ /**
2057
+ * The trailing `_done` line. The server nests the fields under `_done`; the
2058
+ * SDK lifts them to the top level so `stream.done?.truncated` works.
2059
+ */
2060
+ interface ExportDone extends ExportDoneInfo {
2061
+ _done?: ExportDoneInfo | unknown;
2062
+ }
1187
2063
  /** Signals lifted from the `X-Export-*` response headers. */
1188
2064
  interface ExportHeaderInfo {
1189
2065
  /** Total rows matching the filters in the database (`X-Export-Total`). */
1190
2066
  total: number | undefined;
1191
- /** Rows actually streamed — min of total and limit (`X-Export-Streaming`). */
2067
+ /**
2068
+ * Rows the server set out to stream — min of total and limit
2069
+ * (`X-Export-Streaming`). Rows written can be lower by `done.skippedStubs`.
2070
+ */
1192
2071
  streaming: number | undefined;
1193
- /** `true` when the row cap was hit (`X-Export-Truncated: 1`). */
2072
+ /**
2073
+ * `X-Export-Truncated: 1` — the up-front count exceeded the row cap. A hint
2074
+ * only; `stream.truncated` prefers `_done.truncated` once it is read.
2075
+ */
1194
2076
  truncated: boolean | undefined;
1195
2077
  }
1196
2078
  /**
@@ -1199,59 +2081,133 @@ interface ExportHeaderInfo {
1199
2081
  * - `meta` is parsed from the leading `_meta` line and available
1200
2082
  * immediately (before iterating).
1201
2083
  * - `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.
2084
+ * completes; check `stream.truncated` (`_done.truncated` once read,
2085
+ * else the header / `_meta` hints — SDK contract §1.8) to detect rows the
2086
+ * export did not reach.
2087
+ * - If the body ends WITHOUT the `_done` trailer (the server stopped
2088
+ * mid-export), iteration throws `IncompleteExportError` after yielding the
2089
+ * rows that did arrive (`complete` stays `false`); a dropped connection
2090
+ * throws `NetworkError` (`CONNECTION_ERROR`); no data for `timeoutMs`
2091
+ * throws `TimeoutError` (`REQUEST_TIMEOUT`); the call's `signal` throws
2092
+ * `RequestAbortedError`. In every case the connection is released.
2093
+ * - A `_done` line with `complete: false`, or any line whose only key is
2094
+ * `_error`, also means incomplete: iteration throws `IncompleteExportError`
2095
+ * after the rows that did arrive (the `_error` body is on its `details` and
2096
+ * on `stream.error`). Unknown `_done` fields (`truncatedBy`, `credits`) are
2097
+ * kept on `done`.
2098
+ * - Lines that are not JSON objects are counted in `invalidLines`, not yielded.
2099
+ * - `_meta`/`_done`/`_error` lines are never yielded as rows.
1205
2100
  */
1206
2101
  interface ExportStream extends AsyncIterable<ExportRow> {
1207
2102
  readonly meta: ExportMeta | undefined;
1208
2103
  readonly done: ExportDone | undefined;
1209
2104
  readonly headers: ExportHeaderInfo;
2105
+ /**
2106
+ * `true` once a `_done` trailer was read that does not say
2107
+ * `complete: false`, and no `_error` line arrived — only then is the export
2108
+ * whole (SDK contract §1.8).
2109
+ */
2110
+ readonly complete: boolean;
2111
+ /** The server's `_error` line body, if one arrived (never yielded as a row). */
2112
+ readonly error: Record<string, unknown> | undefined;
2113
+ /** Data rows yielded so far. */
2114
+ readonly rowsRead: number;
2115
+ /** Lines that were not JSON objects (e.g. a half-written last line) — counted, not yielded. */
2116
+ readonly invalidLines: number;
2117
+ /**
2118
+ * Whether matching rows remain that this export did not reach, per SDK
2119
+ * contract §1.8: `_done.truncated` once the trailer has been read (API
2120
+ * 2.3.0: authoritative — set by `limit`, the server maximum or the credit
2121
+ * pool, see `done.truncatedBy`; never derived from the count; skipped stubs
2122
+ * do not count). Before the trailer: the `X-Export-Truncated` header, then
2123
+ * `_meta.truncated` — hints from the up-front count, which may be cached
2124
+ * for up to a minute and never caps the stream. `undefined` when unknown.
2125
+ */
2126
+ readonly truncated: boolean | undefined;
2127
+ /**
2128
+ * Abandon the export and release the connection (e.g. after inspecting
2129
+ * `meta` without iterating). Breaking out of `for await` does this too.
2130
+ */
2131
+ cancel(): Promise<void>;
2132
+ }
2133
+ /** Options for reading an export body. */
2134
+ interface ExportStreamOptions {
2135
+ /** Abort a read that receives no bytes for this long (ms). Default: the client timeout. */
2136
+ idleTimeoutMs?: number;
2137
+ /** Caller cancellation (aborts the read and releases the connection). */
2138
+ signal?: AbortSignal;
1210
2139
  }
1211
2140
 
1212
2141
  /**
1213
- * Webhook subscriptions — notify a URL when newly-published documents
1214
- * match saved `/search` criteria. Accessed as `client.webhooks.*`.
2142
+ * Webhook subscriptions — notify a URL when newly-published documents match
2143
+ * saved criteria (`documents.new`) and/or watched acts change
2144
+ * (`watchlist.changes`). Accessed as `client.webhooks.*`. Webhook management
2145
+ * and deliveries cost no credits.
2146
+ *
2147
+ * Write calls (create / update / delete / test) are never retried on 5xx or
2148
+ * on network errors after the connection was made — only on 429 and on
2149
+ * connect-phase failures (nothing reached the API).
1215
2150
  */
1216
2151
  declare class WebhooksAPI {
1217
2152
  private readonly http;
1218
2153
  constructor(http: HttpClient);
2154
+ private call;
1219
2155
  /**
1220
2156
  * `GET /webhooks` — every webhook owned by the caller, newest first.
1221
2157
  * The `secret` is never returned here (only once, on creation).
1222
2158
  */
1223
2159
  list(options?: CallOptions): Promise<WebhookListResponse>;
1224
2160
  /**
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).
2161
+ * `POST /webhooks` — needs `searchCriteria`, `watchCelex`, or both. If
2162
+ * `secret` is omitted the server generates one and returns it in this
2163
+ * response ONLY — store it. Rejected with 400 (`InvalidParamsError`):
2164
+ * unsupported criteria or a watch list above the plan limit carry a
2165
+ * `details` list; the tier webhook ceiling (FREE=0, STARTER=2,
2166
+ * PROFESSIONAL=10, BUSINESS=50, SCALE=100, ENTERPRISE=100) has no
2167
+ * `details` — read `current` / `limit` from `error.body`.
1230
2168
  */
1231
2169
  create(request: WebhookCreateRequest, options?: CallOptions): Promise<WebhookCreateResponse>;
1232
- /** `GET /webhooks/{id}` — full details including the 20 most recent deliveries. */
2170
+ /** `GET /webhooks/{id}` — full details incl. `retryPolicy` and the 20 most recent deliveries. */
1233
2171
  get(id: string, options?: CallOptions): Promise<WebhookResponse>;
1234
2172
  /**
1235
2173
  * `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).
2174
+ * `watchCelex` replaces the whole list; `searchCriteria: null` removes the
2175
+ * criteria (one of the two must remain). Setting `status: "ACTIVE"`
2176
+ * resets `consecutiveFailures`; moving a `FAILED` or `PAUSED` webhook to
2177
+ * `ACTIVE` also re-queues its deliveries from the last 7 days that ran out
2178
+ * of retries (count in `requeuedDeliveries`, 0 otherwise).
1238
2179
  */
1239
2180
  update(id: string, request: WebhookUpdateRequest, options?: CallOptions): Promise<WebhookUpdateResponse>;
1240
2181
  /**
1241
2182
  * `DELETE /webhooks/{id}` — permanently deletes the webhook and its
1242
- * delivery history. Resolves on 204; a repeat delete throws
1243
- * `NotFoundError`.
2183
+ * delivery history. Resolves with the server's `{ success, message }`
2184
+ * (an empty object plus `headers` on a bodiless 204); a repeat delete
2185
+ * throws `NotFoundError`.
1244
2186
  */
1245
- delete(id: string, options?: CallOptions): Promise<void>;
2187
+ delete(id: string, options?: CallOptions): Promise<WebhookDeleteResponse | undefined>;
1246
2188
  /**
1247
2189
  * `POST /webhooks/{id}/test` — synchronously POSTs a `webhook.test`
1248
2190
  * payload (HMAC-SHA256 signed via `X-Webhook-Signature`) to the webhook
1249
2191
  * URL and returns the upstream result. 10 s timeout; redirects are not
1250
- * followed.
2192
+ * followed; not recorded in the delivery history.
1251
2193
  */
1252
2194
  test(id: string, options?: CallOptions): Promise<WebhookTestResponse>;
1253
2195
  /** `GET /webhooks/{id}/deliveries` — delivery history, most recent first. */
1254
2196
  deliveries(id: string, params?: WebhookDeliveriesParams, options?: CallOptions): Promise<WebhookDeliveriesResponse>;
2197
+ /**
2198
+ * Walk the whole delivery history page by page (`limit` per page, default
2199
+ * 50), starting at `offset`, newest first (SDK contract §1.4). Each
2200
+ * delivery is yielded at most once (deduplicated on `id`): a delivery
2201
+ * created during the walk shifts later pages by one. Stops on an empty page
2202
+ * or when the offset reaches `total`. Pages are free (0 credits).
2203
+ *
2204
+ * ```ts
2205
+ * for await (const page of client.webhooks.paginateDeliveries(id)) {
2206
+ * for (const d of page.deliveries) console.log(d.status, d.responseStatus);
2207
+ * }
2208
+ * ```
2209
+ */
2210
+ paginateDeliveries(id: string, params?: WebhookDeliveriesParams, options?: CallOptions): AsyncGenerator<WebhookDeliveriesResponse, void>;
1255
2211
  }
1256
2212
 
1257
2213
  interface LexAPIOptions {
@@ -1263,19 +2219,30 @@ interface LexAPIOptions {
1263
2219
  apiKey?: string;
1264
2220
  /** API base URL. Defaults to production (`https://lex-api.com/api/v1`). */
1265
2221
  baseUrl?: string;
1266
- /** Per-request timeout in milliseconds (per attempt). Default 60_000. */
2222
+ /**
2223
+ * Per-attempt timeout in milliseconds, covering the response body (for
2224
+ * `export`: an idle timeout per read). Default 95_000 — enough for a
2225
+ * single live EUR-Lex fetch (the API caps each at 90 s, then answers with
2226
+ * a typed, refunded 504), and below Cloudflare's 100 s proxy timeout. A
2227
+ * request that needs several upstream fetches can still exceed it.
2228
+ */
1267
2229
  timeoutMs?: number;
1268
2230
  /** Injectable fetch (used for testing / polyfills). Defaults to global fetch. */
1269
2231
  fetch?: typeof fetch;
1270
- /** Retry policy. Default: 3 retries, 500 ms base, 30 s cap. */
2232
+ /** Retry policy. Default: 3 retries, 500 ms base, 30 s cap; read-only POST 5xx retries are opt-in. */
1271
2233
  retry?: RetryOptions;
1272
2234
  /** Optional suffix appended to the `User-Agent` header. */
1273
2235
  userAgentSuffix?: string;
1274
2236
  }
1275
2237
  /** Per-call overrides accepted by every SDK method. */
1276
2238
  interface CallOptions {
1277
- /** Override the client-level timeout for this call only. */
2239
+ /** Override the client-level timeout for this call only (per attempt, covering the response body). */
1278
2240
  timeoutMs?: number;
2241
+ /**
2242
+ * Cancel the call: aborts the in-flight request, any retry wait and (for
2243
+ * `export`) the stream. Rejects with `RequestAbortedError`; never retried.
2244
+ */
2245
+ signal?: AbortSignal;
1279
2246
  }
1280
2247
  /**
1281
2248
  * LexAPI client — European legal data, made queryable.
@@ -1283,6 +2250,10 @@ interface CallOptions {
1283
2250
  * Server-side only: API keys are secrets and browsers additionally forbid
1284
2251
  * setting the `User-Agent` header this SDK sends.
1285
2252
  *
2253
+ * Every JSON result carries the raw `subscription` / `usage` / `credits`
2254
+ * blocks plus an SDK-added `headers` object (`X-Source`, rate limits,
2255
+ * `X-Warning`, …) — see `ResponseHeaders`.
2256
+ *
1286
2257
  * ```ts
1287
2258
  * const client = new LexAPI({ apiKey: "lex_..." }); // or set LEXAPI_API_KEY
1288
2259
  * const info = await client.getInfo();
@@ -1293,6 +2264,10 @@ declare class LexAPI {
1293
2264
  /** Webhook subscriptions (`client.webhooks.list/create/get/update/delete/test/deliveries`). */
1294
2265
  readonly webhooks: WebhooksAPI;
1295
2266
  constructor(options?: LexAPIOptions);
2267
+ /** Redacted view for `JSON.stringify` — never includes the API key. */
2268
+ toJSON(): Record<string, unknown>;
2269
+ /** Perform a JSON request and attach the parsed response headers (+ legacy header fields). */
2270
+ private call;
1296
2271
  /**
1297
2272
  * `GET /info` — API capabilities, subscription tier, and current usage.
1298
2273
  * Free operation (0 credits); useful as a connection probe.
@@ -1301,100 +2276,138 @@ declare class LexAPI {
1301
2276
  /**
1302
2277
  * `POST /search` — search EUR-Lex with structured filters.
1303
2278
  *
2279
+ * **Cost: 3 credits per result page** (`maxPages`, tier-clamped), charged
2280
+ * upfront and refunded for pages never fetched; a search that fails
2281
+ * before its first page is refunded in full. Identical searches within
2282
+ * 60 minutes are served from a result cache (`headers.searchCache: "hit"`,
2283
+ * same price) — pass `fresh: true` to force a re-fetch.
2284
+ *
1304
2285
  * 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).
2286
+ * are surfaced, not hidden: `truncated` / `truncatedAt` / `truncatedReason`
2287
+ * (tier-capped pagination), `partial` / `partialReason` (an upstream page
2288
+ * timed out, or `source: "corpus"` — EUR-Lex unreachable, answered from
2289
+ * the corpus mirror), `postFilteredBy` (`"date"` → raise `maxPages`),
2290
+ * `ignoredDocumentTypes`, `hint` (zero results → try semantic search), and
2291
+ * `xWarning` (the `X-Warning` header, e.g. `maxPages` clamped).
1311
2292
  */
1312
2293
  search(request: SearchRequest, options?: CallOptions): Promise<SearchResponse>;
1313
2294
  /**
1314
2295
  * `POST /documentContent` — fetch a single fully-parsed document by CELEX.
1315
2296
  *
1316
- * Corpus-first with live-scrape fallback (`bypassCorpus: true` forces a
1317
- * live read). Use `include`/`fields`/`articleId` to trim the payload.
2297
+ * **Cost: 5 credits, settled by source** — 1 from the LexAPI corpus
2298
+ * (`headers.source === "corpus"`), 4 from the Publications Office Cellar
2299
+ * API (`"cellar"` / `"cellar-oj"`), 5 for a browser fetch (`"live"`).
2300
+ *
2301
+ * Check `document.textAvailability.available` before reading
2302
+ * `document.content`: a document whose text EUR-Lex does not publish is a
2303
+ * 200 with metadata and `content: null` (billed 1 credit), with the reason
2304
+ * and — for base acts — a pointer to the consolidated version. Use
2305
+ * `language` / `acceptLanguages` for other renditions and
2306
+ * `include`/`fields`/`articleId` to trim the payload.
1318
2307
  */
1319
2308
  getDocument(request: DocumentContentRequest, options?: CallOptions): Promise<DocumentContentResponse>;
1320
2309
  /**
1321
2310
  * `POST /documentContent/batch` — fetch multiple documents in one request.
1322
2311
  *
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.
2312
+ * **Cost: 5 credits per processed item, settled by source** (corpus 1,
2313
+ * Cellar / OJ 4, browser 5; `headers.batch` has the source counts). The
2314
+ * batch is clamped to the tier ceiling (FREE=1, STARTER=5,
2315
+ * PROFESSIONAL=20, BUSINESS+=50); trimmed items are not charged. Clamping
2316
+ * is surfaced: `trimmed` / `trimmedTo` / `trimmedReason` and `xWarning`.
2317
+ * Per-CELEX failures are collected in `errors`; text-unavailable items
2318
+ * stay in `documents` (counted in `textUnavailable`).
1328
2319
  */
1329
2320
  getDocumentsBatch(request: DocumentContentBatchRequest, options?: CallOptions): Promise<DocumentContentBatchResponse>;
1330
2321
  /**
1331
2322
  * `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.
2323
+ * days, default 7; up to `limit`, default 50).
2324
+ *
2325
+ * **Cost: 3 credits per result page** (~10 results each, tier-capped);
2326
+ * unfiltered requests are answered from Cellar in one query
2327
+ * (`headers.source === "cellar"`) and settle at a single page. `author`
2328
+ * arrays are sent as repeated query parameters; `documentType` and
2329
+ * `subdomain` take ONE value — EUR-Lex applies only the first of several
2330
+ * on this path (use `search` for multi-type / multi-subdomain queries). `languageFilter`
2331
+ * reports rows dropped by the language post-filter.
1335
2332
  */
1336
2333
  getRecentDocuments(params?: RecentDocumentsParams, options?: CallOptions): Promise<RecentDocumentsResponse>;
1337
2334
  /**
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.
2335
+ * `POST /documents/url` — fetch a document by any EUR-Lex URL. Shaped like
2336
+ * `getDocument` plus `sourceUrl` and `extractedCelex` echo-backs. Same
2337
+ * settle-by-source pricing (corpus 1, Cellar 4, browser 5).
1341
2338
  */
1342
2339
  getDocumentByUrl(request: DocumentByUrlRequest, options?: CallOptions): Promise<DocumentByUrlResponse>;
1343
2340
  /**
1344
2341
  * `POST /documents/metadata` — metadata only (title, dates, ECLI/ELI,
1345
- * keywords, subjects). Skips the body parse: significantly faster and
1346
- * cheaper than `getDocument`.
2342
+ * keywords, subjects, URLs). Skips the body parse: faster than
2343
+ * `getDocument`. **Cost: 5 credits, settled by source** (corpus 1, Cellar 4).
1347
2344
  */
1348
2345
  getDocumentMetadata(request: DocumentMetadataRequest, options?: CallOptions): Promise<DocumentMetadataResponse>;
1349
2346
  /**
1350
2347
  * `POST /resolve` — resolve any legal identifier (bare CELEX, EUR-Lex
1351
2348
  * URL, ELI URI, or ECLI) to the canonical CELEX plus access URLs.
2349
+ * 1 credit. ECLIs (and unmappable ELIs) resolve via the corpus
2350
+ * (`resolvedVia: "ecli-corpus"` / `"eli-corpus"`).
1352
2351
  */
1353
2352
  resolve(identifier: string, options?: CallOptions): Promise<ResolveResponse>;
1354
2353
  /**
1355
2354
  * `GET /documents/{celex}/versions` — version history, newest first,
1356
2355
  * current version included and flagged. 1 credit.
1357
2356
  */
1358
- listDocumentVersions(celex: string, params?: {
1359
- language?: string;
1360
- }, options?: CallOptions): Promise<DocumentVersionsResponse>;
2357
+ listDocumentVersions(celex: string, params?: VersionParams, options?: CallOptions): Promise<DocumentVersionsResponse>;
1361
2358
  /**
1362
2359
  * `GET /documents/{celex}/versions/{version}` — one immutable snapshot
1363
2360
  * including `parsedContent`. `corpusVersion` mirrors the
1364
2361
  * `X-Corpus-Version` response header. 1 credit.
1365
2362
  */
1366
- getDocumentVersion(celex: string, version: number, params?: {
1367
- language?: string;
1368
- }, options?: CallOptions): Promise<DocumentVersionResponse>;
2363
+ getDocumentVersion(celex: string, version: number, params?: VersionParams, options?: CallOptions): Promise<DocumentVersionResponse>;
1369
2364
  /**
1370
2365
  * `GET /documents/{celex}/at/{date}` — the snapshot LexAPI observed as
1371
2366
  * current on `date` (`YYYY-MM-DD`, end-of-day UTC inclusive). Dates
1372
2367
  * before the document entered the corpus reject with `NotFoundError`
1373
2368
  * carrying the tracking start date. 1 credit.
1374
2369
  */
1375
- getDocumentAtDate(celex: string, date: string, params?: {
1376
- language?: string;
1377
- }, options?: CallOptions): Promise<DocumentVersionResponse>;
2370
+ getDocumentAtDate(celex: string, date: string, params?: VersionParams, options?: CallOptions): Promise<DocumentVersionResponse>;
1378
2371
  /**
1379
2372
  * `POST /citations/extract` — crawl a document's EUR-Lex metadata page
1380
2373
  * for citations and persist them into the graph. Idempotent: an already
1381
- * processed document returns immediately with `alreadyExtracted: true`.
2374
+ * processed document returns `alreadyExtracted: true`. 5 credits,
2375
+ * refunded to 1 on `alreadyExtracted`.
1382
2376
  */
1383
2377
  extractCitations(celexNumber: string, options?: CallOptions): Promise<CitationExtractResponse>;
1384
2378
  /**
1385
2379
  * `GET /citations/cites/{celexNumber}` — documents this one cites
1386
2380
  * (outbound edges), grouped by target. The document must first have been
1387
- * crawled via `extractCitations` to appear here.
2381
+ * crawled via `extractCitations` to appear here. 1 credit.
1388
2382
  */
1389
2383
  getCites(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): Promise<CitesResponse>;
1390
2384
  /**
1391
2385
  * `GET /citations/cited-by/{celexNumber}` — documents that cite this one
1392
- * (inbound edges), grouped by source.
2386
+ * (inbound edges), grouped by source. 1 credit. For legislation, inbound
2387
+ * amendment / corrigendum / repeal edges are refreshed from Cellar when
2388
+ * older than 7 days (waits ≤ ~2.5 s) — see `relationSync`.
1393
2389
  */
1394
2390
  getCitedBy(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): Promise<CitedByResponse>;
2391
+ /**
2392
+ * Walk every page of `getCites` (offset in edge rows) until a short or
2393
+ * empty page (SDK contract §1.4). Each page is a billed call (1 credit).
2394
+ * Edges are ordered by extraction time only, so edges extracted at the
2395
+ * same instant or during the walk can shift: an edge may repeat or be
2396
+ * missed. A target's edges can straddle a page boundary, so the same
2397
+ * `celexNumber` may appear in two consecutive pages — merge by
2398
+ * `celexNumber` if you need one group per document.
2399
+ */
2400
+ paginateCites(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): AsyncGenerator<CitesResponse, void>;
2401
+ /**
2402
+ * Walk every page of `getCitedBy` (offset in edge rows) until a short or
2403
+ * empty page (SDK contract §1.4). Each page is a billed call (1 credit);
2404
+ * edges may repeat or be missed if extractions happen during the walk. A source's edges can straddle a page boundary, so the same
2405
+ * `celexNumber` may appear in two consecutive pages.
2406
+ */
2407
+ paginateCitedBy(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): AsyncGenerator<CitedByResponse, void>;
1395
2408
  /**
1396
2409
  * `GET /citations/network/{celexNumber}` — inbound and outbound
1397
- * neighbourhood in one call, paginated per direction.
2410
+ * neighbourhood in one call, paginated per direction. 20 credits.
1398
2411
  *
1399
2412
  * If the server-side wall-clock budget expires the endpoint still
1400
2413
  * returns 200 with `partial: true`, an EMPTY `network`, and `null`
@@ -1403,22 +2416,19 @@ declare class LexAPI {
1403
2416
  getCitationNetwork(celexNumber: string, params?: CitationNetworkParams, options?: CallOptions): Promise<CitationNetworkResponse>;
1404
2417
  /**
1405
2418
  * `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.
2419
+ * outbound edges). 20 credits. `found: false` is a graceful HTTP 200,
2420
+ * not an error. Default `maxDepth` 3 (max 8); the visited set is bounded
2421
+ * to 5000 nodes.
1408
2422
  */
1409
- getCitationPath(from: string, to: string, params?: {
1410
- maxDepth?: number;
1411
- }, options?: CallOptions): Promise<CitationPathResponse>;
2423
+ getCitationPath(from: string, to: string, params?: CitationPathParams, options?: CallOptions): Promise<CitationPathResponse>;
1412
2424
  /**
1413
2425
  * `GET /citations/related/{celexNumber}` — bibliographic-coupling
1414
2426
  * 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.
2427
+ * the seed). 20 credits. Returns a graceful empty list with `message`
2428
+ * when the seed has no outbound citations to couple on.
1417
2429
  */
1418
- getRelatedDocuments(celexNumber: string, params?: {
1419
- limit?: number;
1420
- }, options?: CallOptions): Promise<RelatedDocumentsResponse>;
1421
- /** `GET /citations/stats` — global citation graph statistics. */
2430
+ getRelatedDocuments(celexNumber: string, params?: RelatedDocumentsParams, options?: CallOptions): Promise<RelatedDocumentsResponse>;
2431
+ /** `GET /citations/stats` — global citation graph statistics. 20 credits. */
1422
2432
  getCitationStats(options?: CallOptions): Promise<CitationStatsResponse>;
1423
2433
  /**
1424
2434
  * `POST /search/semantic` — embedding-based semantic search over CJEU
@@ -1426,53 +2436,67 @@ declare class LexAPI {
1426
2436
  * keyword matching is literal.
1427
2437
  *
1428
2438
  * **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).
2439
+ * (HyDE query rewriting; ~1–3 s extra latency). HyDE is best-effort: on
2440
+ * LLM failure the search falls back to plain retrieval, the response
2441
+ * reports `hyde: false`, and the 10-credit premium is **refunded
2442
+ * automatically**.
1440
2443
  *
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.
2444
+ * Hits carry a ~600-char `snippet` by default; `includeText: true`
2445
+ * returns the full text instead. `hint` is present only on
2446
+ * low-confidence result sets. Fewer results than `limit`? The ~0.7
2447
+ * default relevance floor cut in — pass `minScore: 0.5` (or `0`).
1443
2448
  *
1444
2449
  * Persistent document identity is `(metadata.celex_id,
1445
- * metadata.document_type)`; `case_id` is snapshot-scoped and does not
1446
- * survive index rebuilds.
2450
+ * metadata.document_type)`; `case_id` is snapshot-scoped.
1447
2451
  */
1448
2452
  semanticSearch(request: SemanticCaseLawSearchOptions, options?: CallOptions): Promise<SemanticCaseLawSearchResponse>;
1449
2453
  /**
1450
2454
  * `POST /legislation/semantic` — embedding-based semantic search over EU
1451
2455
  * legislation; results are article-level matches (`article_ref`,
1452
- * `law_id`, `law_title`, `score`).
2456
+ * `law_id`, `law_title`, `score`). `limit` is never above 50 here.
2457
+ *
2458
+ * **Consolidated texts:** when an act and its consolidated version match
2459
+ * the same article you get ONE hit — the consolidated article, labelled
2460
+ * `consolidated` / `consolidatedAsOf` / `baseCelex` / `consolidatedNote`,
2461
+ * with the authentic act's own match under `baseAct`. Consolidated texts
2462
+ * are not authentic; cite `baseCelex`.
1453
2463
  *
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.
2464
+ * **`asOf` (YYYY-MM-DD):** each hit answers with the version in force on
2465
+ * that date (`asOfResolved`, `asOfVersion`, `matchedVersion`); a hit that
2466
+ * cannot be answered keeps its latest text with `asOfResolved: false` and
2467
+ * an `asOfReason`. The response adds `asOf` and `asOfSummary`.
2468
+ *
2469
+ * **Cost:** 5 credits for the search; with `asOf`, each live fetch of a
2470
+ * version the corpus does not hold reserves 5 and settles by outcome
2471
+ * (Cellar 4, browser 5, no text 1, failed 0) — at most 3 per request by
2472
+ * default. Corpus reads are free; an unaffordable fetch is skipped
2473
+ * (`insufficient_credits`), never a 402. The `hyde` option is case-law only.
1458
2474
  */
1459
- semanticLegislationSearch(request: SemanticSearchOptions, options?: CallOptions): Promise<SemanticLegislationSearchResponse>;
2475
+ semanticLegislationSearch(request: SemanticLegislationSearchOptions, options?: CallOptions): Promise<SemanticLegislationSearchResponse>;
1460
2476
  /**
1461
- * `GET /export` — stream matching corpus rows as NDJSON (BUSINESS tier;
1462
- * 402 `TierForbidden`/`CreditsExhausted`-style envelope otherwise).
2477
+ * `GET /export` — stream matching corpus rows as NDJSON (BUSINESS, SCALE
2478
+ * and ENTERPRISE; lower tiers get 403 `TierForbiddenError`). Metadata-only
2479
+ * rows are skipped unless `includeStubs: true`.
2480
+ *
2481
+ * Billing (credit plans, API 2.3.0): 1 credit per row written, at least 1
2482
+ * per export. The call is admitted for 1 credit, the matching rows are
2483
+ * counted, and the rest of 1 credit per row it can return is reserved; a
2484
+ * pool that cannot cover it throws `CreditsExhaustedError` before anything
2485
+ * streams. Unwritten rows are refunded when the stream ends; the settled
2486
+ * charge is `stream.done?.credits` (`charged`).
1463
2487
  *
1464
2488
  * Returns a single-pass async iterator over document rows. The leading
1465
2489
  * `_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.
2490
+ * trailing `_done` line is exposed as `stream.done` after iteration —
2491
+ * check `stream.truncated` (`_done.truncated` once read; the header / `_meta`
2492
+ * hints before) to detect rows the export did not reach instead of assuming
2493
+ * it was complete.
1470
2494
  *
1471
2495
  * ```ts
1472
- * const stream = await client.export({ documentType: "regulation", limit: 1000 });
1473
- * console.log(stream.meta, stream.headers.total);
2496
+ * const stream = await client.export({ documentTypeCode: "regulation", limit: 1000 });
2497
+ * console.log(stream.meta?.totalMatching, stream.headers.total);
1474
2498
  * for await (const row of stream) process(row.celex, row.parsedContent);
1475
- * if (stream.done?.truncated) console.warn("row cap hit — paginate with fetchedSince");
2499
+ * if (stream.truncated) console.warn(`not every row reached (${stream.done?.truncatedBy}) — narrow the filters or resume with changedSince`);
1476
2500
  * ```
1477
2501
  */
1478
2502
  export(params?: ExportParams, options?: CallOptions): Promise<ExportStream>;
@@ -1486,10 +2510,10 @@ declare class LexAPI {
1486
2510
  interface CreditUsage {
1487
2511
  /**
1488
2512
  * 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).
2513
+ * `credits.operation_weight`. `0` for free operations such as `/info`
2514
+ * and for legacy accounts without a credit pool (SDK contract §1.5).
1491
2515
  */
1492
- unitsCharged: number | undefined;
2516
+ unitsCharged: number;
1493
2517
  /** `credits.remaining`, falling back to `usage.remaining`. */
1494
2518
  creditsRemaining: number | undefined;
1495
2519
  /** When the quota window resets — `credits.resetsAt` falling back to `usage.resetsAt`. */
@@ -1506,6 +2530,74 @@ interface CreditUsage {
1506
2530
  */
1507
2531
  declare function getCreditUsage(response: CreditedResponse): CreditUsage;
1508
2532
 
1509
- declare const VERSION = "0.1.0";
2533
+ /**
2534
+ * Verifying incoming LexAPI webhook deliveries.
2535
+ *
2536
+ * LexAPI signs every delivery with `X-Webhook-Signature`: the hex-encoded
2537
+ * HMAC-SHA256 of the raw request body, keyed with the webhook's `secret`.
2538
+ * Verify against the raw body bytes exactly as received — never a
2539
+ * re-serialised parse (key order / whitespace changes break the digest).
2540
+ *
2541
+ * The signature covers only the body and there is no nonce, so also enforce
2542
+ * a freshness window on the signed `timestamp` and dedupe on `delivery.id`.
2543
+ *
2544
+ * Uses the Web Crypto API (`crypto.subtle`), available in Node ≥ 18, Deno
2545
+ * and Bun — no dependency.
2546
+ */
2547
+ /** Header names LexAPI sends on deliveries (lower-case, as most frameworks expose them). */
2548
+ declare const WEBHOOK_SIGNATURE_HEADER = "x-webhook-signature";
2549
+ declare const WEBHOOK_DELIVERY_HEADER = "x-webhook-delivery";
2550
+ declare const WEBHOOK_ID_HEADER = "x-webhook-id";
2551
+ type WebhookBody = string | Uint8Array | ArrayBuffer;
2552
+ interface VerifyWebhookOptions {
2553
+ /**
2554
+ * Reject deliveries whose signed `timestamp` is further than this from
2555
+ * now (replay guard). Default 300 000 ms (5 minutes). `0` disables the check.
2556
+ */
2557
+ toleranceMs?: number;
2558
+ /** Clock override (testing). Default `Date.now()`. */
2559
+ now?: number;
2560
+ }
2561
+ /**
2562
+ * Thrown by {@link verifyWebhook} when a delivery fails verification,
2563
+ * and by every helper when the `secret` is empty (`missing_secret`).
2564
+ * `instanceof` works across the ESM and CommonJS builds (shared brand).
2565
+ */
2566
+ declare class WebhookSignatureError extends Error {
2567
+ readonly reason: "missing_secret" | "missing_signature" | "invalid_signature" | "malformed_body" | "stale_timestamp";
2568
+ static [Symbol.hasInstance](value: unknown): boolean;
2569
+ constructor(reason: WebhookSignatureError["reason"], message: string);
2570
+ }
2571
+ /** Compute the expected `X-Webhook-Signature` (hex HMAC-SHA256) for a raw body. */
2572
+ declare function computeSignature(rawBody: WebhookBody, secret: string): Promise<string>;
2573
+ /**
2574
+ * `true` when `signature` (the `X-Webhook-Signature` header) is the
2575
+ * HMAC-SHA256 of `rawBody` under `secret`. Constant-time comparison.
2576
+ * Signature only — use {@link verifyWebhook} to also check freshness.
2577
+ * Throws `WebhookSignatureError("missing_secret")` for an empty secret
2578
+ * (a configuration error, not a bad delivery).
2579
+ */
2580
+ declare function verifySignature(rawBody: WebhookBody, signature: string | null | undefined, secret: string): Promise<boolean>;
2581
+ /**
2582
+ * Verify a delivery and parse it into a typed {@link WebhookPayload}
2583
+ * (switch on `event`). Throws {@link WebhookSignatureError} on a missing
2584
+ * or invalid signature, a non-JSON body, or a `timestamp` outside
2585
+ * `toleranceMs` (default 5 minutes).
2586
+ *
2587
+ * ```ts
2588
+ * app.post("/lexapi-webhook", express.raw({ type: "application/json" }), async (req, res) => {
2589
+ * try {
2590
+ * const event = await verifyWebhook(req.body, req.get("x-webhook-signature"), secret);
2591
+ * if (event.event === "watchlist.changes") handle(event.data.changes);
2592
+ * res.sendStatus(200);
2593
+ * } catch {
2594
+ * res.sendStatus(401);
2595
+ * }
2596
+ * });
2597
+ * ```
2598
+ */
2599
+ declare function verifyWebhook(rawBody: WebhookBody, signature: string | null | undefined, secret: string, options?: VerifyWebhookOptions): Promise<WebhookPayload>;
2600
+
2601
+ declare const VERSION = "0.2.0";
1510
2602
 
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 };
2603
+ export { AS_OF_REASONS, type AcceptLanguages, type Annex, type Article, type AsOfReason, type AsOfVersion, AuthenticationError, type Author, type BatchDocumentError, type BatchSourceCounts, type CallOptions, type CitationEdgeDetail, type CitationEdgeParams, type CitationEdgeSummary, type CitationExtractResponse, type CitationNeighbour, type CitationNetworkParams, type CitationNetworkResponse, type CitationPathNode, type CitationPathParams, type CitationPathResponse, type CitationStatsResponse, type CitationStatsTopCited, type CitationStatsTopCiting, type CitationType, type CitedByResponse, type CitedDocumentGroup, type CitesResponse, type CitingDocumentGroup, type ConsolidatedVersionHint, type CreditUsage, type CreditedResponse, type CreditsExhaustedDetails, CreditsExhaustedError, type CreditsInfo, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type DeliveryStatus, type Document, type DocumentByUrlRequest, type DocumentByUrlResponse, type DocumentContent, type DocumentContentBatchRequest, type DocumentContentBatchResponse, type DocumentContentRequest, type DocumentContentResponse, type DocumentMetadata, type DocumentMetadataRequest, type DocumentMetadataResponse, type DocumentType, type DocumentTypeCode, type DocumentUrls, type DocumentVersionResponse, type DocumentVersionsResponse, type Domain, type ErrorCode, type ExportDone, type ExportDoneInfo, type ExportHeaderInfo, type ExportListFilter, type ExportMeta, type ExportMetaInfo, type ExportParams, type ExportRow, type ExportStream, type ExportStreamOptions, type IdentifierType, type IncludeSelection, type IncludeToken, IncompleteExportError, type InfoResponse, type InfoSearchFilters, InternalServerError, InvalidCelexError, InvalidParamsError, InvalidResponseError, InvalidUrlError, type Language, LexAPI, LexAPIError, type LexAPIErrorContext, type LexAPIOptions, NetworkError, NotFoundError, type OneOrMany, type Procedure, type RateLimitInfo, RateLimitedError, type RecentDocumentsParams, type RecentDocumentsResponse, type Recital, type RelatedDocument, type RelatedDocumentsParams, type RelatedDocumentsResponse, type RelationSync, RequestAbortedError, type ResolveResponse, type ResolvedVia, type ResponseHeaders, type RetryOptions, type SearchRequest, type SearchResponse, type SearchResult, type Section, type SemanticCaseLawResult, type SemanticCaseLawSearchOptions, type SemanticCaseLawSearchResponse, type SemanticLanguage, type SemanticLegislationResult, type SemanticLegislationSearchOptions, type SemanticLegislationSearchResponse, type SemanticSearchOptions, type SemanticUsageInfo, ServiceUnavailableError, type Subdomain, type SubscriptionInfo, type SubscriptionTier, type Table, type TextAvailability, type TextScope, type TextUnavailableReason, TierForbiddenError, TimeoutError, type TitleSource, UpstreamError, type UsageInfo, VERSION, type VerifyWebhookOptions, type VersionEntry, type VersionParams, WEBHOOK_DELIVERY_HEADER, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, type WatchlistRelation, type WebhookBody, type WebhookChangeDocument, type WebhookCreateRequest, type WebhookCreateResponse, type WebhookCriteria, type WebhookDeleteResponse, type WebhookDeliveriesParams, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDeliveryEnvelope, type WebhookDetail, type WebhookDocumentsNewPayload, type WebhookListItem, type WebhookListResponse, type WebhookPayload, type WebhookResponse, type WebhookRetryPolicy, WebhookSignatureError, type WebhookStatus, type WebhookTestPayload, type WebhookTestResponse, type WebhookUpdateRequest, type WebhookUpdateResponse, type WebhookWatchlistChange, type WebhookWatchlistChangesPayload, WebhooksAPI, type WithResponseHeaders, computeSignature, getCreditUsage, isLexAPIError, normalizeRetryAfterSeconds, parseResponseHeaders, verifySignature, verifyWebhook };