@lexapi/client 0.1.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/README.md +225 -0
- package/dist/index.cjs +999 -0
- package/dist/index.d.cts +1511 -0
- package/dist/index.d.ts +1511 -0
- package/dist/index.js +954 -0
- package/package.json +52 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,1511 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Typed errors mirroring the LexAPI error envelope:
|
|
3
|
+
*
|
|
4
|
+
* { "success": false, "error": { "code": "NOT_FOUND", "message": "...", "details": {...} } }
|
|
5
|
+
*
|
|
6
|
+
* Some legacy endpoints return a bare `{ "error": "...", "message": "..." }`
|
|
7
|
+
* body without the typed envelope; the parser tolerates both shapes. Unknown
|
|
8
|
+
* codes never crash the parser — the raw code string is preserved on the
|
|
9
|
+
* base `LexAPIError` (forward compatibility).
|
|
10
|
+
*/
|
|
11
|
+
/** Stable error codes from the OpenAPI `ErrorResponse.error.code` enum. */
|
|
12
|
+
type ErrorCode = "NOT_FOUND" | "INVALID_CELEX" | "INVALID_URL" | "INVALID_PARAMS" | "RATE_LIMITED" | "TIER_FORBIDDEN" | "CREDITS_EXHAUSTED" | "UPSTREAM_ERROR" | "TIMEOUT" | "INTERNAL" | "UNAUTHORIZED" | "NETWORK_ERROR" | (string & {});
|
|
13
|
+
/** Base class for every error thrown by the SDK. */
|
|
14
|
+
declare class LexAPIError extends Error {
|
|
15
|
+
/** Stable machine-readable code (`error.code`, or derived from the HTTP status for legacy bodies). */
|
|
16
|
+
readonly code: ErrorCode;
|
|
17
|
+
/** HTTP status. `0` for client-side failures (network error, client-side timeout). */
|
|
18
|
+
readonly status: number;
|
|
19
|
+
/** The `error.details` object from the typed envelope, when present. */
|
|
20
|
+
readonly details: unknown;
|
|
21
|
+
/**
|
|
22
|
+
* Seconds to wait before retrying, when the server said so (429).
|
|
23
|
+
* Sourced from the `Retry-After` response HEADER first; the JSON
|
|
24
|
+
* `retryAfter` body field is only a fallback because it historically
|
|
25
|
+
* carried buggy epoch-seconds values (epoch-looking values are
|
|
26
|
+
* normalized to a delta).
|
|
27
|
+
*/
|
|
28
|
+
readonly retryAfter: number | undefined;
|
|
29
|
+
constructor(code: ErrorCode, message: string, status: number, details?: unknown, retryAfter?: number);
|
|
30
|
+
/**
|
|
31
|
+
* Build the most specific error subclass for a non-2xx response.
|
|
32
|
+
* Accepts both the typed envelope and the legacy bare `{error, message}` shape.
|
|
33
|
+
*/
|
|
34
|
+
static fromResponse(status: number, body: unknown, headerRetryAfter?: number): LexAPIError;
|
|
35
|
+
}
|
|
36
|
+
/** 404 — document or resource missing (`NOT_FOUND`). */
|
|
37
|
+
declare class NotFoundError extends LexAPIError {
|
|
38
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
39
|
+
}
|
|
40
|
+
/** 400 — CELEX failed validation (`INVALID_CELEX`). */
|
|
41
|
+
declare class InvalidCelexError extends LexAPIError {
|
|
42
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
43
|
+
}
|
|
44
|
+
/** 400 — URL had no resolvable CELEX (`INVALID_URL`). */
|
|
45
|
+
declare class InvalidUrlError extends LexAPIError {
|
|
46
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
47
|
+
}
|
|
48
|
+
/** 400 — missing or malformed params (`INVALID_PARAMS`). */
|
|
49
|
+
declare class InvalidParamsError extends LexAPIError {
|
|
50
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
51
|
+
}
|
|
52
|
+
/** 401 — missing, invalid, or revoked API key. */
|
|
53
|
+
declare class AuthenticationError extends LexAPIError {
|
|
54
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
55
|
+
}
|
|
56
|
+
/** 429 — quota or rate ceiling hit (`RATE_LIMITED`). Check `retryAfter`. */
|
|
57
|
+
declare class RateLimitedError extends LexAPIError {
|
|
58
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
59
|
+
}
|
|
60
|
+
/** 403 — tier-gated endpoint (`TIER_FORBIDDEN`). Retrying cannot help; upgrade the plan. */
|
|
61
|
+
declare class TierForbiddenError extends LexAPIError {
|
|
62
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
63
|
+
}
|
|
64
|
+
/** 402 — monthly credit pool exhausted (`CREDITS_EXHAUSTED`). Not retried. */
|
|
65
|
+
declare class CreditsExhaustedError extends LexAPIError {
|
|
66
|
+
/** When the monthly credit allowance resets (ISO date-time), when the server said so. */
|
|
67
|
+
readonly resetsAt: string | undefined;
|
|
68
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number, resetsAt?: string);
|
|
69
|
+
}
|
|
70
|
+
/** 502 — EUR-Lex returned an error (`UPSTREAM_ERROR`). Retry-safe on GETs. */
|
|
71
|
+
declare class UpstreamError extends LexAPIError {
|
|
72
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* `TIMEOUT` — either a server-reported 504 (upstream EUR-Lex fetch timed out,
|
|
76
|
+
* spec-marked retry-safe) or a client-side timeout (`status === 0`) when the
|
|
77
|
+
* configured `timeoutMs` elapsed before a response arrived.
|
|
78
|
+
*/
|
|
79
|
+
declare class TimeoutError extends LexAPIError {
|
|
80
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
81
|
+
}
|
|
82
|
+
/** 500 — unexpected server failure (`INTERNAL`). Not retried by default. */
|
|
83
|
+
declare class InternalServerError extends LexAPIError {
|
|
84
|
+
constructor(message: string, status?: number, details?: unknown, retryAfter?: number);
|
|
85
|
+
}
|
|
86
|
+
/** Transport-level failure: DNS, connection reset, etc. No HTTP response was received. */
|
|
87
|
+
declare class NetworkError extends LexAPIError {
|
|
88
|
+
readonly cause: unknown;
|
|
89
|
+
constructor(message: string, cause?: unknown);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
declare const DEFAULT_BASE_URL = "https://lex-api.com/api/v1";
|
|
93
|
+
declare const DEFAULT_TIMEOUT_MS = 60000;
|
|
94
|
+
/** Retry policy knobs (SDK contract §1.2). */
|
|
95
|
+
interface RetryOptions {
|
|
96
|
+
/** Max retries after the initial attempt. Default 3. Set 0 to disable retries. */
|
|
97
|
+
maxRetries?: number;
|
|
98
|
+
/** Exponential backoff base. Default 500 ms. */
|
|
99
|
+
baseDelayMs?: number;
|
|
100
|
+
/** Cap on any single wait (computed or server-directed). Default 30 000 ms. */
|
|
101
|
+
maxDelayMs?: number;
|
|
102
|
+
}
|
|
103
|
+
interface HttpClientOptions {
|
|
104
|
+
apiKey: string;
|
|
105
|
+
baseUrl: string;
|
|
106
|
+
timeoutMs: number;
|
|
107
|
+
fetchFn: typeof fetch;
|
|
108
|
+
retry: Required<RetryOptions>;
|
|
109
|
+
userAgentSuffix?: string | undefined;
|
|
110
|
+
}
|
|
111
|
+
type QueryParams = Record<string, string | number | boolean | undefined>;
|
|
112
|
+
interface RequestOptions {
|
|
113
|
+
method: "GET" | "POST" | "PUT" | "DELETE";
|
|
114
|
+
path: string;
|
|
115
|
+
query?: QueryParams;
|
|
116
|
+
body?: unknown;
|
|
117
|
+
/** Per-call timeout override. */
|
|
118
|
+
timeoutMs?: number | undefined;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* Single request core used by every SDK method.
|
|
122
|
+
*
|
|
123
|
+
* - `x-api-key` auth + `User-Agent: lexapi-typescript/<version>` on every request
|
|
124
|
+
* (UA omitted on browser runtimes, where it cannot be set).
|
|
125
|
+
* - Timeout per attempt via `AbortController`.
|
|
126
|
+
* - Retries: up to `maxRetries` (default 3) on 429/502/503/504 and on
|
|
127
|
+
* transport-level network errors, with exponential backoff + full jitter.
|
|
128
|
+
* Server-directed waits win over computed backoff, resolved in order:
|
|
129
|
+
* `Retry-After` header → `RateLimit-Reset` header → JSON `retryAfter` body
|
|
130
|
+
* field (epoch-guarded — the field was buggy epoch-seconds until a pending
|
|
131
|
+
* server fix, which is why the HEADER is authoritative) → backoff.
|
|
132
|
+
* - Non-idempotent methods (anything but GET) are retried ONLY on 429 —
|
|
133
|
+
* never on 5xx or network errors, where the request may have been applied.
|
|
134
|
+
*/
|
|
135
|
+
declare class HttpClient {
|
|
136
|
+
private readonly opts;
|
|
137
|
+
private readonly userAgent;
|
|
138
|
+
constructor(opts: HttpClientOptions);
|
|
139
|
+
/** Perform a request and parse the JSON body (204 yields `undefined`). */
|
|
140
|
+
requestJson<T>(options: RequestOptions): Promise<T>;
|
|
141
|
+
/** Like `requestJson`, but also exposes the raw `Response` (for header signals). */
|
|
142
|
+
requestJsonWithResponse<T>(options: RequestOptions): Promise<{
|
|
143
|
+
data: T;
|
|
144
|
+
response: Response;
|
|
145
|
+
}>;
|
|
146
|
+
/**
|
|
147
|
+
* Perform a request and return the raw successful `Response` without
|
|
148
|
+
* consuming the body (used by streaming endpoints such as `/export`).
|
|
149
|
+
* Non-2xx responses are parsed and thrown as typed errors; the retry
|
|
150
|
+
* policy applies before the first body byte is consumed.
|
|
151
|
+
*/
|
|
152
|
+
requestRaw(options: RequestOptions): Promise<Response>;
|
|
153
|
+
private fetchWithTimeout;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* Hand-curated types mirroring `openapi.yaml` (LexAPI 2.0.0).
|
|
158
|
+
* Field names and nullability follow the spec exactly — `type: [X, 'null']`
|
|
159
|
+
* becomes `X | null`, and properties outside a `required` list are optional.
|
|
160
|
+
*/
|
|
161
|
+
type SubscriptionTier = "FREE" | "STARTER" | "PROFESSIONAL" | "BUSINESS" | "ENTERPRISE";
|
|
162
|
+
/** ISO 639-1 code (24 official EU languages). */
|
|
163
|
+
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
|
+
type Domain = "EU_LAW" | "NATIONAL_LAW" | "ALL";
|
|
165
|
+
type Subdomain = "LEGISLATION" | "CONSLEG" | "TREATIES" | "EU_CASE_LAW" | "LEGAL_PROCEDURE" | "INTER_AGREE" | "PRE_ACTS" | "PAR_QUESTION" | "NAT_CASE_LAW";
|
|
166
|
+
/** User-facing document-type filter enum (request side). */
|
|
167
|
+
type DocumentType = "judgment" | "opinion" | "order" | "regulation" | "directive" | "decision" | "recommendation" | "communication" | "proposal" | "report" | "resolution" | "declaration" | "treaty" | "protocol" | "agreement" | "written-question" | "oral-question" | "consolidated-text" | "guideline" | "implementing" | "staff-working-document";
|
|
168
|
+
type Author = "commission" | "council" | "parliament" | "court-of-justice" | "general-court" | "ecb" | "eca" | "eesc" | "cor" | "ema" | "efsa";
|
|
169
|
+
type Procedure = "ordinary" | "codecision" | "consent" | "consultation" | "budget" | "implementing" | "delegated" | "comitology" | "appointment" | "non-legislative";
|
|
170
|
+
type TextScope = "title" | "text" | "title-text" | "any";
|
|
171
|
+
interface SubscriptionInfo {
|
|
172
|
+
tier?: SubscriptionTier;
|
|
173
|
+
maxPages?: number;
|
|
174
|
+
maxBatchSize?: number;
|
|
175
|
+
maxWebhooks?: number;
|
|
176
|
+
/** `credits` = monthly credit pool (pricing v2); `daily` = legacy daily-call model. */
|
|
177
|
+
pricingMode?: "credits" | "daily";
|
|
178
|
+
/** Legacy daily-call ceiling. `null` for credit-pool (v2) accounts. */
|
|
179
|
+
dailyLimit?: number | null;
|
|
180
|
+
/** Monthly credit allowance. `null` for legacy daily-call accounts. */
|
|
181
|
+
monthlyCredits?: number | null;
|
|
182
|
+
/** e.g. "120 requests/minute" */
|
|
183
|
+
rateLimit?: string;
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* Caller's current usage counters at request time. Dual-mode: credits over
|
|
187
|
+
* the monthly window for v2 accounts, API calls for the day on legacy
|
|
188
|
+
* accounts — read `unit` to disambiguate.
|
|
189
|
+
*/
|
|
190
|
+
interface UsageInfo {
|
|
191
|
+
current?: number;
|
|
192
|
+
limit?: number;
|
|
193
|
+
remaining?: number;
|
|
194
|
+
unit?: "credits" | "calls";
|
|
195
|
+
/** When the counter resets (ISO date-time). */
|
|
196
|
+
resetsAt?: string;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Pricing-v2 credit-pool state. Present on responses for credit-pool
|
|
200
|
+
* accounts (alongside the back-compat `usage` block); absent for legacy
|
|
201
|
+
* daily-call accounts.
|
|
202
|
+
*/
|
|
203
|
+
interface CreditsInfo {
|
|
204
|
+
/** Credits this specific request cost (0 for free operations such as /info). */
|
|
205
|
+
operation_weight?: number;
|
|
206
|
+
/** Credits used in the current monthly window. */
|
|
207
|
+
current?: number;
|
|
208
|
+
/** Total pool this window (included + topup). */
|
|
209
|
+
limit?: number;
|
|
210
|
+
remaining?: number;
|
|
211
|
+
/** Monthly credit allowance for the tier. */
|
|
212
|
+
included?: number;
|
|
213
|
+
/** Purchased top-up credits, spent after the monthly allowance; never expire. */
|
|
214
|
+
topup?: number;
|
|
215
|
+
/** When the monthly allowance resets. May be null until first set. */
|
|
216
|
+
resetsAt?: string | null;
|
|
217
|
+
}
|
|
218
|
+
/** Shape shared by every LexAPI response that reports quota state. */
|
|
219
|
+
interface CreditedResponse {
|
|
220
|
+
subscription?: SubscriptionInfo;
|
|
221
|
+
usage?: UsageInfo;
|
|
222
|
+
credits?: CreditsInfo;
|
|
223
|
+
}
|
|
224
|
+
interface InfoSearchFilters {
|
|
225
|
+
textScope?: TextScope[];
|
|
226
|
+
domain?: Domain[];
|
|
227
|
+
subdomain?: Subdomain[];
|
|
228
|
+
documentType?: DocumentType[];
|
|
229
|
+
author?: Author[];
|
|
230
|
+
procedure?: Procedure[];
|
|
231
|
+
}
|
|
232
|
+
interface InfoResponse extends CreditedResponse {
|
|
233
|
+
service?: string;
|
|
234
|
+
version?: string;
|
|
235
|
+
description?: string;
|
|
236
|
+
/** Self-describing capability map (per-endpoint method, path, parameters). */
|
|
237
|
+
endpoints?: Record<string, unknown>;
|
|
238
|
+
searchFilters?: InfoSearchFilters;
|
|
239
|
+
supportedLanguages?: Language[];
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* `include` / `fields` token. The spec's enum lists
|
|
243
|
+
* metadata/fullText/articles/recitals/sections/tables/annexes; the
|
|
244
|
+
* `DocumentContent` description additionally documents `paragraphs` as
|
|
245
|
+
* part of the accepted include set.
|
|
246
|
+
*/
|
|
247
|
+
type IncludeToken = "metadata" | "fullText" | "articles" | "recitals" | "paragraphs" | "sections" | "tables" | "annexes";
|
|
248
|
+
/** Array form, or a comma-separated string like `"metadata,articles"`. */
|
|
249
|
+
type IncludeSelection = IncludeToken[] | string;
|
|
250
|
+
/** A top-level article extracted from the document body. */
|
|
251
|
+
interface Article {
|
|
252
|
+
/** Stable id from the EUR-Lex `eli-subdivision` (e.g. `art_17`). */
|
|
253
|
+
id?: string;
|
|
254
|
+
/** e.g. `"Article 17"` */
|
|
255
|
+
number: string;
|
|
256
|
+
title?: string | null;
|
|
257
|
+
/** Plain-text body of the article (paragraphs joined). */
|
|
258
|
+
content: string;
|
|
259
|
+
}
|
|
260
|
+
/**
|
|
261
|
+
* Chapter/section hierarchy node. `articleRange` is
|
|
262
|
+
* `[firstArticleId, lastArticleId]` when the section directly contains
|
|
263
|
+
* articles; `null` for chapters whose children are sub-sections.
|
|
264
|
+
*/
|
|
265
|
+
interface Section {
|
|
266
|
+
type: "chapter" | "section";
|
|
267
|
+
number: string;
|
|
268
|
+
title: string;
|
|
269
|
+
articleRange?: [string, string] | null;
|
|
270
|
+
}
|
|
271
|
+
/** Preamble recital — also the element type of `paragraphs[]` (numbered prose). */
|
|
272
|
+
interface Recital {
|
|
273
|
+
number: number;
|
|
274
|
+
text: string;
|
|
275
|
+
}
|
|
276
|
+
interface Annex {
|
|
277
|
+
title?: string;
|
|
278
|
+
content?: string;
|
|
279
|
+
}
|
|
280
|
+
interface Table {
|
|
281
|
+
caption?: string;
|
|
282
|
+
headers?: string[];
|
|
283
|
+
rows?: string[][];
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* Structured document body. Case-law CELEXes (sector 6) emit numbered
|
|
287
|
+
* grounds in `paragraphs[]` with empty `recitals[]`; legislation keeps
|
|
288
|
+
* `recitals[]` — the two arrays are mutually exclusive on one document.
|
|
289
|
+
* With `include`/`fields` selection any of these keys can be omitted.
|
|
290
|
+
*/
|
|
291
|
+
interface DocumentContent {
|
|
292
|
+
fullText?: string;
|
|
293
|
+
articles?: Article[];
|
|
294
|
+
/** Legislative preamble recitals. Empty `[]` on case-law — see `paragraphs`. */
|
|
295
|
+
recitals?: Recital[];
|
|
296
|
+
/** Judgment grounds (case-law) or fullText splits when no structured extractor matched. */
|
|
297
|
+
paragraphs?: Recital[];
|
|
298
|
+
sections?: Section[];
|
|
299
|
+
/** Genuine data tables only (layout-table noise is filtered out server-side). */
|
|
300
|
+
tables?: Table[];
|
|
301
|
+
annexes?: Annex[];
|
|
302
|
+
}
|
|
303
|
+
/** Normalized metadata for a single document. */
|
|
304
|
+
interface DocumentMetadata {
|
|
305
|
+
/** Canonical CELEX. Always present on metadata responses. */
|
|
306
|
+
celex?: string;
|
|
307
|
+
/** Legacy alias for `celex` (metadata endpoint back-compat). */
|
|
308
|
+
celexNumber?: string;
|
|
309
|
+
/** `null` when the document is genuinely sparse — never `"Unknown Title"`. */
|
|
310
|
+
title?: string | null;
|
|
311
|
+
/** Prose form of the document, e.g. `"Regulation"`. */
|
|
312
|
+
documentType?: string | null;
|
|
313
|
+
/** Stable enum slug for `documentType` (e.g. `"regulation"`). */
|
|
314
|
+
documentTypeCode?: DocumentTypeCode | null;
|
|
315
|
+
author?: string;
|
|
316
|
+
/** Legacy DD/MM/YYYY string as published by EUR-Lex. Prefer `dateOfDocumentISO`. */
|
|
317
|
+
dateOfDocument?: string | null;
|
|
318
|
+
/** ISO-8601 date parsed from `dateOfDocument`. */
|
|
319
|
+
dateOfDocumentISO?: string | null;
|
|
320
|
+
dateOfEffect?: string | null;
|
|
321
|
+
dateOfEffectISO?: string | null;
|
|
322
|
+
dateOfPublication?: string | null;
|
|
323
|
+
dateOfPublicationISO?: string | null;
|
|
324
|
+
/** Qualifier EUR-Lex appends to dates (e.g. `"Date of signature"`). */
|
|
325
|
+
dateType?: string | null;
|
|
326
|
+
/** European Case Law Identifier (recovered from htmlMetadata for sector-6 rows). */
|
|
327
|
+
ecli?: string | null;
|
|
328
|
+
/** European Legislation Identifier path. */
|
|
329
|
+
eli?: string | null;
|
|
330
|
+
/** Court case number; joined-case ranges come as one string (`"C-171/24 to C-177/24"`). */
|
|
331
|
+
caseNumber?: string | null;
|
|
332
|
+
/** Parsed party names from case-law titles. */
|
|
333
|
+
parties?: string | null;
|
|
334
|
+
/** EUROVOC keywords, deduplicated case-insensitively. */
|
|
335
|
+
keywords?: string[];
|
|
336
|
+
/** EUR-Lex directory codes (e.g. `"13.30.99.00 Other sectors"`). */
|
|
337
|
+
directoryCodes?: string[];
|
|
338
|
+
subject?: string[];
|
|
339
|
+
}
|
|
340
|
+
/** Fully-parsed document: metadata + structured content. */
|
|
341
|
+
interface Document extends DocumentMetadata {
|
|
342
|
+
/** ISO code of the language rendition actually served. */
|
|
343
|
+
language?: string;
|
|
344
|
+
/** Present only on a fallback — the language originally requested. */
|
|
345
|
+
languageRequested?: string;
|
|
346
|
+
/** Present only on a fallback — the language served instead (`en`). */
|
|
347
|
+
languageFallback?: string;
|
|
348
|
+
content?: DocumentContent;
|
|
349
|
+
urls?: {
|
|
350
|
+
html?: string;
|
|
351
|
+
metadata?: string;
|
|
352
|
+
};
|
|
353
|
+
}
|
|
354
|
+
/**
|
|
355
|
+
* Response-side document-type slug. The spec enumerates the known values,
|
|
356
|
+
* but unknown prose is slugified server-side (e.g. `staff working document`
|
|
357
|
+
* → `staff_working_document`), so unknown strings must be tolerated.
|
|
358
|
+
*/
|
|
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 & {});
|
|
360
|
+
/** A single entry in a search results page. */
|
|
361
|
+
interface SearchResult {
|
|
362
|
+
/** Title with HTML entities decoded and sentence-spacing restored. */
|
|
363
|
+
title?: string;
|
|
364
|
+
/** Legacy field. Same value as `celex`. */
|
|
365
|
+
celexNumber?: string;
|
|
366
|
+
/** Canonical CELEX alias. */
|
|
367
|
+
celex?: string;
|
|
368
|
+
/** Legacy field. Same value as `documentType`. */
|
|
369
|
+
form?: string | null;
|
|
370
|
+
documentType?: string | null;
|
|
371
|
+
documentTypeCode?: DocumentTypeCode | null;
|
|
372
|
+
date?: string;
|
|
373
|
+
dateOfDocumentISO?: string | null;
|
|
374
|
+
author?: string | null;
|
|
375
|
+
/**
|
|
376
|
+
* Upper-case 2-letter ISO codes the document is published in. Empty `[]`
|
|
377
|
+
* for rows that don't expose the field (case-law, preparatory documents).
|
|
378
|
+
*/
|
|
379
|
+
availableLanguages?: string[];
|
|
380
|
+
url?: string;
|
|
381
|
+
}
|
|
382
|
+
/**
|
|
383
|
+
* Search filters. At least one of `query`, `dateFrom`, `dateTo`, `year`,
|
|
384
|
+
* `month`, `documentType`, `author`, `procedure`, `domain`, or `subdomain`
|
|
385
|
+
* is required — a completely empty body fails with 400.
|
|
386
|
+
*/
|
|
387
|
+
interface SearchRequest {
|
|
388
|
+
/** Free-text search. Prefer 1–3 distinctive terms; quotes force exact-phrase matching. */
|
|
389
|
+
query?: string;
|
|
390
|
+
textScope?: TextScope;
|
|
391
|
+
dateFrom?: string;
|
|
392
|
+
dateTo?: string;
|
|
393
|
+
year?: number | number[];
|
|
394
|
+
month?: number | number[];
|
|
395
|
+
/** Multi-value arrays fan out to one EUR-Lex search per resolved form code. */
|
|
396
|
+
documentType?: DocumentType | DocumentType[];
|
|
397
|
+
author?: Author | Author[];
|
|
398
|
+
procedure?: Procedure | Procedure[];
|
|
399
|
+
domain?: Domain;
|
|
400
|
+
subdomain?: Subdomain | Subdomain[];
|
|
401
|
+
language?: Language;
|
|
402
|
+
/**
|
|
403
|
+
* EUR-Lex result pages to fetch. Clamped to the subscription tier
|
|
404
|
+
* (FREE=1, STARTER=5, PROFESSIONAL=20, BUSINESS=100); if clamped, the
|
|
405
|
+
* response carries an `X-Warning` header (surfaced as `xWarning`).
|
|
406
|
+
*/
|
|
407
|
+
maxPages?: number;
|
|
408
|
+
}
|
|
409
|
+
interface SearchResponse extends CreditedResponse {
|
|
410
|
+
searchParameters?: SearchRequest;
|
|
411
|
+
/** Total matching documents on EUR-Lex. */
|
|
412
|
+
totalResults?: number;
|
|
413
|
+
/** Total result pages available on EUR-Lex. */
|
|
414
|
+
totalPages?: number;
|
|
415
|
+
pagesFetched?: number;
|
|
416
|
+
/** Number of results in this response. */
|
|
417
|
+
resultCount?: number;
|
|
418
|
+
results?: SearchResult[];
|
|
419
|
+
/**
|
|
420
|
+
* Present and `true` when the result set was capped by the tier
|
|
421
|
+
* `maxPages` limit and more pages exist on EUR-Lex. Check
|
|
422
|
+
* `truncatedAt`/`truncatedReason` — do not ignore silently.
|
|
423
|
+
*/
|
|
424
|
+
truncated?: boolean;
|
|
425
|
+
/** Approximate result count at the truncation boundary (`pagesFetched * 10`). */
|
|
426
|
+
truncatedAt?: number;
|
|
427
|
+
truncatedReason?: string;
|
|
428
|
+
/**
|
|
429
|
+
* Present and `true` when an upstream timeout dropped one of the
|
|
430
|
+
* requested pages; the pages collected before the failure are still in
|
|
431
|
+
* `results`. Check `partialReason`.
|
|
432
|
+
*/
|
|
433
|
+
partial?: boolean;
|
|
434
|
+
partialReason?: string;
|
|
435
|
+
/**
|
|
436
|
+
* Comma-joined dimensions on which a controller-side post-filter dropped
|
|
437
|
+
* rows (`author`, `date`, `documentType`). `"date"` signals the
|
|
438
|
+
* recall-vs-pagination trade-off: raise `maxPages` to widen recall on
|
|
439
|
+
* tight date filters.
|
|
440
|
+
*/
|
|
441
|
+
postFilteredBy?: string;
|
|
442
|
+
/** Requested types that resolve to no EUR-Lex form code (reported, not silently dropped). */
|
|
443
|
+
ignoredDocumentTypes?: string[];
|
|
444
|
+
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
|
+
*/
|
|
449
|
+
xWarning?: string;
|
|
450
|
+
}
|
|
451
|
+
interface DocumentContentRequest {
|
|
452
|
+
celexNumber: string;
|
|
453
|
+
/** Force a live scrape, bypassing the corpus cache. */
|
|
454
|
+
bypassCorpus?: boolean;
|
|
455
|
+
/**
|
|
456
|
+
* Language rendition to return (whole document). Falls back to English
|
|
457
|
+
* when unavailable — see `languageRequested`/`languageFallback` on the
|
|
458
|
+
* document.
|
|
459
|
+
*/
|
|
460
|
+
language?: Language;
|
|
461
|
+
/** Trim the response payload to the listed pieces. */
|
|
462
|
+
include?: IncludeSelection;
|
|
463
|
+
/** Alias accepted alongside `include`. */
|
|
464
|
+
fields?: IncludeSelection;
|
|
465
|
+
/** Narrow `content.articles` to a single article (`art_17`, `17`, or `Article 17`). */
|
|
466
|
+
articleId?: string;
|
|
467
|
+
}
|
|
468
|
+
interface DocumentContentResponse extends CreditedResponse {
|
|
469
|
+
success: boolean;
|
|
470
|
+
document: Document;
|
|
471
|
+
}
|
|
472
|
+
interface DocumentContentBatchRequest {
|
|
473
|
+
/** Truncated to the tier batch ceiling (FREE=1, STARTER=5, PROFESSIONAL=20, BUSINESS=50). */
|
|
474
|
+
celexNumbers: string[];
|
|
475
|
+
bypassCorpus?: boolean;
|
|
476
|
+
language?: Language;
|
|
477
|
+
include?: IncludeSelection;
|
|
478
|
+
fields?: IncludeSelection;
|
|
479
|
+
articleId?: string;
|
|
480
|
+
}
|
|
481
|
+
/** One failed CELEX from a batch fetch. */
|
|
482
|
+
interface BatchDocumentError {
|
|
483
|
+
celexNumber?: string;
|
|
484
|
+
/** Short error slug (includes upstream timeouts as `"FetchTimeoutError" | "TIMEOUT"`). */
|
|
485
|
+
error?: string;
|
|
486
|
+
message?: string;
|
|
487
|
+
}
|
|
488
|
+
interface DocumentContentBatchResponse extends CreditedResponse {
|
|
489
|
+
success: boolean;
|
|
490
|
+
/** Number of CELEX numbers in the request body. */
|
|
491
|
+
requested: number;
|
|
492
|
+
/** Number actually processed after tier clamping. */
|
|
493
|
+
processed: number;
|
|
494
|
+
successful: number;
|
|
495
|
+
failed: number;
|
|
496
|
+
/**
|
|
497
|
+
* Present and `true` when the request exceeded the tier batch ceiling.
|
|
498
|
+
* Mirrors the `X-Warning` header (also surfaced as `xWarning`). Check
|
|
499
|
+
* `trimmedTo`/`trimmedReason` — trimmed entries were silently dropped
|
|
500
|
+
* server-side.
|
|
501
|
+
*/
|
|
502
|
+
trimmed?: boolean;
|
|
503
|
+
trimmedTo?: number;
|
|
504
|
+
trimmedReason?: string;
|
|
505
|
+
documents: Document[];
|
|
506
|
+
/** Per-CELEX failures — the batch does not abort on individual errors. */
|
|
507
|
+
errors: BatchDocumentError[];
|
|
508
|
+
/** SDK-added: `X-Warning` response header (batch clamped), when present. */
|
|
509
|
+
xWarning?: string;
|
|
510
|
+
}
|
|
511
|
+
interface RecentDocumentsParams {
|
|
512
|
+
/** How many days back from today to include. Default 7. */
|
|
513
|
+
days?: number;
|
|
514
|
+
documentType?: DocumentType;
|
|
515
|
+
author?: Author;
|
|
516
|
+
domain?: Domain;
|
|
517
|
+
subdomain?: Subdomain;
|
|
518
|
+
/** Result language (default `en`). */
|
|
519
|
+
language?: Language;
|
|
520
|
+
/** Maximum number of results to return. Default 50. */
|
|
521
|
+
limit?: number;
|
|
522
|
+
}
|
|
523
|
+
interface RecentDocumentsResponse extends CreditedResponse {
|
|
524
|
+
success: boolean;
|
|
525
|
+
/** Echo of the resolved query parameters (with computed `dateFrom`/`dateTo`). */
|
|
526
|
+
parameters?: {
|
|
527
|
+
days?: number;
|
|
528
|
+
dateFrom?: string;
|
|
529
|
+
dateTo?: string;
|
|
530
|
+
documentType?: string | null;
|
|
531
|
+
author?: string | null;
|
|
532
|
+
domain?: string | null;
|
|
533
|
+
subdomain?: string | null;
|
|
534
|
+
language?: string;
|
|
535
|
+
limit?: number;
|
|
536
|
+
};
|
|
537
|
+
totalResults?: number;
|
|
538
|
+
resultCount?: number;
|
|
539
|
+
results: SearchResult[];
|
|
540
|
+
/** Present only when the language post-filter dropped rows. */
|
|
541
|
+
languageFilter?: {
|
|
542
|
+
requested: string;
|
|
543
|
+
kept: number;
|
|
544
|
+
beforeFilter: number;
|
|
545
|
+
};
|
|
546
|
+
fetchedAt?: string;
|
|
547
|
+
/** SDK-added: `X-Warning` response header, when present. */
|
|
548
|
+
xWarning?: string;
|
|
549
|
+
}
|
|
550
|
+
interface DocumentByUrlRequest {
|
|
551
|
+
/** Any `eur-lex.europa.eu` URL containing a CELEX (path segment or `uri=` param). */
|
|
552
|
+
url: string;
|
|
553
|
+
include?: IncludeSelection;
|
|
554
|
+
fields?: IncludeSelection;
|
|
555
|
+
articleId?: string;
|
|
556
|
+
}
|
|
557
|
+
interface DocumentByUrlResponse extends CreditedResponse {
|
|
558
|
+
success: boolean;
|
|
559
|
+
/** The exact URL passed in the request body. */
|
|
560
|
+
sourceUrl: string;
|
|
561
|
+
/** CELEX number extracted from `sourceUrl`, uppercased. */
|
|
562
|
+
extractedCelex: string;
|
|
563
|
+
document: Document;
|
|
564
|
+
}
|
|
565
|
+
interface DocumentMetadataRequest {
|
|
566
|
+
celexNumber: string;
|
|
567
|
+
bypassCorpus?: boolean;
|
|
568
|
+
}
|
|
569
|
+
interface DocumentMetadataResponse extends CreditedResponse {
|
|
570
|
+
success: boolean;
|
|
571
|
+
/** Metadata-only — no `content`. Includes the canonical EUR-Lex URLs. */
|
|
572
|
+
metadata: DocumentMetadata & {
|
|
573
|
+
urls?: {
|
|
574
|
+
html?: string;
|
|
575
|
+
metadata?: string;
|
|
576
|
+
pdf?: string;
|
|
577
|
+
xml?: string;
|
|
578
|
+
};
|
|
579
|
+
};
|
|
580
|
+
}
|
|
581
|
+
type IdentifierType = "celex" | "url" | "eli" | "ecli";
|
|
582
|
+
interface ResolveResponse {
|
|
583
|
+
success: boolean;
|
|
584
|
+
/** Echo of the caller's input. */
|
|
585
|
+
identifier: string;
|
|
586
|
+
identifierType: IdentifierType;
|
|
587
|
+
/** Which resolution path matched. Pure path for celex/url/eli; corpus lookup for ecli. */
|
|
588
|
+
resolvedVia: IdentifierType;
|
|
589
|
+
celex: string;
|
|
590
|
+
urls: {
|
|
591
|
+
metadata?: string;
|
|
592
|
+
html?: string;
|
|
593
|
+
pdf?: string;
|
|
594
|
+
xml?: string;
|
|
595
|
+
};
|
|
596
|
+
}
|
|
597
|
+
/** Classification of a citation edge. */
|
|
598
|
+
type CitationType = "reference" | "amendment" | "repeal" | "implementation" | "legal-basis" | "proposal";
|
|
599
|
+
/** Edge shape emitted on fresh extraction. */
|
|
600
|
+
interface CitationEdgeSummary {
|
|
601
|
+
targetCelex?: string;
|
|
602
|
+
citationType?: CitationType;
|
|
603
|
+
/** Surrounding text around the citation on the source metadata page, when available. */
|
|
604
|
+
contextSnippet?: string | null;
|
|
605
|
+
}
|
|
606
|
+
interface CitationExtractResponse {
|
|
607
|
+
success: boolean;
|
|
608
|
+
message?: string;
|
|
609
|
+
/** Present on fresh extraction. Omitted when `alreadyExtracted` is true. */
|
|
610
|
+
document?: {
|
|
611
|
+
celexNumber?: string;
|
|
612
|
+
title?: string | null;
|
|
613
|
+
};
|
|
614
|
+
/** Number of citation edges persisted (or already on file). */
|
|
615
|
+
citationCount?: number;
|
|
616
|
+
/** Edges that were just extracted. Empty array when `alreadyExtracted: true`. */
|
|
617
|
+
citations?: CitationEdgeSummary[];
|
|
618
|
+
/** True when the document had already been processed (extraction is idempotent). */
|
|
619
|
+
alreadyExtracted?: boolean;
|
|
620
|
+
}
|
|
621
|
+
/** A single citation edge with classification, context, and timestamp. */
|
|
622
|
+
interface CitationEdgeDetail {
|
|
623
|
+
citationType?: CitationType;
|
|
624
|
+
contextSnippet?: string | null;
|
|
625
|
+
extractedAt?: string;
|
|
626
|
+
}
|
|
627
|
+
/** All edges from one source document into the target (cited-by grouping). */
|
|
628
|
+
interface CitingDocumentGroup {
|
|
629
|
+
celexNumber?: string;
|
|
630
|
+
title?: string | null;
|
|
631
|
+
citationCount?: number;
|
|
632
|
+
citations?: CitationEdgeDetail[];
|
|
633
|
+
}
|
|
634
|
+
/** All edges from the source document into one target (cites grouping). */
|
|
635
|
+
interface CitedDocumentGroup {
|
|
636
|
+
celexNumber?: string;
|
|
637
|
+
title?: string | null;
|
|
638
|
+
citationCount?: number;
|
|
639
|
+
citations?: CitationEdgeDetail[];
|
|
640
|
+
}
|
|
641
|
+
/** Pagination filters shared by the cites / cited-by endpoints. */
|
|
642
|
+
interface CitationEdgeParams {
|
|
643
|
+
/** Filter to a single citation type. */
|
|
644
|
+
citationType?: CitationType;
|
|
645
|
+
/** Max edges to return per page. Default 100. */
|
|
646
|
+
limit?: number;
|
|
647
|
+
/** Pagination offset (in edges, not documents). Default 0. */
|
|
648
|
+
offset?: number;
|
|
649
|
+
}
|
|
650
|
+
interface CitedByResponse {
|
|
651
|
+
success: boolean;
|
|
652
|
+
/** The CELEX whose inbound edges are being listed. */
|
|
653
|
+
targetDocument: string;
|
|
654
|
+
/** Total inbound edges matching the filter (across all pages). */
|
|
655
|
+
totalCitations?: number;
|
|
656
|
+
uniqueDocuments?: number;
|
|
657
|
+
limit?: number;
|
|
658
|
+
offset?: number;
|
|
659
|
+
citedBy: CitingDocumentGroup[];
|
|
660
|
+
}
|
|
661
|
+
interface CitesResponse {
|
|
662
|
+
success: boolean;
|
|
663
|
+
/** The CELEX whose outbound edges are being listed. */
|
|
664
|
+
sourceDocument: string;
|
|
665
|
+
totalCitations?: number;
|
|
666
|
+
uniqueDocuments?: number;
|
|
667
|
+
limit?: number;
|
|
668
|
+
offset?: number;
|
|
669
|
+
cites: CitedDocumentGroup[];
|
|
670
|
+
}
|
|
671
|
+
/** A neighbour in the citation graph, deduplicated across edge types. */
|
|
672
|
+
interface CitationNeighbour {
|
|
673
|
+
celexNumber?: string;
|
|
674
|
+
title?: string | null;
|
|
675
|
+
/** Number of edges to/from this neighbour. */
|
|
676
|
+
count?: number;
|
|
677
|
+
/** Union of `citationType` values across all edges to/from it. */
|
|
678
|
+
types?: CitationType[];
|
|
679
|
+
}
|
|
680
|
+
interface CitationNetworkParams {
|
|
681
|
+
/** Filter both directions to a single citation type. */
|
|
682
|
+
citationType?: CitationType;
|
|
683
|
+
/** Max edges to fetch per direction (default 100, max 500). */
|
|
684
|
+
limit?: number;
|
|
685
|
+
/** Pagination offset (in edges, applied to both directions). */
|
|
686
|
+
offset?: number;
|
|
687
|
+
}
|
|
688
|
+
interface CitationNetworkResponse {
|
|
689
|
+
success: boolean;
|
|
690
|
+
/** The centre CELEX. */
|
|
691
|
+
document: string;
|
|
692
|
+
network: {
|
|
693
|
+
celexNumber: string;
|
|
694
|
+
/** Unique outbound neighbours in THIS PAGE — see `paging.citesTotal` for the unbounded total. */
|
|
695
|
+
citesCount: number;
|
|
696
|
+
/** Unique inbound neighbours in THIS PAGE — see `paging.citedByTotal` for the unbounded total. */
|
|
697
|
+
citedByCount: number;
|
|
698
|
+
cites: CitationNeighbour[];
|
|
699
|
+
citedBy: CitationNeighbour[];
|
|
700
|
+
};
|
|
701
|
+
paging: {
|
|
702
|
+
/** Effective per-direction limit after clamping. */
|
|
703
|
+
limit: number;
|
|
704
|
+
offset: number;
|
|
705
|
+
/** Total outbound edges matching the query. `null` when the response is partial. */
|
|
706
|
+
citesTotal: number | null;
|
|
707
|
+
/** Total inbound edges matching the query. `null` when the response is partial. */
|
|
708
|
+
citedByTotal: number | null;
|
|
709
|
+
};
|
|
710
|
+
/**
|
|
711
|
+
* Present and `true` when the server-side wall-clock budget expired —
|
|
712
|
+
* `network` arrays are empty and paging totals `null`. Retry with a
|
|
713
|
+
* smaller `limit` or use the per-direction endpoints. Do not treat an
|
|
714
|
+
* empty partial network as "no citations".
|
|
715
|
+
*/
|
|
716
|
+
partial?: boolean;
|
|
717
|
+
partialReason?: "TIMEOUT";
|
|
718
|
+
message?: string;
|
|
719
|
+
/** The server-side budget that expired (only on partial responses). */
|
|
720
|
+
timeoutMs?: number;
|
|
721
|
+
}
|
|
722
|
+
interface CitationStatsTopCited {
|
|
723
|
+
celexNumber?: string;
|
|
724
|
+
title?: string | null;
|
|
725
|
+
citedByCount?: number;
|
|
726
|
+
}
|
|
727
|
+
interface CitationStatsTopCiting {
|
|
728
|
+
celexNumber?: string;
|
|
729
|
+
title?: string | null;
|
|
730
|
+
citesCount?: number;
|
|
731
|
+
}
|
|
732
|
+
interface CitationStatsResponse {
|
|
733
|
+
success: boolean;
|
|
734
|
+
stats: {
|
|
735
|
+
totalCitations: number;
|
|
736
|
+
uniqueSourceDocuments: number;
|
|
737
|
+
uniqueTargetDocuments: number;
|
|
738
|
+
/** Top-10 most-cited documents. */
|
|
739
|
+
mostCited: CitationStatsTopCited[];
|
|
740
|
+
/** Top-10 documents with the most outbound citations. */
|
|
741
|
+
mostCiting: CitationStatsTopCiting[];
|
|
742
|
+
};
|
|
743
|
+
}
|
|
744
|
+
interface CitationPathNode {
|
|
745
|
+
celexNumber: string;
|
|
746
|
+
/** Enriched at read time from the corpus where available. */
|
|
747
|
+
title: string | null;
|
|
748
|
+
}
|
|
749
|
+
interface CitationPathResponse {
|
|
750
|
+
success: boolean;
|
|
751
|
+
from: string;
|
|
752
|
+
to: string;
|
|
753
|
+
/** `false` is a graceful HTTP 200, not an error — see `message`. */
|
|
754
|
+
found: boolean;
|
|
755
|
+
/** Number of edges (0 for self-loops). `null` when `found` is false. */
|
|
756
|
+
pathLength?: number | null;
|
|
757
|
+
/** The depth budget actually used. */
|
|
758
|
+
maxDepth?: number;
|
|
759
|
+
path: CitationPathNode[];
|
|
760
|
+
/** Present when `found` is false. */
|
|
761
|
+
message?: string;
|
|
762
|
+
}
|
|
763
|
+
interface RelatedDocument {
|
|
764
|
+
celexNumber: string;
|
|
765
|
+
title?: string | null;
|
|
766
|
+
/** Number of citation targets the related document shares with the seed. */
|
|
767
|
+
sharedCount: number;
|
|
768
|
+
sharedTargets?: string[];
|
|
769
|
+
}
|
|
770
|
+
interface RelatedDocumentsResponse {
|
|
771
|
+
success: boolean;
|
|
772
|
+
celexNumber: string;
|
|
773
|
+
method: "bibliographic-coupling";
|
|
774
|
+
/** Outbound citations on the seed, used to compute coupling. */
|
|
775
|
+
seedCitationCount?: number;
|
|
776
|
+
count: number;
|
|
777
|
+
related: RelatedDocument[];
|
|
778
|
+
/** Present when the seed has no outbound citations to couple on. */
|
|
779
|
+
message?: string;
|
|
780
|
+
}
|
|
781
|
+
/** Languages accepted by the semantic endpoints (narrower than `Language`). */
|
|
782
|
+
type SemanticLanguage = "en" | "fr" | "de" | "es" | "it" | "sl" | "el" | "nl" | "pt" | "pl";
|
|
783
|
+
/**
|
|
784
|
+
* SDK-side options for the semantic endpoints. Camel-cased; the SDK maps
|
|
785
|
+
* them to the wire shape (`min_score`, `include: ["text"]`).
|
|
786
|
+
*/
|
|
787
|
+
interface SemanticSearchOptions {
|
|
788
|
+
/** Natural-language query to embed. */
|
|
789
|
+
query: string;
|
|
790
|
+
/** Max results. Clamped to the caller's tier ceiling. Default 10. */
|
|
791
|
+
limit?: number;
|
|
792
|
+
/**
|
|
793
|
+
* Drop results below this cosine similarity (wire: `min_score`).
|
|
794
|
+
* Unset applies the upstream's default relevance floor of ~0.7 — if you
|
|
795
|
+
* got fewer results than `limit`, the floor cut in; pass `0.5` (or lower)
|
|
796
|
+
* to widen recall, `0` to disable the floor entirely.
|
|
797
|
+
*/
|
|
798
|
+
minScore?: number;
|
|
799
|
+
/** Language of returned content. Default `en`. */
|
|
800
|
+
language?: SemanticLanguage;
|
|
801
|
+
/**
|
|
802
|
+
* Set `true` to receive the full document text in each hit (wire:
|
|
803
|
+
* `include: ["text"]`). By default each hit carries a ~600-char snippet
|
|
804
|
+
* instead — about a 10-50x payload reduction.
|
|
805
|
+
*/
|
|
806
|
+
includeText?: boolean;
|
|
807
|
+
/** Free-form filter object forwarded to the semantic backend. */
|
|
808
|
+
filters?: Record<string, unknown>;
|
|
809
|
+
}
|
|
810
|
+
/** Options for `semanticSearch` (case law) — adds HyDE query rewriting. */
|
|
811
|
+
interface SemanticCaseLawSearchOptions extends SemanticSearchOptions {
|
|
812
|
+
/**
|
|
813
|
+
* Enable HyDE query rewriting (case-law endpoint only; ignored by
|
|
814
|
+
* `/legislation/semantic`): an LLM drafts the passage a relevant
|
|
815
|
+
* judgment would contain and retrieval fuses plain-query and
|
|
816
|
+
* hypothetical-passage rankings. Markedly better recall on short or
|
|
817
|
+
* keyword-style queries.
|
|
818
|
+
*
|
|
819
|
+
* **Billing: 15 credits instead of 5**, and adds ~1–3 s of latency (one
|
|
820
|
+
* LLM call). Best-effort: if generation fails the search transparently
|
|
821
|
+
* falls back to plain retrieval, the response reports `hyde: false`,
|
|
822
|
+
* and the 10-credit premium is **automatically refunded**
|
|
823
|
+
* (`credits.operation_weight` reflects the base rate).
|
|
824
|
+
*
|
|
825
|
+
* Must be a JSON boolean — string values are rejected with 400.
|
|
826
|
+
*/
|
|
827
|
+
hyde?: boolean;
|
|
828
|
+
}
|
|
829
|
+
/** Single case-law match from `/search/semantic`. */
|
|
830
|
+
interface SemanticCaseLawResult {
|
|
831
|
+
/**
|
|
832
|
+
* Snapshot-scoped UUID — regenerated when the upstream index is rebuilt.
|
|
833
|
+
* Do NOT store as a long-term identifier; use
|
|
834
|
+
* `(metadata.celex_id, metadata.document_type)` for persistent joins.
|
|
835
|
+
*/
|
|
836
|
+
case_id?: string | null;
|
|
837
|
+
/** Cosine similarity, 0–1. */
|
|
838
|
+
score?: number;
|
|
839
|
+
/** Matching passage; replaced with the full document text when a parsed copy is available. */
|
|
840
|
+
text?: string;
|
|
841
|
+
case_name?: string | null;
|
|
842
|
+
case_number?: string | null;
|
|
843
|
+
ecli?: string | null;
|
|
844
|
+
court?: string | null;
|
|
845
|
+
/** Always includes `celex_id` when available — the persistent identity key. */
|
|
846
|
+
metadata?: {
|
|
847
|
+
celex_id?: string;
|
|
848
|
+
document_type?: string | null;
|
|
849
|
+
[key: string]: unknown;
|
|
850
|
+
};
|
|
851
|
+
}
|
|
852
|
+
/** Semantic-specific quota counters (legacy daily-call plans only). */
|
|
853
|
+
interface SemanticUsageInfo {
|
|
854
|
+
current?: number;
|
|
855
|
+
limit?: number;
|
|
856
|
+
remaining?: number;
|
|
857
|
+
}
|
|
858
|
+
interface SemanticCaseLawSearchResponse {
|
|
859
|
+
success: boolean;
|
|
860
|
+
searchType?: "semantic-case-law";
|
|
861
|
+
query?: string;
|
|
862
|
+
resultCount?: number;
|
|
863
|
+
results: SemanticCaseLawResult[];
|
|
864
|
+
/**
|
|
865
|
+
* Present only on best-effort responses (low-confidence hits below your
|
|
866
|
+
* `minScore`, or noise-floor fallback) — its presence is itself the
|
|
867
|
+
* low-confidence signal. Omitted entirely (never `null`) otherwise.
|
|
868
|
+
*/
|
|
869
|
+
hint?: string;
|
|
870
|
+
/**
|
|
871
|
+
* Present only when the request set `hyde: true`. Reports whether HyDE
|
|
872
|
+
* rewriting actually ran; `false` means generation failed, the search
|
|
873
|
+
* fell back to plain retrieval, and the 10-credit premium was refunded.
|
|
874
|
+
*/
|
|
875
|
+
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
|
+
*/
|
|
881
|
+
hypotheticalDocument?: string;
|
|
882
|
+
/** Opaque upstream pass-through; shape not stable — use `tookMs` for timing. */
|
|
883
|
+
metadata?: Record<string, unknown>;
|
|
884
|
+
/** Server-measured wall-clock time for this request, in ms. */
|
|
885
|
+
tookMs?: number;
|
|
886
|
+
semanticUsage?: SemanticUsageInfo;
|
|
887
|
+
subscription?: SubscriptionInfo & {
|
|
888
|
+
maxResults?: number;
|
|
889
|
+
};
|
|
890
|
+
usage?: UsageInfo;
|
|
891
|
+
credits?: CreditsInfo;
|
|
892
|
+
}
|
|
893
|
+
/** Single article-level match from `/legislation/semantic`. */
|
|
894
|
+
interface SemanticLegislationResult {
|
|
895
|
+
/** Cosine similarity, 0–1. */
|
|
896
|
+
score?: number;
|
|
897
|
+
/** Matching article text from the embedding index. */
|
|
898
|
+
text?: string;
|
|
899
|
+
/** Article identifier (e.g. `Article 17`). */
|
|
900
|
+
article_ref?: string | null;
|
|
901
|
+
/** CELEX identifier of the parent legal act. */
|
|
902
|
+
law_id?: string | null;
|
|
903
|
+
law_title?: string | null;
|
|
904
|
+
metadata?: Record<string, unknown>;
|
|
905
|
+
}
|
|
906
|
+
interface SemanticLegislationSearchResponse {
|
|
907
|
+
success: boolean;
|
|
908
|
+
searchType?: "semantic-legislation";
|
|
909
|
+
query?: string;
|
|
910
|
+
resultCount?: number;
|
|
911
|
+
results: SemanticLegislationResult[];
|
|
912
|
+
/** Present only on best-effort responses — see `SemanticCaseLawSearchResponse.hint`. */
|
|
913
|
+
hint?: string;
|
|
914
|
+
/** Opaque upstream pass-through; shape not stable — use `tookMs` for timing. */
|
|
915
|
+
metadata?: Record<string, unknown>;
|
|
916
|
+
tookMs?: number;
|
|
917
|
+
semanticUsage?: SemanticUsageInfo;
|
|
918
|
+
subscription?: SubscriptionInfo & {
|
|
919
|
+
maxResults?: number;
|
|
920
|
+
};
|
|
921
|
+
usage?: UsageInfo;
|
|
922
|
+
credits?: CreditsInfo;
|
|
923
|
+
}
|
|
924
|
+
/** Operational state. `FAILED` is set automatically after repeated delivery errors. */
|
|
925
|
+
type WebhookStatus = "ACTIVE" | "PAUSED" | "FAILED";
|
|
926
|
+
type DeliveryStatus = "PENDING" | "SUCCESS" | "FAILED" | "RETRYING";
|
|
927
|
+
/** Summary shape used in list responses. The `secret` is never included here. */
|
|
928
|
+
interface WebhookListItem {
|
|
929
|
+
id?: string;
|
|
930
|
+
name?: string;
|
|
931
|
+
url?: string;
|
|
932
|
+
status?: WebhookStatus;
|
|
933
|
+
/** The saved search — same shape as a `/search` request body. */
|
|
934
|
+
searchCriteria?: SearchRequest;
|
|
935
|
+
lastChecked?: string | null;
|
|
936
|
+
lastTriggered?: string | null;
|
|
937
|
+
consecutiveFailures?: number;
|
|
938
|
+
/** Total delivery attempts ever made (success and failure combined). */
|
|
939
|
+
deliveryCount?: number;
|
|
940
|
+
createdAt?: string;
|
|
941
|
+
}
|
|
942
|
+
/** A single delivery attempt. */
|
|
943
|
+
interface WebhookDelivery {
|
|
944
|
+
id?: string;
|
|
945
|
+
status?: DeliveryStatus;
|
|
946
|
+
/** The JSON payload that was POSTed (or queued) to the webhook URL. */
|
|
947
|
+
payload?: Record<string, unknown>;
|
|
948
|
+
/** HTTP status code returned by the webhook URL. */
|
|
949
|
+
responseStatus?: number | null;
|
|
950
|
+
/** Truncated response body (max 500 chars). */
|
|
951
|
+
responseBody?: string | null;
|
|
952
|
+
errorMessage?: string | null;
|
|
953
|
+
attemptCount?: number;
|
|
954
|
+
nextRetryAt?: string | null;
|
|
955
|
+
deliveredAt?: string | null;
|
|
956
|
+
createdAt?: string;
|
|
957
|
+
}
|
|
958
|
+
/** Full webhook details (no `secret`). */
|
|
959
|
+
interface WebhookDetail {
|
|
960
|
+
id?: string;
|
|
961
|
+
name?: string;
|
|
962
|
+
url?: string;
|
|
963
|
+
status?: WebhookStatus;
|
|
964
|
+
searchCriteria?: SearchRequest;
|
|
965
|
+
lastChecked?: string | null;
|
|
966
|
+
lastTriggered?: string | null;
|
|
967
|
+
consecutiveFailures?: number;
|
|
968
|
+
maxRetries?: number;
|
|
969
|
+
createdAt?: string;
|
|
970
|
+
updatedAt?: string;
|
|
971
|
+
/** Up to 20 most recent delivery attempts, newest first. */
|
|
972
|
+
recentDeliveries?: WebhookDelivery[];
|
|
973
|
+
}
|
|
974
|
+
interface WebhookListResponse {
|
|
975
|
+
success: boolean;
|
|
976
|
+
count?: number;
|
|
977
|
+
webhooks: WebhookListItem[];
|
|
978
|
+
}
|
|
979
|
+
interface WebhookCreateRequest {
|
|
980
|
+
/** User-friendly label for the webhook. */
|
|
981
|
+
name: string;
|
|
982
|
+
/** HTTPS endpoint to POST matching documents to. */
|
|
983
|
+
url: string;
|
|
984
|
+
/**
|
|
985
|
+
* Optional HMAC-SHA256 signing secret. If omitted, the server generates
|
|
986
|
+
* a 32-byte hex value and returns it in the create response — the ONLY
|
|
987
|
+
* time it is exposed. Store it.
|
|
988
|
+
*/
|
|
989
|
+
secret?: string;
|
|
990
|
+
/** Documents newly matching these filters trigger a delivery to `url`. */
|
|
991
|
+
searchCriteria: SearchRequest;
|
|
992
|
+
}
|
|
993
|
+
/**
|
|
994
|
+
* Partial update — only the supplied fields are changed. Setting `status`
|
|
995
|
+
* to `ACTIVE` additionally resets `consecutiveFailures` to 0 (how you
|
|
996
|
+
* re-enable an auto-paused webhook).
|
|
997
|
+
*/
|
|
998
|
+
interface WebhookUpdateRequest {
|
|
999
|
+
name?: string;
|
|
1000
|
+
url?: string;
|
|
1001
|
+
searchCriteria?: SearchRequest;
|
|
1002
|
+
status?: WebhookStatus;
|
|
1003
|
+
}
|
|
1004
|
+
/** Returned by `POST /webhooks`. The `secret` is included here only. */
|
|
1005
|
+
interface WebhookCreateResponse {
|
|
1006
|
+
success: boolean;
|
|
1007
|
+
message?: string;
|
|
1008
|
+
webhook: {
|
|
1009
|
+
id: string;
|
|
1010
|
+
name: string;
|
|
1011
|
+
url: string;
|
|
1012
|
+
/** HMAC-SHA256 signing secret. Store this — it is not returned again. */
|
|
1013
|
+
secret?: string;
|
|
1014
|
+
status: WebhookStatus;
|
|
1015
|
+
searchCriteria?: SearchRequest;
|
|
1016
|
+
createdAt: string;
|
|
1017
|
+
};
|
|
1018
|
+
}
|
|
1019
|
+
/** Returned by `PUT /webhooks/{id}` — summary fields only. */
|
|
1020
|
+
interface WebhookUpdateResponse {
|
|
1021
|
+
success: boolean;
|
|
1022
|
+
message?: string;
|
|
1023
|
+
webhook: {
|
|
1024
|
+
id?: string;
|
|
1025
|
+
name?: string;
|
|
1026
|
+
url?: string;
|
|
1027
|
+
status?: WebhookStatus;
|
|
1028
|
+
searchCriteria?: SearchRequest;
|
|
1029
|
+
updatedAt?: string;
|
|
1030
|
+
};
|
|
1031
|
+
}
|
|
1032
|
+
/** Returned by `GET /webhooks/{id}`. */
|
|
1033
|
+
interface WebhookResponse {
|
|
1034
|
+
success: boolean;
|
|
1035
|
+
webhook: WebhookDetail;
|
|
1036
|
+
}
|
|
1037
|
+
/**
|
|
1038
|
+
* Result of a synchronous test delivery. `success: true` means the
|
|
1039
|
+
* upstream responded 2xx; non-2xx and network errors both yield
|
|
1040
|
+
* `success: false` plus a populated `delivery.errorMessage`.
|
|
1041
|
+
*/
|
|
1042
|
+
interface WebhookTestResponse {
|
|
1043
|
+
success: boolean;
|
|
1044
|
+
message?: string;
|
|
1045
|
+
delivery: {
|
|
1046
|
+
status?: "SUCCESS" | "FAILED";
|
|
1047
|
+
responseStatus?: number | null;
|
|
1048
|
+
/** Truncated upstream response body (max 500 chars). */
|
|
1049
|
+
responseBody?: string | null;
|
|
1050
|
+
errorMessage?: string | null;
|
|
1051
|
+
};
|
|
1052
|
+
}
|
|
1053
|
+
interface WebhookDeliveriesParams {
|
|
1054
|
+
/** Max deliveries to return. Default 50. */
|
|
1055
|
+
limit?: number;
|
|
1056
|
+
/** Pagination offset. Default 0. */
|
|
1057
|
+
offset?: number;
|
|
1058
|
+
}
|
|
1059
|
+
interface WebhookDeliveriesResponse {
|
|
1060
|
+
success: boolean;
|
|
1061
|
+
/** Total deliveries for this webhook (across all pages). */
|
|
1062
|
+
total?: number;
|
|
1063
|
+
limit?: number;
|
|
1064
|
+
offset?: number;
|
|
1065
|
+
deliveries: WebhookDelivery[];
|
|
1066
|
+
}
|
|
1067
|
+
/**
|
|
1068
|
+
* One entry in a document's version history.
|
|
1069
|
+
*
|
|
1070
|
+
* Versions are LexAPI *observation snapshots* (content-hash changes between
|
|
1071
|
+
* fetches), not legal in-force reconstructions. `fetchedAt` is when THIS
|
|
1072
|
+
* version was fetched — version N is "current" from there until version
|
|
1073
|
+
* N+1's `fetchedAt`.
|
|
1074
|
+
*/
|
|
1075
|
+
interface VersionEntry {
|
|
1076
|
+
version: number;
|
|
1077
|
+
isCurrent: boolean;
|
|
1078
|
+
/** Equality across versions means no real content change. */
|
|
1079
|
+
contentHash: string;
|
|
1080
|
+
fetchedAt: string;
|
|
1081
|
+
title?: string | null;
|
|
1082
|
+
documentType?: string | null;
|
|
1083
|
+
documentTypeCode?: string | null;
|
|
1084
|
+
/** Present on single-snapshot responses only (not in history listings). */
|
|
1085
|
+
parsedContent?: Record<string, unknown> | null;
|
|
1086
|
+
}
|
|
1087
|
+
interface DocumentVersionsResponse extends CreditedResponse {
|
|
1088
|
+
success: boolean;
|
|
1089
|
+
celex: string;
|
|
1090
|
+
language: string;
|
|
1091
|
+
currentVersion: number;
|
|
1092
|
+
/** When the document first entered the corpus — history starts here. */
|
|
1093
|
+
trackedSince: string;
|
|
1094
|
+
/** Server restatement of the observation-snapshot semantics. */
|
|
1095
|
+
semantics: string;
|
|
1096
|
+
/** Newest first; the current version is included and flagged. */
|
|
1097
|
+
versions: VersionEntry[];
|
|
1098
|
+
}
|
|
1099
|
+
interface DocumentVersionResponse extends CreditedResponse {
|
|
1100
|
+
success: boolean;
|
|
1101
|
+
celex: string;
|
|
1102
|
+
language: string;
|
|
1103
|
+
/** Present on `/at/{date}` responses only — the requested date. */
|
|
1104
|
+
asOf?: string;
|
|
1105
|
+
semantics: string;
|
|
1106
|
+
document: VersionEntry;
|
|
1107
|
+
/** Mirrors the `X-Corpus-Version` response header. */
|
|
1108
|
+
corpusVersion?: number;
|
|
1109
|
+
}
|
|
1110
|
+
|
|
1111
|
+
interface ExportParams {
|
|
1112
|
+
/** Comma-separated document types, e.g. `"regulation,directive"`. */
|
|
1113
|
+
documentType?: string;
|
|
1114
|
+
/** Comma-separated list of authors. */
|
|
1115
|
+
author?: string;
|
|
1116
|
+
/** Comma-separated subdomains (`legislation`, `case-law`, `treaties`, ...). */
|
|
1117
|
+
subdomain?: string;
|
|
1118
|
+
/** Document language (default `en`). */
|
|
1119
|
+
language?: Language;
|
|
1120
|
+
/** Earliest `dateOfDocument` to include (inclusive, `YYYY-MM-DD`). */
|
|
1121
|
+
dateFrom?: string;
|
|
1122
|
+
/** Latest `dateOfDocument` to include (inclusive, `YYYY-MM-DD`). */
|
|
1123
|
+
dateTo?: string;
|
|
1124
|
+
/** Only stream rows whose `lastSeenAt` is at or after this ISO timestamp. */
|
|
1125
|
+
fetchedSince?: string;
|
|
1126
|
+
/** Include raw `htmlContent` / `htmlMetadata` per row (large). Default false. */
|
|
1127
|
+
includeHtml?: boolean;
|
|
1128
|
+
/** Set `false` to omit `parsedContent` from each row. Default true. */
|
|
1129
|
+
includeContent?: boolean;
|
|
1130
|
+
/** Max rows to stream. Clamped to the server's `EXPORT_MAX_ROWS` ceiling. */
|
|
1131
|
+
limit?: number;
|
|
1132
|
+
}
|
|
1133
|
+
/**
|
|
1134
|
+
* One corpus document line from the export stream. Explicit fields per the
|
|
1135
|
+
* spec's line-shape description; the index signature keeps future server
|
|
1136
|
+
* additions accessible without an SDK update.
|
|
1137
|
+
*/
|
|
1138
|
+
interface ExportRow {
|
|
1139
|
+
celex?: string;
|
|
1140
|
+
language?: string;
|
|
1141
|
+
title?: string | null;
|
|
1142
|
+
documentType?: string | null;
|
|
1143
|
+
/** Stable enum slug alongside the prose `documentType`. */
|
|
1144
|
+
documentTypeCode?: string | null;
|
|
1145
|
+
author?: string | null;
|
|
1146
|
+
dateOfDocument?: string | null;
|
|
1147
|
+
dateOfEffect?: string | null;
|
|
1148
|
+
dateOfPublication?: string | null;
|
|
1149
|
+
dateOfDocumentISO?: string | null;
|
|
1150
|
+
dateOfEffectISO?: string | null;
|
|
1151
|
+
dateOfPublicationISO?: string | null;
|
|
1152
|
+
/** Recovered from `htmlMetadata` for case-law rows where the column is null. */
|
|
1153
|
+
ecli?: string | null;
|
|
1154
|
+
eli?: string | null;
|
|
1155
|
+
caseNumber?: string | null;
|
|
1156
|
+
parties?: string | null;
|
|
1157
|
+
keywords?: string[];
|
|
1158
|
+
subject?: string[];
|
|
1159
|
+
/** Monotonic corpus version for this CELEX. */
|
|
1160
|
+
version?: number;
|
|
1161
|
+
contentHash?: string;
|
|
1162
|
+
firstSeenAt?: string;
|
|
1163
|
+
lastSeenAt?: string;
|
|
1164
|
+
fetchedAt?: string;
|
|
1165
|
+
source?: string;
|
|
1166
|
+
/** Present unless `includeContent: false`. */
|
|
1167
|
+
parsedContent?: Record<string, unknown> | null;
|
|
1168
|
+
/** Present only with `includeHtml: true`. */
|
|
1169
|
+
htmlContent?: string | null;
|
|
1170
|
+
htmlMetadata?: unknown;
|
|
1171
|
+
[key: string]: unknown;
|
|
1172
|
+
}
|
|
1173
|
+
/**
|
|
1174
|
+
* The leading `_meta` envelope line. The spec does not pin its shape, so
|
|
1175
|
+
* beyond the `_meta` marker everything is kept as-is.
|
|
1176
|
+
*/
|
|
1177
|
+
interface ExportMeta {
|
|
1178
|
+
_meta?: unknown;
|
|
1179
|
+
[key: string]: unknown;
|
|
1180
|
+
}
|
|
1181
|
+
/** The trailing `_done` line. Reports `truncated: true` when the row cap was hit. */
|
|
1182
|
+
interface ExportDone {
|
|
1183
|
+
_done?: unknown;
|
|
1184
|
+
truncated?: boolean;
|
|
1185
|
+
[key: string]: unknown;
|
|
1186
|
+
}
|
|
1187
|
+
/** Signals lifted from the `X-Export-*` response headers. */
|
|
1188
|
+
interface ExportHeaderInfo {
|
|
1189
|
+
/** Total rows matching the filters in the database (`X-Export-Total`). */
|
|
1190
|
+
total: number | undefined;
|
|
1191
|
+
/** Rows actually streamed — min of total and limit (`X-Export-Streaming`). */
|
|
1192
|
+
streaming: number | undefined;
|
|
1193
|
+
/** `true` when the row cap was hit (`X-Export-Truncated: 1`). */
|
|
1194
|
+
truncated: boolean | undefined;
|
|
1195
|
+
}
|
|
1196
|
+
/**
|
|
1197
|
+
* Single-pass async iterator over export rows.
|
|
1198
|
+
*
|
|
1199
|
+
* - `meta` is parsed from the leading `_meta` line and available
|
|
1200
|
+
* immediately (before iterating).
|
|
1201
|
+
* - `done` is populated from the trailing `_done` line once iteration
|
|
1202
|
+
* completes; check `done.truncated` (or `headers.truncated`) to detect
|
|
1203
|
+
* the row cap — do not assume the stream was complete.
|
|
1204
|
+
* - `_meta`/`_done` lines are never yielded as rows.
|
|
1205
|
+
*/
|
|
1206
|
+
interface ExportStream extends AsyncIterable<ExportRow> {
|
|
1207
|
+
readonly meta: ExportMeta | undefined;
|
|
1208
|
+
readonly done: ExportDone | undefined;
|
|
1209
|
+
readonly headers: ExportHeaderInfo;
|
|
1210
|
+
}
|
|
1211
|
+
|
|
1212
|
+
/**
|
|
1213
|
+
* Webhook subscriptions — notify a URL when newly-published documents
|
|
1214
|
+
* match saved `/search` criteria. Accessed as `client.webhooks.*`.
|
|
1215
|
+
*/
|
|
1216
|
+
declare class WebhooksAPI {
|
|
1217
|
+
private readonly http;
|
|
1218
|
+
constructor(http: HttpClient);
|
|
1219
|
+
/**
|
|
1220
|
+
* `GET /webhooks` — every webhook owned by the caller, newest first.
|
|
1221
|
+
* The `secret` is never returned here (only once, on creation).
|
|
1222
|
+
*/
|
|
1223
|
+
list(options?: CallOptions): Promise<WebhookListResponse>;
|
|
1224
|
+
/**
|
|
1225
|
+
* `POST /webhooks` — subscribe a URL to documents matching saved search
|
|
1226
|
+
* criteria. If `secret` is omitted the server generates one and returns
|
|
1227
|
+
* it in this response ONLY — store it. Rejected with 400 when the tier
|
|
1228
|
+
* webhook ceiling is reached (FREE=0, STARTER=2, PROFESSIONAL=10,
|
|
1229
|
+
* BUSINESS=50).
|
|
1230
|
+
*/
|
|
1231
|
+
create(request: WebhookCreateRequest, options?: CallOptions): Promise<WebhookCreateResponse>;
|
|
1232
|
+
/** `GET /webhooks/{id}` — full details including the 20 most recent deliveries. */
|
|
1233
|
+
get(id: string, options?: CallOptions): Promise<WebhookResponse>;
|
|
1234
|
+
/**
|
|
1235
|
+
* `PUT /webhooks/{id}` — partial update; only supplied fields change.
|
|
1236
|
+
* Setting `status: "ACTIVE"` also resets `consecutiveFailures` to 0
|
|
1237
|
+
* (re-enables an auto-paused webhook).
|
|
1238
|
+
*/
|
|
1239
|
+
update(id: string, request: WebhookUpdateRequest, options?: CallOptions): Promise<WebhookUpdateResponse>;
|
|
1240
|
+
/**
|
|
1241
|
+
* `DELETE /webhooks/{id}` — permanently deletes the webhook and its
|
|
1242
|
+
* delivery history. Resolves on 204; a repeat delete throws
|
|
1243
|
+
* `NotFoundError`.
|
|
1244
|
+
*/
|
|
1245
|
+
delete(id: string, options?: CallOptions): Promise<void>;
|
|
1246
|
+
/**
|
|
1247
|
+
* `POST /webhooks/{id}/test` — synchronously POSTs a `webhook.test`
|
|
1248
|
+
* payload (HMAC-SHA256 signed via `X-Webhook-Signature`) to the webhook
|
|
1249
|
+
* URL and returns the upstream result. 10 s timeout; redirects are not
|
|
1250
|
+
* followed.
|
|
1251
|
+
*/
|
|
1252
|
+
test(id: string, options?: CallOptions): Promise<WebhookTestResponse>;
|
|
1253
|
+
/** `GET /webhooks/{id}/deliveries` — delivery history, most recent first. */
|
|
1254
|
+
deliveries(id: string, params?: WebhookDeliveriesParams, options?: CallOptions): Promise<WebhookDeliveriesResponse>;
|
|
1255
|
+
}
|
|
1256
|
+
|
|
1257
|
+
interface LexAPIOptions {
|
|
1258
|
+
/**
|
|
1259
|
+
* LexAPI key (`lex_...`). Falls back to the `LEXAPI_API_KEY` environment
|
|
1260
|
+
* variable when `process` exists. Keys are server-side secrets — never
|
|
1261
|
+
* ship them in client-side code.
|
|
1262
|
+
*/
|
|
1263
|
+
apiKey?: string;
|
|
1264
|
+
/** API base URL. Defaults to production (`https://lex-api.com/api/v1`). */
|
|
1265
|
+
baseUrl?: string;
|
|
1266
|
+
/** Per-request timeout in milliseconds (per attempt). Default 60_000. */
|
|
1267
|
+
timeoutMs?: number;
|
|
1268
|
+
/** Injectable fetch (used for testing / polyfills). Defaults to global fetch. */
|
|
1269
|
+
fetch?: typeof fetch;
|
|
1270
|
+
/** Retry policy. Default: 3 retries, 500 ms base, 30 s cap. */
|
|
1271
|
+
retry?: RetryOptions;
|
|
1272
|
+
/** Optional suffix appended to the `User-Agent` header. */
|
|
1273
|
+
userAgentSuffix?: string;
|
|
1274
|
+
}
|
|
1275
|
+
/** Per-call overrides accepted by every SDK method. */
|
|
1276
|
+
interface CallOptions {
|
|
1277
|
+
/** Override the client-level timeout for this call only. */
|
|
1278
|
+
timeoutMs?: number;
|
|
1279
|
+
}
|
|
1280
|
+
/**
|
|
1281
|
+
* LexAPI client — European legal data, made queryable.
|
|
1282
|
+
*
|
|
1283
|
+
* Server-side only: API keys are secrets and browsers additionally forbid
|
|
1284
|
+
* setting the `User-Agent` header this SDK sends.
|
|
1285
|
+
*
|
|
1286
|
+
* ```ts
|
|
1287
|
+
* const client = new LexAPI({ apiKey: "lex_..." }); // or set LEXAPI_API_KEY
|
|
1288
|
+
* const info = await client.getInfo();
|
|
1289
|
+
* ```
|
|
1290
|
+
*/
|
|
1291
|
+
declare class LexAPI {
|
|
1292
|
+
protected readonly http: HttpClient;
|
|
1293
|
+
/** Webhook subscriptions (`client.webhooks.list/create/get/update/delete/test/deliveries`). */
|
|
1294
|
+
readonly webhooks: WebhooksAPI;
|
|
1295
|
+
constructor(options?: LexAPIOptions);
|
|
1296
|
+
/**
|
|
1297
|
+
* `GET /info` — API capabilities, subscription tier, and current usage.
|
|
1298
|
+
* Free operation (0 credits); useful as a connection probe.
|
|
1299
|
+
*/
|
|
1300
|
+
getInfo(options?: CallOptions): Promise<InfoResponse>;
|
|
1301
|
+
/**
|
|
1302
|
+
* `POST /search` — search EUR-Lex with structured filters.
|
|
1303
|
+
*
|
|
1304
|
+
* At least one filter is required. Truncation and partial-result signals
|
|
1305
|
+
* are surfaced on the response rather than hidden: check `truncated` /
|
|
1306
|
+
* `truncatedAt` / `truncatedReason` (tier-capped pagination), `partial` /
|
|
1307
|
+
* `partialReason` (an upstream page timed out), `postFilteredBy`
|
|
1308
|
+
* (controller-side post-filter dropped rows — `"date"` means raising
|
|
1309
|
+
* `maxPages` widens recall), `ignoredDocumentTypes`, and `xWarning`
|
|
1310
|
+
* (the `X-Warning` response header, e.g. `maxPages` tier clamping).
|
|
1311
|
+
*/
|
|
1312
|
+
search(request: SearchRequest, options?: CallOptions): Promise<SearchResponse>;
|
|
1313
|
+
/**
|
|
1314
|
+
* `POST /documentContent` — fetch a single fully-parsed document by CELEX.
|
|
1315
|
+
*
|
|
1316
|
+
* Corpus-first with live-scrape fallback (`bypassCorpus: true` forces a
|
|
1317
|
+
* live read). Use `include`/`fields`/`articleId` to trim the payload.
|
|
1318
|
+
*/
|
|
1319
|
+
getDocument(request: DocumentContentRequest, options?: CallOptions): Promise<DocumentContentResponse>;
|
|
1320
|
+
/**
|
|
1321
|
+
* `POST /documentContent/batch` — fetch multiple documents in one request.
|
|
1322
|
+
*
|
|
1323
|
+
* The batch is clamped to the tier ceiling (FREE=1, STARTER=5,
|
|
1324
|
+
* PROFESSIONAL=20, BUSINESS=50). Clamping is surfaced, not silent: check
|
|
1325
|
+
* `trimmed` / `trimmedTo` / `trimmedReason` on the body and `xWarning`
|
|
1326
|
+
* (the `X-Warning` header). Per-CELEX failures are collected in `errors`
|
|
1327
|
+
* instead of aborting the batch.
|
|
1328
|
+
*/
|
|
1329
|
+
getDocumentsBatch(request: DocumentContentBatchRequest, options?: CallOptions): Promise<DocumentContentBatchResponse>;
|
|
1330
|
+
/**
|
|
1331
|
+
* `GET /documents/recent` — recently-published documents (last `days`
|
|
1332
|
+
* days, default 7). Page fetching is tier-clamped like `/search`;
|
|
1333
|
+
* `xWarning` carries the `X-Warning` header when clamping fired, and
|
|
1334
|
+
* `languageFilter` reports rows dropped by the language post-filter.
|
|
1335
|
+
*/
|
|
1336
|
+
getRecentDocuments(params?: RecentDocumentsParams, options?: CallOptions): Promise<RecentDocumentsResponse>;
|
|
1337
|
+
/**
|
|
1338
|
+
* `POST /documents/url` — fetch a document by any EUR-Lex URL. The
|
|
1339
|
+
* response is shaped like `getDocument` plus `sourceUrl` and
|
|
1340
|
+
* `extractedCelex` echo-backs.
|
|
1341
|
+
*/
|
|
1342
|
+
getDocumentByUrl(request: DocumentByUrlRequest, options?: CallOptions): Promise<DocumentByUrlResponse>;
|
|
1343
|
+
/**
|
|
1344
|
+
* `POST /documents/metadata` — metadata only (title, dates, ECLI/ELI,
|
|
1345
|
+
* keywords, subjects). Skips the body parse: significantly faster and
|
|
1346
|
+
* cheaper than `getDocument`.
|
|
1347
|
+
*/
|
|
1348
|
+
getDocumentMetadata(request: DocumentMetadataRequest, options?: CallOptions): Promise<DocumentMetadataResponse>;
|
|
1349
|
+
/**
|
|
1350
|
+
* `POST /resolve` — resolve any legal identifier (bare CELEX, EUR-Lex
|
|
1351
|
+
* URL, ELI URI, or ECLI) to the canonical CELEX plus access URLs.
|
|
1352
|
+
*/
|
|
1353
|
+
resolve(identifier: string, options?: CallOptions): Promise<ResolveResponse>;
|
|
1354
|
+
/**
|
|
1355
|
+
* `GET /documents/{celex}/versions` — version history, newest first,
|
|
1356
|
+
* current version included and flagged. 1 credit.
|
|
1357
|
+
*/
|
|
1358
|
+
listDocumentVersions(celex: string, params?: {
|
|
1359
|
+
language?: string;
|
|
1360
|
+
}, options?: CallOptions): Promise<DocumentVersionsResponse>;
|
|
1361
|
+
/**
|
|
1362
|
+
* `GET /documents/{celex}/versions/{version}` — one immutable snapshot
|
|
1363
|
+
* including `parsedContent`. `corpusVersion` mirrors the
|
|
1364
|
+
* `X-Corpus-Version` response header. 1 credit.
|
|
1365
|
+
*/
|
|
1366
|
+
getDocumentVersion(celex: string, version: number, params?: {
|
|
1367
|
+
language?: string;
|
|
1368
|
+
}, options?: CallOptions): Promise<DocumentVersionResponse>;
|
|
1369
|
+
/**
|
|
1370
|
+
* `GET /documents/{celex}/at/{date}` — the snapshot LexAPI observed as
|
|
1371
|
+
* current on `date` (`YYYY-MM-DD`, end-of-day UTC inclusive). Dates
|
|
1372
|
+
* before the document entered the corpus reject with `NotFoundError`
|
|
1373
|
+
* carrying the tracking start date. 1 credit.
|
|
1374
|
+
*/
|
|
1375
|
+
getDocumentAtDate(celex: string, date: string, params?: {
|
|
1376
|
+
language?: string;
|
|
1377
|
+
}, options?: CallOptions): Promise<DocumentVersionResponse>;
|
|
1378
|
+
/**
|
|
1379
|
+
* `POST /citations/extract` — crawl a document's EUR-Lex metadata page
|
|
1380
|
+
* for citations and persist them into the graph. Idempotent: an already
|
|
1381
|
+
* processed document returns immediately with `alreadyExtracted: true`.
|
|
1382
|
+
*/
|
|
1383
|
+
extractCitations(celexNumber: string, options?: CallOptions): Promise<CitationExtractResponse>;
|
|
1384
|
+
/**
|
|
1385
|
+
* `GET /citations/cites/{celexNumber}` — documents this one cites
|
|
1386
|
+
* (outbound edges), grouped by target. The document must first have been
|
|
1387
|
+
* crawled via `extractCitations` to appear here.
|
|
1388
|
+
*/
|
|
1389
|
+
getCites(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): Promise<CitesResponse>;
|
|
1390
|
+
/**
|
|
1391
|
+
* `GET /citations/cited-by/{celexNumber}` — documents that cite this one
|
|
1392
|
+
* (inbound edges), grouped by source.
|
|
1393
|
+
*/
|
|
1394
|
+
getCitedBy(celexNumber: string, params?: CitationEdgeParams, options?: CallOptions): Promise<CitedByResponse>;
|
|
1395
|
+
/**
|
|
1396
|
+
* `GET /citations/network/{celexNumber}` — inbound and outbound
|
|
1397
|
+
* neighbourhood in one call, paginated per direction.
|
|
1398
|
+
*
|
|
1399
|
+
* If the server-side wall-clock budget expires the endpoint still
|
|
1400
|
+
* returns 200 with `partial: true`, an EMPTY `network`, and `null`
|
|
1401
|
+
* paging totals — check `partial` before treating the network as empty.
|
|
1402
|
+
*/
|
|
1403
|
+
getCitationNetwork(celexNumber: string, params?: CitationNetworkParams, options?: CallOptions): Promise<CitationNetworkResponse>;
|
|
1404
|
+
/**
|
|
1405
|
+
* `GET /citations/path/{from}/{to}` — shortest citation path (BFS over
|
|
1406
|
+
* outbound edges). `found: false` is a graceful HTTP 200, not an error.
|
|
1407
|
+
* Default `maxDepth` 3 (max 8); the visited set is bounded to 5000 nodes.
|
|
1408
|
+
*/
|
|
1409
|
+
getCitationPath(from: string, to: string, params?: {
|
|
1410
|
+
maxDepth?: number;
|
|
1411
|
+
}, options?: CallOptions): Promise<CitationPathResponse>;
|
|
1412
|
+
/**
|
|
1413
|
+
* `GET /citations/related/{celexNumber}` — bibliographic-coupling
|
|
1414
|
+
* neighbours (documents sharing the most outbound citation targets with
|
|
1415
|
+
* the seed). Returns a graceful empty list with `message` when the seed
|
|
1416
|
+
* has no outbound citations to couple on.
|
|
1417
|
+
*/
|
|
1418
|
+
getRelatedDocuments(celexNumber: string, params?: {
|
|
1419
|
+
limit?: number;
|
|
1420
|
+
}, options?: CallOptions): Promise<RelatedDocumentsResponse>;
|
|
1421
|
+
/** `GET /citations/stats` — global citation graph statistics. */
|
|
1422
|
+
getCitationStats(options?: CallOptions): Promise<CitationStatsResponse>;
|
|
1423
|
+
/**
|
|
1424
|
+
* `POST /search/semantic` — embedding-based semantic search over CJEU
|
|
1425
|
+
* case law. Use this (not `search`) for *concept* queries; EUR-Lex
|
|
1426
|
+
* keyword matching is literal.
|
|
1427
|
+
*
|
|
1428
|
+
* **Billing:** 5 credits per call — **15 credits with `hyde: true`**
|
|
1429
|
+
* (HyDE query rewriting: an LLM drafts the passage a relevant judgment
|
|
1430
|
+
* would contain and retrieval fuses both rankings; ~1–3 s extra
|
|
1431
|
+
* latency). HyDE is best-effort: on LLM failure the search falls back
|
|
1432
|
+
* to plain retrieval, the response reports `hyde: false`, and the
|
|
1433
|
+
* 10-credit premium is **refunded automatically** — verify via
|
|
1434
|
+
* `credits.operation_weight`.
|
|
1435
|
+
*
|
|
1436
|
+
* The response exposes `hint` (present only on low-confidence,
|
|
1437
|
+
* best-effort result sets — its presence is itself the signal), `hyde`
|
|
1438
|
+
* (whether HyDE actually ran), and `hypotheticalDocument` (the drafted
|
|
1439
|
+
* passage, present only when HyDE ran).
|
|
1440
|
+
*
|
|
1441
|
+
* Fewer results than `limit`? The upstream's ~0.7 default relevance
|
|
1442
|
+
* floor cut in — pass `minScore: 0.5` (or `0`) to widen recall.
|
|
1443
|
+
*
|
|
1444
|
+
* Persistent document identity is `(metadata.celex_id,
|
|
1445
|
+
* metadata.document_type)`; `case_id` is snapshot-scoped and does not
|
|
1446
|
+
* survive index rebuilds.
|
|
1447
|
+
*/
|
|
1448
|
+
semanticSearch(request: SemanticCaseLawSearchOptions, options?: CallOptions): Promise<SemanticCaseLawSearchResponse>;
|
|
1449
|
+
/**
|
|
1450
|
+
* `POST /legislation/semantic` — embedding-based semantic search over EU
|
|
1451
|
+
* legislation; results are article-level matches (`article_ref`,
|
|
1452
|
+
* `law_id`, `law_title`, `score`).
|
|
1453
|
+
*
|
|
1454
|
+
* Costs 5 credits. The `hyde` option is case-law only and is therefore
|
|
1455
|
+
* not accepted here (the server ignores it on this endpoint). The same
|
|
1456
|
+
* ~0.7 default relevance floor applies — lower `minScore` to widen
|
|
1457
|
+
* recall; `hint` is present only on low-confidence result sets.
|
|
1458
|
+
*/
|
|
1459
|
+
semanticLegislationSearch(request: SemanticSearchOptions, options?: CallOptions): Promise<SemanticLegislationSearchResponse>;
|
|
1460
|
+
/**
|
|
1461
|
+
* `GET /export` — stream matching corpus rows as NDJSON (BUSINESS tier;
|
|
1462
|
+
* 402 `TierForbidden`/`CreditsExhausted`-style envelope otherwise).
|
|
1463
|
+
*
|
|
1464
|
+
* Returns a single-pass async iterator over document rows. The leading
|
|
1465
|
+
* `_meta` envelope is parsed before this resolves (`stream.meta`); the
|
|
1466
|
+
* trailing `_done` line is exposed as `stream.done` after iteration
|
|
1467
|
+
* finishes — check `done.truncated` / `headers.truncated` to detect the
|
|
1468
|
+
* server row cap (`X-Export-Truncated: 1`) instead of assuming the
|
|
1469
|
+
* export was complete.
|
|
1470
|
+
*
|
|
1471
|
+
* ```ts
|
|
1472
|
+
* const stream = await client.export({ documentType: "regulation", limit: 1000 });
|
|
1473
|
+
* console.log(stream.meta, stream.headers.total);
|
|
1474
|
+
* for await (const row of stream) process(row.celex, row.parsedContent);
|
|
1475
|
+
* if (stream.done?.truncated) console.warn("row cap hit — paginate with fetchedSince");
|
|
1476
|
+
* ```
|
|
1477
|
+
*/
|
|
1478
|
+
export(params?: ExportParams, options?: CallOptions): Promise<ExportStream>;
|
|
1479
|
+
}
|
|
1480
|
+
|
|
1481
|
+
/**
|
|
1482
|
+
* Normalized credit visibility for one response (SDK contract §1.5).
|
|
1483
|
+
* All fields tolerate the `usage`/`credits` blocks being absent
|
|
1484
|
+
* (legacy daily-call accounts omit `credits`).
|
|
1485
|
+
*/
|
|
1486
|
+
interface CreditUsage {
|
|
1487
|
+
/**
|
|
1488
|
+
* Credits this specific request cost, mapped from
|
|
1489
|
+
* `credits.operation_weight`. `0` for free operations such as `/info`;
|
|
1490
|
+
* `undefined` when the account has no credit pool (legacy accounts).
|
|
1491
|
+
*/
|
|
1492
|
+
unitsCharged: number | undefined;
|
|
1493
|
+
/** `credits.remaining`, falling back to `usage.remaining`. */
|
|
1494
|
+
creditsRemaining: number | undefined;
|
|
1495
|
+
/** When the quota window resets — `credits.resetsAt` falling back to `usage.resetsAt`. */
|
|
1496
|
+
resetsAt: string | null | undefined;
|
|
1497
|
+
}
|
|
1498
|
+
/**
|
|
1499
|
+
* Read the credit state off any LexAPI response. The raw `usage`/`credits`
|
|
1500
|
+
* blocks stay accessible on the response itself, loss-free.
|
|
1501
|
+
*
|
|
1502
|
+
* ```ts
|
|
1503
|
+
* const info = await client.getInfo();
|
|
1504
|
+
* const { unitsCharged, creditsRemaining, resetsAt } = getCreditUsage(info);
|
|
1505
|
+
* ```
|
|
1506
|
+
*/
|
|
1507
|
+
declare function getCreditUsage(response: CreditedResponse): CreditUsage;
|
|
1508
|
+
|
|
1509
|
+
declare const VERSION = "0.1.0";
|
|
1510
|
+
|
|
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 };
|