@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/CHANGELOG.md +226 -0
- package/LICENSE +21 -0
- package/README.md +251 -96
- package/dist/index.cjs +1238 -321
- package/dist/index.d.cts +1420 -328
- package/dist/index.d.ts +1420 -328
- package/dist/index.js +1222 -320
- package/package.json +32 -13
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" | "
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
177
|
+
static readonly kind: string;
|
|
178
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
|
|
55
179
|
}
|
|
56
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
249
|
+
static readonly kind: string;
|
|
250
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number, context?: LexAPIErrorContext);
|
|
73
251
|
}
|
|
74
252
|
/**
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
124
|
-
* (UA omitted on browser runtimes, where it cannot be set).
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
*
|
|
132
|
-
* -
|
|
133
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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 (
|
|
149
|
-
*
|
|
150
|
-
*
|
|
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
|
|
435
|
+
private execute;
|
|
154
436
|
}
|
|
155
437
|
|
|
156
438
|
/**
|
|
157
|
-
* Hand-curated types mirroring `openapi.yaml` (LexAPI 2.0.0)
|
|
158
|
-
*
|
|
159
|
-
*
|
|
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
|
-
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
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
|
|
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
|
-
|
|
268
|
-
|
|
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
|
|
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[]
|
|
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
|
|
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
|
-
|
|
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
|
|
718
|
+
/** Present only on a fallback — the language served instead. */
|
|
347
719
|
languageFallback?: string;
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
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
|
-
/**
|
|
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
|
|
397
|
-
author?: Author
|
|
398
|
-
procedure?: Procedure
|
|
786
|
+
documentType?: OneOrMany<DocumentType>;
|
|
787
|
+
author?: OneOrMany<Author>;
|
|
788
|
+
procedure?: OneOrMany<Procedure>;
|
|
399
789
|
domain?: Domain;
|
|
400
|
-
|
|
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
|
|
404
|
-
* (FREE=1, STARTER=5,
|
|
405
|
-
*
|
|
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
|
|
431
|
-
* `
|
|
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
|
|
438
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
484
|
-
|
|
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
|
-
*
|
|
499
|
-
*
|
|
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
|
|
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
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
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
|
-
|
|
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
|
-
|
|
588
|
-
resolvedVia: IdentifierType;
|
|
1029
|
+
resolvedVia: ResolvedVia;
|
|
589
1030
|
celex: string;
|
|
590
|
-
urls:
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
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.
|
|
1083
|
+
/** Edges that were just extracted. Omitted when `alreadyExtracted: true`. */
|
|
617
1084
|
citations?: CitationEdgeSummary[];
|
|
618
|
-
/** True when the document had already been processed (
|
|
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`.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
814
|
-
*
|
|
815
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
866
|
-
*
|
|
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`.
|
|
872
|
-
*
|
|
873
|
-
*
|
|
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
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
1467
|
+
/** Full article text — present ONLY with `includeText: true`. */
|
|
898
1468
|
text?: string;
|
|
899
|
-
/**
|
|
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
|
|
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
|
-
|
|
934
|
-
|
|
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?:
|
|
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
|
-
/**
|
|
991
|
-
searchCriteria
|
|
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.
|
|
995
|
-
*
|
|
996
|
-
*
|
|
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?:
|
|
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?:
|
|
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?:
|
|
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
|
|
1072
|
-
*
|
|
1073
|
-
* N
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
1113
|
-
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
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
|
|
1920
|
+
/** Earliest document date to include (inclusive, `YYYY-MM-DD`; anything else is a 400). */
|
|
1121
1921
|
dateFrom?: string;
|
|
1122
|
-
/** Latest
|
|
1922
|
+
/** Latest document date to include (inclusive, `YYYY-MM-DD`). */
|
|
1123
1923
|
dateTo?: string;
|
|
1124
|
-
/**
|
|
1125
|
-
|
|
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
|
-
/**
|
|
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
|
|
1175
|
-
*
|
|
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
|
-
/**
|
|
1182
|
-
interface
|
|
1183
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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 `
|
|
1203
|
-
* the
|
|
1204
|
-
*
|
|
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
|
-
*
|
|
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` —
|
|
1226
|
-
*
|
|
1227
|
-
*
|
|
1228
|
-
*
|
|
1229
|
-
*
|
|
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
|
|
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
|
-
*
|
|
1237
|
-
* (
|
|
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
|
|
1243
|
-
* `
|
|
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<
|
|
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
|
-
/**
|
|
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
|
|
1306
|
-
*
|
|
1307
|
-
* `
|
|
1308
|
-
*
|
|
1309
|
-
* `
|
|
1310
|
-
* (the `X-Warning`
|
|
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
|
-
*
|
|
1317
|
-
*
|
|
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
|
-
*
|
|
1324
|
-
*
|
|
1325
|
-
*
|
|
1326
|
-
*
|
|
1327
|
-
*
|
|
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
|
|
1333
|
-
*
|
|
1334
|
-
*
|
|
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.
|
|
1339
|
-
*
|
|
1340
|
-
*
|
|
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:
|
|
1346
|
-
*
|
|
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
|
|
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,
|
|
1407
|
-
* Default `maxDepth` 3 (max 8); the visited set is bounded
|
|
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`
|
|
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
|
-
|
|
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
|
|
1430
|
-
*
|
|
1431
|
-
*
|
|
1432
|
-
*
|
|
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
|
-
*
|
|
1442
|
-
*
|
|
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
|
|
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
|
-
*
|
|
1455
|
-
*
|
|
1456
|
-
*
|
|
1457
|
-
*
|
|
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:
|
|
2475
|
+
semanticLegislationSearch(request: SemanticLegislationSearchOptions, options?: CallOptions): Promise<SemanticLegislationSearchResponse>;
|
|
1460
2476
|
/**
|
|
1461
|
-
* `GET /export` — stream matching corpus rows as NDJSON (BUSINESS
|
|
1462
|
-
*
|
|
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
|
-
*
|
|
1468
|
-
*
|
|
1469
|
-
*
|
|
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({
|
|
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.
|
|
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
|
-
*
|
|
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
|
|
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
|
-
|
|
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 };
|