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