@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.
@@ -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 };