@lexapi/client 0.1.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +394 -0
- package/LICENSE +21 -0
- package/README.md +407 -95
- package/dist/index.cjs +1723 -323
- package/dist/index.d.cts +2773 -343
- package/dist/index.d.ts +2773 -343
- package/dist/index.js +1698 -322
- package/package.json +32 -13
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,394 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@lexapi/client`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
|
|
4
|
+
versioning: [SemVer](https://semver.org/) — while the package is `0.x`, a **minor** bump may contain
|
|
5
|
+
breaking changes (documented below with a migration note); `npm install @lexapi/client@^0.1.0` never
|
|
6
|
+
picks up `0.2.0` on its own.
|
|
7
|
+
|
|
8
|
+
## [0.4.0] — 2026-11-11
|
|
9
|
+
|
|
10
|
+
Cross-border citation graph. **Requires LexAPI API 2.13.0.** Additive at runtime: no existing
|
|
11
|
+
signature or field changes meaning. Type-level changes to check when upgrading:
|
|
12
|
+
|
|
13
|
+
- `CitationType` gains `"transposition"` — an exhaustive `switch` over it needs a new case.
|
|
14
|
+
- `citationType` params are now `OneOrMany<CitationType>`: code that reads the param back as a
|
|
15
|
+
single value must handle a list.
|
|
16
|
+
- `NationalDocumentContent` gains the required `textSource` and `ocr` fields — objects you build
|
|
17
|
+
yourself (test fixtures, mocks) need them (`null` is valid for both).
|
|
18
|
+
|
|
19
|
+
### Added
|
|
20
|
+
|
|
21
|
+
- **`getTransposition(celexNumber, params?, options?)`** (`GET /citations/transposition/{celexNumber}`,
|
|
22
|
+
5 credits, every plan): the measures the member states notified to the Commission for an EU act
|
|
23
|
+
(CELEX sector 3), grouped by country, from the Publications Office's Cellar records. Every answer
|
|
24
|
+
carries `note` — a notification is not a finding that the measure transposes the act, or
|
|
25
|
+
transposes it completely. On BUSINESS, SCALE and ENTERPRISE, for live jurisdictions, the measures
|
|
26
|
+
LexAPI holds are filled in (`id`, `resolved`, `resolution`, `resolutionBasis`, `counts.resolved`,
|
|
27
|
+
`source.lanes`) and documents whose national source records the relation are added
|
|
28
|
+
(`provenance: "source"`); otherwise those fields are `null` (`termsRequired: true` while the
|
|
29
|
+
national-source terms are not accepted). Params: `jurisdictions`, `resolvedOnly`, `language`.
|
|
30
|
+
Types: `TranspositionParams`, `TranspositionResponse`, `TranspositionCountry`,
|
|
31
|
+
`TranspositionMeasure`.
|
|
32
|
+
- **`getCounterparts(id, params?, options?)`** (`GET /citations/counterparts/{id}`, 20 credits,
|
|
33
|
+
BUSINESS and above): a national document's counterparts in the other live jurisdictions, through
|
|
34
|
+
the EU acts it transposes or implements, ranked 1–3. A lookup past the server's budget throws
|
|
35
|
+
`TimeoutError` (503, `partial`), refunded; the SDK does not retry it — retry yourself, or narrow
|
|
36
|
+
with `jurisdictions`. Other 503s keep the existing retry policy. Types: `CounterpartsParams`, `CounterpartsResponse`,
|
|
37
|
+
`CounterpartVia`, `Counterpart`.
|
|
38
|
+
- **Edge filters** on `getCites`, `getCitedBy`, `getCitationNetwork`, `getCitationPath` and
|
|
39
|
+
`getRelatedDocuments` (and the `paginate*` helpers): `citationType` now takes one value or a
|
|
40
|
+
list, plus `provenance`, `jurisdictions` and `resolution` (each one value or a list, sent
|
|
41
|
+
comma-separated). `CitationFilterParams`; `CitationPathParams` and `RelatedDocumentsParams` gain
|
|
42
|
+
`citationType` too.
|
|
43
|
+
- **`unresolved: true`** on `getCites` (new `CitesParams`) and `getCitationNetwork` for a national
|
|
44
|
+
document id: `unresolved` (`UnresolvedReference[]`) and `unresolvedTruncated` on the response.
|
|
45
|
+
- **Provenance and resolution on every edge**: `CitationEdgeDetail.provenance` /
|
|
46
|
+
`.resolution`, and `CitationNeighbour.edgeDetails` (`CitationEdgeKind[]`). Types
|
|
47
|
+
`CitationProvenance`, `CitationResolution`; runtime lists `CITATION_TYPES`,
|
|
48
|
+
`CITATION_PROVENANCES`, `CITATION_RESOLUTIONS`.
|
|
49
|
+
- **Node identity** (`CitationNode`: `id`, `jurisdiction`, `documentKind`) on cites / cited-by
|
|
50
|
+
groups, network neighbours, path nodes and related documents. `celexNumber` is unchanged.
|
|
51
|
+
- **`CitationType`** gains `"transposition"`.
|
|
52
|
+
- **Totals**: `totalEdges` and `countsSource` (`"stats"` | `"counted"`, API 2.10.0) on
|
|
53
|
+
`getCites` / `getCitedBy`; `paging.citesEdgeTotal`, `paging.citedByEdgeTotal` and
|
|
54
|
+
`paging.countsSource` (`null` when partial) on `getCitationNetwork`.
|
|
55
|
+
- **`getCitationStats({ includeNational: true })`**: `stats.byJurisdiction`, `stats.byProvenance`,
|
|
56
|
+
`stats.transposition`.
|
|
57
|
+
- **Coverage**: `NationalJurisdictionCoverage.citationGraph` (`NationalCitationGraph`) — extraction
|
|
58
|
+
`methods` (incl. `unmeasured` rate → `not-collected` | `source-empty`), `edges`,
|
|
59
|
+
`decisionResolutionRate`, `actEuRate`, `textPatternRate`, `transposition`, `precision`,
|
|
60
|
+
`measuredAt`, `nimResolvedRate`, `nimMeasuredAt`, `floors`.
|
|
61
|
+
- **National content**: `content.textSource` (`html` | `pdf-text` | `ocr` | `null`) and
|
|
62
|
+
`content.ocr` (`NationalOcrInfo` | `null`) — API 2.9.0.
|
|
63
|
+
- **`InvalidParamsError.param` / `.value` / `.allowed`**: the refused parameter, the value sent
|
|
64
|
+
(when the server echoes it) and its allowed values, read
|
|
65
|
+
from either error shape. **`TimeoutError.partial` / `.serverTimeoutMs`** for a budget timeout.
|
|
66
|
+
- **Incomplete national semantic searches**: `partial` (`true`) and `partialReason`
|
|
67
|
+
(`NationalSearchPartialReason`, `"SEARCH_INCOMPLETE"`) on `NationalSemanticCaseLawResponse` and
|
|
68
|
+
`NationalSemanticLegislationResponse` — the national index could not complete the search and the
|
|
69
|
+
results may be missing better matches; `hint` says whether a retry or a rephrased query / changed
|
|
70
|
+
filters may complete it. With nothing left to return the call fails instead:
|
|
71
|
+
`NationalSemanticUnavailableError` (503) now exposes `.partialReason` (`"SEARCH_INCOMPLETE"`), and
|
|
72
|
+
its `retryAfter` falls back to the body's `retryAfter` when the header is missing.
|
|
73
|
+
- **`NationalSemanticFilterUnreachableError`** (extends `InvalidParamsError`, code
|
|
74
|
+
`NATIONAL_SEMANTIC_FILTER_UNREACHABLE`, 422, `.jurisdiction`, `.partialReason`): the national index
|
|
75
|
+
cannot search this slice (jurisdiction, document kind, filters) completely and there is nothing
|
|
76
|
+
left to return. Not retryable as is — rephrase the query or change the filters. Refunded.
|
|
77
|
+
- **`/resolve`**: optional `ResolveResponse.verified` and the `ResolvedVia` value `"eli-cellar"`
|
|
78
|
+
(servers that send them; `verified: false` means the CELEX was not confirmed by a lookup).
|
|
79
|
+
|
|
80
|
+
### Changed
|
|
81
|
+
|
|
82
|
+
- A `422 NATIONAL_SEMANTIC_FILTER_UNREACHABLE` is now a `NationalSemanticFilterUnreachableError`,
|
|
83
|
+
a subclass of `InvalidParamsError` (previously the base `LexAPIError`): `catch` blocks for
|
|
84
|
+
`InvalidParamsError` now also see it. The request may be valid — it is a coverage limit of the
|
|
85
|
+
national index, not a malformed request, and `.param` is absent.
|
|
86
|
+
- An incomplete national semantic search `503` without a retry wait (the same search has
|
|
87
|
+
repeatedly come back incomplete) is not retried automatically, even with `retryReadOnlyPosts`.
|
|
88
|
+
With a wait it keeps the existing 503 policy, but is retried at most once per call. A
|
|
89
|
+
`retry.maxDelayMs` below the server's wait shortens that wait. A `503` is never a `RateLimitedError`, whatever
|
|
90
|
+
`Retry-After` / `retryAfter` it carries — only a `429` is.
|
|
91
|
+
|
|
92
|
+
## [0.3.0] — 2026-10-28
|
|
93
|
+
|
|
94
|
+
Adds national (member-state, and non-EU) law support. **Requires LexAPI API 2.8.0.**
|
|
95
|
+
|
|
96
|
+
### National document shape (API 2.8.0)
|
|
97
|
+
|
|
98
|
+
The national types follow the normalized cross-jurisdiction contract — a client written for one
|
|
99
|
+
country now works for every other:
|
|
100
|
+
|
|
101
|
+
- `NationalDocumentSummary` (listing rows, documents, and every semantic hit's `document`): every
|
|
102
|
+
field is required and `null` when the source has nothing — `title`, `documentType`, `ecli`,
|
|
103
|
+
`eli`, `dateOfDocument` (`YYYY-MM-DD`), `validTo`, `inForce` — plus the new **`documentKind`**
|
|
104
|
+
(`"act"` | `"decision"`, type `NationalDocumentKind`).
|
|
105
|
+
- `NationalDocument` gains **`decision: NationalDecision | null`** (`court`, `chamber`,
|
|
106
|
+
`caseNumbers[]`, `citedNorms[]` of `NationalCitedNorm { text, documentId }`) and `content` is the
|
|
107
|
+
closed `NationalDocumentContent` (`fullText`, `articles: NationalArticle[]`, `textLanguages`,
|
|
108
|
+
`textLanguage`, `embeddedForeignText`, `repeal: NationalRepeal | null`, `source`, `details`) instead
|
|
109
|
+
of the EU `DocumentContent`. Articles are `{ number, title, section, text, inForceFrom, inForceTo,
|
|
110
|
+
details }`. `textAvailability` is required; `textBasis` is `NationalTextBasis | null`. Source-
|
|
111
|
+
specific keys (Austria's `gericht`, Germany's `aktenzeichen`, unit ids, …) live only under
|
|
112
|
+
`content.details` / `articles[].details` — read `decision` instead.
|
|
113
|
+
- New helper **`isNationalDecision(document)`** — a type guard narrowing to
|
|
114
|
+
`NationalDecisionDocument` (non-null `decision`).
|
|
115
|
+
- `NationalSemanticCaseLawResult` / `NationalSemanticLegislationResult`: required `document`
|
|
116
|
+
(`NationalDocumentSummary`), `documentId`, `jurisdiction`, `attribution`; legislation hits always
|
|
117
|
+
carry `law_title`, `article_ref`, `section`, `language`, `in_force`, `valid_from`, `valid_to`,
|
|
118
|
+
`law_type` (each nullable).
|
|
119
|
+
|
|
120
|
+
### Added
|
|
121
|
+
|
|
122
|
+
- **National law**: `getNationalCoverage()` (`GET /national/coverage`, public, free — which
|
|
123
|
+
jurisdictions are live, what each covers, sources and their attribution), `getNationalDocument()`
|
|
124
|
+
(`GET /{jurisdiction}/documents/{id}`, 1 credit), `listNationalDocuments()` /
|
|
125
|
+
`paginateNationalDocuments()` (`GET /{jurisdiction}/documents`, 3 credits flat per call — pagination
|
|
126
|
+
does not multiply the price; cursor paging past the first 1,000 rows, newest-first
|
|
127
|
+
by document date), `nationalSemanticSearch()`
|
|
128
|
+
(`POST /{jurisdiction}/search/semantic`, 5 credits — `hyde` accepted but never rewrites or
|
|
129
|
+
changes price here) and `nationalLegislationSemanticSearch()`
|
|
130
|
+
(`POST /{jurisdiction}/legislation/semantic`, 5 credits; no `hyde`/`asOf` — and never forwards a
|
|
131
|
+
bypassed `hyde` either, now that the server validates it strictly as a boolean on this route
|
|
132
|
+
too). New types:
|
|
133
|
+
`NationalCoverageResponse`, `NationalDocument`, `NationalDocumentSummary`,
|
|
134
|
+
`NationalDocumentResponse`, `NationalDocumentListParams`, `NationalDocumentListResponse`,
|
|
135
|
+
`NationalSemanticCaseLawOptions`/`Result`/`Response`, `NationalSemanticLegislationOptions`/
|
|
136
|
+
`Result`/`Response`, `NationalSource`, `NationalJurisdictionCoverage` and friends. Every
|
|
137
|
+
document/result carries `attribution` — always show it alongside the text.
|
|
138
|
+
- **`NationalAllowanceExhaustedError`** (`NATIONAL_ALLOWANCE_EXHAUSTED`, 402): FREE/STARTER/
|
|
139
|
+
PROFESSIONAL get national law within a monthly allowance of calls; BUSINESS and above have no
|
|
140
|
+
separate limit. Typed `jurisdiction`/`limit`/`remaining`/`resetsAt`/`upgradeUrl` getters.
|
|
141
|
+
- **`NationalSemanticNotEnabledError`** (409 `NATIONAL_SEMANTIC_NOT_ENABLED` — a jurisdiction has
|
|
142
|
+
no semantic index at all) and **`NationalSemanticUnavailableError`** (503
|
|
143
|
+
`NATIONAL_SEMANTIC_UNAVAILABLE` — temporarily unreachable; extends `ServiceUnavailableError`, so
|
|
144
|
+
`instanceof ServiceUnavailableError` still holds). Both legacy-shape bodies; `.jurisdiction` is
|
|
145
|
+
read off the raw `body`, not `details`.
|
|
146
|
+
- **`DocumentWithdrawnError`** (`DOCUMENT_WITHDRAWN`, 410): a national document
|
|
147
|
+
its source withdrew (a takedown, a pseudonymisation fix) is served nowhere — no title, no
|
|
148
|
+
metadata, no text. Thrown by `getNationalDocument` (typed envelope, `details: {id, jurisdiction,
|
|
149
|
+
withdrawnAt}`) and by the citation methods for a withdrawn national id (legacy shape, the same
|
|
150
|
+
three fields as top-level siblings instead). `.id`/`.jurisdiction`/`.withdrawnAt` read whichever
|
|
151
|
+
shape answered. Not retryable; nothing is ever charged for it.
|
|
152
|
+
- **`result.headers.nationalAllowance`** (`{ limit, remaining, resetsAt }`), parsed from
|
|
153
|
+
`X-National-Limit`/`X-National-Remaining`/`X-National-Reset` — present only for
|
|
154
|
+
FREE/STARTER/PROFESSIONAL callers on the four national document/semantic endpoints (also on the
|
|
155
|
+
402 error itself, via `err.headers`).
|
|
156
|
+
- **`includeNational`** on all six citation-graph methods (`getCites`, `getCitedBy`,
|
|
157
|
+
`getCitationNetwork`, `getCitationPath`, `getRelatedDocuments`, `getCitationStats`): also
|
|
158
|
+
returns/follows national documents of live jurisdictions as neighbours — BUSINESS, SCALE and
|
|
159
|
+
ENTERPRISE only (`403 TierForbiddenError` below that). `celexNumber` and `getCitationPath`'s
|
|
160
|
+
`from`/`to` accept a national document id directly (e.g. `"AT-NOR-10001597"`); an id whose
|
|
161
|
+
jurisdiction is not live is a plain `404 NotFoundError`. `getCitationStats` gained an optional
|
|
162
|
+
`params` argument before `options`.
|
|
163
|
+
Back-compatible with 0.2.0's `getCitationStats(options?)`: a first argument shaped like
|
|
164
|
+
`CallOptions` (`timeoutMs`/`signal`, not `includeNational`) is still honoured as the per-call
|
|
165
|
+
options rather than silently read as `params` — this can't be caught at the type level for a
|
|
166
|
+
non-literal variable or a JS caller, so it's detected at runtime too. Every response type
|
|
167
|
+
carries an optional `includeNational` boolean, present once the flag was honoured.
|
|
168
|
+
- The national methods URL-encode the `jurisdiction` path segment (lower-cased, as before), like every other caller-supplied segment — a stray `/` or `?` in that argument can no longer reach a different route.
|
|
169
|
+
- `paginateNationalDocuments` strips `page` from its params at runtime (not just via the
|
|
170
|
+
`Omit<…, "page">` type, which only guards TypeScript callers) — passing both `page` and
|
|
171
|
+
`cursor` to the underlying `GET` is a 400 ("Use either cursor or page, not both").
|
|
172
|
+
|
|
173
|
+
National semantic responses (`nationalSemanticSearch`/`nationalLegislationSemanticSearch`) carry
|
|
174
|
+
the `credits` block, like every other credit-metered route.
|
|
175
|
+
|
|
176
|
+
## [0.2.0] — 2026-10-26
|
|
177
|
+
|
|
178
|
+
Full re-sync with the LexAPI API (validated against lex-api `main` @ `633eb67`, PR #298, and
|
|
179
|
+
`openapi.yaml` / `docs.md` at that commit). Every endpoint, parameter, response field and error shape
|
|
180
|
+
was audited against the spec **and** the server controllers.
|
|
181
|
+
|
|
182
|
+
### Added
|
|
183
|
+
|
|
184
|
+
- **Point-in-time legislation search** — `semanticLegislationSearch({ query, asOf: "2019-06-01" })`
|
|
185
|
+
returns, per hit, the text in force on that date. New result fields: `asOf`, `asOfResolved`,
|
|
186
|
+
`asOfReason` (typed `AsOfReason`, runtime list `AS_OF_REASONS`), `asOfVersion`
|
|
187
|
+
(`{ celex, date, kind }`), `matchedVersion`; new response fields `asOf` and `asOfSummary`
|
|
188
|
+
(`liveFetches`, `unresolved`). New options type `SemanticLegislationSearchOptions`.
|
|
189
|
+
- **Consolidated-text labels** on legislation hits: `consolidated`, `consolidatedAsOf`, `baseCelex`,
|
|
190
|
+
`consolidatedNote`, `baseAct`; plus `id`, `snippet`, `language`, `section`, `chapter`,
|
|
191
|
+
`exact_match_law_id`.
|
|
192
|
+
- **Case-law hit fields**: `snippet` (the default payload), `parties`, `summary`, `decision_date`,
|
|
193
|
+
`jurisdiction`, `language`, the structured analytics block (`outcome`, `claimed_amount`, …) and
|
|
194
|
+
`metadata.paragraph_number`; `semanticUsage.unitsCharged`.
|
|
195
|
+
- **Text availability**: `document.textAvailability` (`available`, `reason`, `retryable`,
|
|
196
|
+
`availableLanguages`, `externalSource`, `source`, `checkedAt`, `latestConsolidated`,
|
|
197
|
+
`upcomingConsolidated`, `newestConsolidated`); `textUnavailable` on batch responses;
|
|
198
|
+
consolidated-version hints on `/documents/metadata`.
|
|
199
|
+
- **Language**: `acceptLanguages` (`["fr", "de"]` or `"any"`) on `getDocument` /
|
|
200
|
+
`getDocumentsBatch`; `titleLanguage` on documents, batch items and metadata.
|
|
201
|
+
- **Search**: `fresh` (bypass the 60-minute result cache), response `hint` and `source: "corpus"`.
|
|
202
|
+
- **Response headers on every result** — `result.headers` (`ResponseHeaders`): `source`
|
|
203
|
+
(`corpus`/`cellar`/`cellar-oj`/`live` — what a document read settled at), `searchSource`,
|
|
204
|
+
`searchCache`, `language`, `languageFallback`, `textAvailable`, `corpusVersion`, `corpusFetchedAt`,
|
|
205
|
+
`warning`, `ignoredDocumentTypes`, `postFilteredBy`, `documentTypeFanOut`, the batch source split
|
|
206
|
+
(`batch.corpusHits/cellarServed/ojRecovered/liveFetches/textUnavailable`) and `rateLimit`
|
|
207
|
+
(`RateLimit-Limit/Remaining/Reset/Policy`). `parseResponseHeaders()` is exported.
|
|
208
|
+
- **Webhooks**: `watchCelex` watch lists (create/update/read), `searchCriteria` now optional and
|
|
209
|
+
nullable on update (`null` removes it), `WebhookCriteria` (the webhook filter vocabulary),
|
|
210
|
+
`criteriaErrors`, `retryPolicy`, `requeuedDeliveries`; `webhooks.paginateDeliveries()`.
|
|
211
|
+
- **Webhook receivers** (§1.9): `verifyWebhook()` (signature + 300 s replay window + typed parse into the
|
|
212
|
+
`WebhookPayload` union: `documents.new` / `watchlist.changes` / `webhook.test`), `verifySignature()` (a
|
|
213
|
+
missing, empty, non-ASCII or non-hex header is a plain `false`), `computeSignature()`,
|
|
214
|
+
`WebhookSignatureError`; Web Crypto — still zero dependencies.
|
|
215
|
+
- **Citations**: `citationType: "corrigendum"`, `relationSync` on cited-by and network,
|
|
216
|
+
`titleSource` on every neighbour/path node, `language` (title language) on cites / cited-by /
|
|
217
|
+
network / path / related; `paginateCites()` / `paginateCitedBy()` page iterators.
|
|
218
|
+
- **Export**: `includeStubs`; array values for `documentType` / `author` / `subdomain`;
|
|
219
|
+
`stream.cancel()`; typed `_meta` / `_done` contents (`totalMatching`, `written`, `skippedStubs`, …).
|
|
220
|
+
- **Errors**: `ServiceUnavailableError` (503); every `LexAPIError` now carries `body` (the raw JSON
|
|
221
|
+
error body — e.g. `upgradeUrl`, `current`/`limit`) and `headers`; legacy-shape `details` lists
|
|
222
|
+
(search / webhook validation) are kept; `CreditsExhaustedError` exposes `operation`, `weight`,
|
|
223
|
+
`available` and typed `details`; `RateLimitedError.rateLimit`.
|
|
224
|
+
- `SubscriptionTier` includes `SCALE`; `SubscriptionInfo.maxResults`; `ResolvedVia` includes
|
|
225
|
+
`ecli-corpus` / `eli-corpus`; `DocumentUrls.pdf/xml`; `Document.fetchedAt`.
|
|
226
|
+
- `ResponseHeaders.retryAfter`; `RateLimitedError.quotaExhausted` / `resetsAt`.
|
|
227
|
+
- **Cancellation:** `{ signal }` on every method (`CallOptions.signal`) — aborts the request, any retry
|
|
228
|
+
wait and an export stream; rejects with `RequestAbortedError` (`ABORTED`), never retried.
|
|
229
|
+
- **Cross-build `instanceof`:** error classes carry a shared `Symbol.for` brand, so errors from the CommonJS
|
|
230
|
+
build (or a second installed copy) satisfy the ESM build's `instanceof`; `isLexAPIError(err, Class?)`.
|
|
231
|
+
- New errors: `RequestAbortedError`, `InvalidResponseError` (a 2xx with a non-JSON body),
|
|
232
|
+
`IncompleteExportError` (export ended without `_done`, `rowsRead`).
|
|
233
|
+
- `ResponseHeaders.apiVersion` / `release` (`X-LexAPI-Version` / `X-LexAPI-Release`), `languagePartialKept`,
|
|
234
|
+
`cacheAge`. Types: `Document.version`, `SearchResult.dateType/ecli/internalNumber`,
|
|
235
|
+
`CitationEdgeSummary.sourceCelex/direction`, `CitingDocumentGroup.hasResume/hasSummary`,
|
|
236
|
+
`CitationStatsResponse.cachedAt/cacheTtlSeconds`, `UsageInfo.unitsCharged`.
|
|
237
|
+
- `LICENSE` file, `CHANGELOG.md`, `prepublishOnly` guard, and a framework-free dist smoke test
|
|
238
|
+
(`npm run smoke:dist`, incl. a CJS↔ESM `instanceof` check) that CI runs on Node 18–24, Bun and Deno.
|
|
239
|
+
|
|
240
|
+
### Fixed
|
|
241
|
+
|
|
242
|
+
- **Export trailer/meta were never readable**: the server nests them (`{"_done": {written, truncated,
|
|
243
|
+
skippedStubs}}`), so `stream.done?.truncated` was always `undefined`. The fields are now lifted to
|
|
244
|
+
the top level (`stream.done.truncated`, `stream.meta.totalMatching`); the raw `_done` / `_meta`
|
|
245
|
+
stay available.
|
|
246
|
+
- Breaking out of `for await` over an export now cancels the response body instead of leaving the
|
|
247
|
+
connection streaming; `stream.cancel()` takes effect immediately, even during a pending read.
|
|
248
|
+
- **An export that ended without its `_done` trailer looked complete** (iteration finished, `done` was
|
|
249
|
+
`undefined`, so `done?.truncated` was falsy). It now throws `IncompleteExportError` after yielding the rows
|
|
250
|
+
that arrived; `stream.complete`, `stream.rowsRead`, `stream.invalidLines` (lines that are not JSON objects
|
|
251
|
+
are counted, not yielded) and `stream.truncated` (header → `_meta` → `_done` discounted by `skippedStubs`)
|
|
252
|
+
follow §1.8. A stream is read once: re-iterating one read to its `_done` yields nothing; iterating one that
|
|
253
|
+
was ended early (`cancel()`, `break`, an error) raises `IncompleteExportError`.
|
|
254
|
+
- **A dropped export connection threw a raw `TypeError: terminated`**; it is now a `NetworkError`
|
|
255
|
+
("Export stream interrupted after N rows").
|
|
256
|
+
- **`timeoutMs` stopped at the response headers** — a server that sent headers then stalled hung the call
|
|
257
|
+
(and an export) forever. It is now an inactivity limit that restarts on every body chunk (§1.6).
|
|
258
|
+
- **The API key was visible** in `console.log(client)`, `util.inspect` and `JSON.stringify(client)`. It now
|
|
259
|
+
lives in a private field; the client redacts itself in all three.
|
|
260
|
+
- `paginateCites` / `paginateCitedBy` could stop early: they compared the edge offset with
|
|
261
|
+
`totalCitations`, which counts distinct pairs (raw rows can outnumber it). They now stop on a short page.
|
|
262
|
+
- `BatchDocumentError` used field names the server never sends: it is `{ celex, error }` (the README example
|
|
263
|
+
printed `undefined`).
|
|
264
|
+
- `getRecentDocuments({ documentType: [...] })` / `({ subdomain: [...] })` silently used only the first value
|
|
265
|
+
(the endpoint has no fan-out and EUR-Lex reads the first `DTS_SUBDOM` only); both now take one value.
|
|
266
|
+
`search()` keeps multi-value `subdomain` (the web service ORs them) with a documented caveat for the
|
|
267
|
+
result-page fallback. `author` arrays work on both (every `AU_CODED` is sent and ORed).
|
|
268
|
+
- Aborting an export now releases the connection immediately, even while nobody is iterating.
|
|
269
|
+
- A 200 with a non-JSON body threw a raw `SyntaxError` (now `InvalidResponseError`); an empty `Retry-After`
|
|
270
|
+
meant a 0 ms retry (now ignored); unmapped 4xx were `InternalServerError` (now a base `LexAPIError`, code
|
|
271
|
+
`INTERNAL` per §1.3); an empty webhook secret threw a raw Web Crypto `DataError` (now
|
|
272
|
+
`WebhookSignatureError("missing_secret")`); NDJSON lines were rescanned per chunk (quadratic on
|
|
273
|
+
multi-MB `includeHtml` rows; now linear).
|
|
274
|
+
- Copy: export pricing is no longer stated as "1 credit per row" (see the pricing page); `extractCitations`
|
|
275
|
+
never settles at 4; batch source headers overlap rather than partition; the 95 s timeout covers a single
|
|
276
|
+
live fetch, not every request; the "edge runtimes" claim was removed (Bun and Deno are now tested).
|
|
277
|
+
- `resolvedVia` was typed as `IdentifierType`; the server returns `ecli-corpus` / `eli-corpus`.
|
|
278
|
+
- CommonJS consumers got ESM type declarations ("masquerading as ESM", per arethetypeswrong):
|
|
279
|
+
the `exports` map now points `require` at `index.d.cts`.
|
|
280
|
+
- Legacy error bodies dropped their `details` (e.g. which `/search` parameter failed validation).
|
|
281
|
+
- Docs/README: the export tier gate is a `403` (not `402`) and covers BUSINESS, SCALE and
|
|
282
|
+
ENTERPRISE; tier limits include SCALE; "not yet published" and "requires lex-api PR #72" notes
|
|
283
|
+
removed; webhook ceilings updated.
|
|
284
|
+
- Export streams never report a failed export as complete. A `_done` trailer with
|
|
285
|
+
`complete: false`, or any line whose only key is `_error`, now throws `IncompleteExportError`
|
|
286
|
+
(after the rows that did arrive) and leaves `stream.complete` false; before, any `_done` line
|
|
287
|
+
counted as complete and an `_error` line was yielded as an `ExportRow`. The error line's body is
|
|
288
|
+
on the exception's `details` and on the new `stream.error`. Unknown `_done` fields
|
|
289
|
+
(`truncatedBy`, `credits`) are kept on `stream.done`. (PLAN.md §1.8; lex-api #303.)
|
|
290
|
+
- A top-level string `code` on a legacy-shape error body (lex-api #304 adds it next to the text
|
|
291
|
+
`error`) is now the error's `code`, ahead of the status-derived one. A 429 with
|
|
292
|
+
`code: "QUOTA_EXHAUSTED"` (a legacy plan's used-up daily or monthly-semantic quota) is a
|
|
293
|
+
`RateLimitedError` with `code === "QUOTA_EXHAUSTED"`, `quotaExhausted` true, `retryAfter`
|
|
294
|
+
`undefined` and `resetsAt` from the body's `resetsAt`; it is never retried. `QUOTA_EXHAUSTED`
|
|
295
|
+
joins `ErrorCode`. Servers without the `code` are still recognised by the old shape check.
|
|
296
|
+
(PLAN.md §1.2/§1.3.)
|
|
297
|
+
- Export parameters for API 2.3.0 (lex-api #303): `documentTypeCode` (a type family) and
|
|
298
|
+
`changedSince` (rows whose text changed); `fetchedSince` / `changedSince` also take a `Date`
|
|
299
|
+
(sent as UTC). A `limit` that is not a positive integer throws `RangeError` before the request
|
|
300
|
+
(the API answers 400). `ExportDoneInfo` types `truncatedBy` and `credits`. Docs describe the
|
|
301
|
+
per-row billing and the filter semantics of API 2.3.0. **Publish only after lex-api #303 is
|
|
302
|
+
deployed.**
|
|
303
|
+
- `stream.truncated` reads `_done.truncated` first once the trailer has been read. From API
|
|
304
|
+
2.3.0 that flag is authoritative: set when matching rows remain unreached (`truncatedBy`:
|
|
305
|
+
`limit`, `max_rows`, `credits` or `recovered` — both join the type) and never derived from the row
|
|
306
|
+
count. The `X-Export-Truncated` header and `_meta.truncated` come from an up-front count that
|
|
307
|
+
may be a minute old and never caps the stream, so they are now only the fallback before the
|
|
308
|
+
trailer arrives. (PLAN.md §1.8; lex-api #303.)
|
|
309
|
+
|
|
310
|
+
### Changed
|
|
311
|
+
|
|
312
|
+
Retries, timeouts and error codes now follow the shared SDK contract (PLAN.md §1, identical in
|
|
313
|
+
`lexapi-python`) — **an SDK retries only when the retry cannot charge the caller twice**:
|
|
314
|
+
|
|
315
|
+
- **Retry decision table (§1.2).** 429 that is not a quota: every call. Never reached the server (DNS failure,
|
|
316
|
+
connection refused/unreachable, connect timeout incl. `ETIMEDOUT` with `syscall: "connect"`, TLS
|
|
317
|
+
certificate-verification and handshake-alert failures; Cloudflare 521/522/523): every call. App-origin
|
|
318
|
+
502/503/504: GETs, and read-only POSTs only with the opt-in. Proxy-origin 502/503/504, 520, 524 and any other
|
|
319
|
+
transport error (reset, closed connection — `fetch` cannot tell before-response from mid-response — read
|
|
320
|
+
timeout): **free calls only** (`getInfo`, webhook reads). Never: quota 429, 4xx, 500.
|
|
321
|
+
0.1 retried every 502/503/504 and every network error on a GET, including when a proxy answered after the API
|
|
322
|
+
had charged the call (no refund), and never retried a POST that provably never left the machine.
|
|
323
|
+
- **App-origin** = a non-empty `X-LexAPI-Version` header (lex-api #299 on) or a `RateLimit-Limit` header (the
|
|
324
|
+
app's rate limiter sets `RateLimit-*` on every billable app response; proxies never do). A JSON error body alone
|
|
325
|
+
is not enough.
|
|
326
|
+
- **New opt-in `retry.retryReadOnlyPosts`** (default off): the eight read-only POSTs (`search`, `getDocument`,
|
|
327
|
+
`getDocumentsBatch`, `getDocumentByUrl`, `getDocumentMetadata`, `resolve`, `semanticSearch`,
|
|
328
|
+
`semanticLegislationSearch`) also retry an app-origin 502/503/504 — refunded in full, so billing-safe.
|
|
329
|
+
`extractCitations` is a mutating call (it persists edges) and is never retried on 5xx.
|
|
330
|
+
- **Timeout model (§1.6): `timeoutMs` is a per-attempt inactivity limit**, default **95 s** (was 60 s): it runs
|
|
331
|
+
until the response head and then restarts on every body chunk, for JSON bodies and export streams alike. 0.1's
|
|
332
|
+
timer stopped at the headers, so a stalled body hung forever. 95 s lets the API's 90 s limit on one live
|
|
333
|
+
EUR-Lex fetch reach the caller as a typed, refunded 504; `timeoutMs: 60_000` restores the old value.
|
|
334
|
+
- **Retry waits (§1.2):** `Retry-After` on any status (empty or unparseable = absent); on a 429 only, then
|
|
335
|
+
`RateLimit-Reset` and the JSON `retryAfter` field. `X-RateLimit-*` is not read. Hints are clamped to the 30 s
|
|
336
|
+
cap; numbers above 1e12 / 1e9 are epoch ms / s. 0.1 used `RateLimit-Reset` on every retryable status — the API
|
|
337
|
+
sends it on every response, so a retried 5xx slept for the rate window.
|
|
338
|
+
- **Quota 429s are not retried** (legacy daily quota, monthly semantic quota: `usage.resetsAt`, no `Retry-After`,
|
|
339
|
+
no `retryAfter`) and expose `retryAfter: undefined`; `RateLimitedError.quotaExhausted` / `.resetsAt`.
|
|
340
|
+
- **Error codes (§1.3):** `NetworkError.code` is `CONNECTION_ERROR` (was `NETWORK_ERROR`); the SDK's own timeout
|
|
341
|
+
is `TimeoutError` with `code: "REQUEST_TIMEOUT"`, status 0 (was `TIMEOUT`); 503 → `SERVICE_UNAVAILABLE`
|
|
342
|
+
(`ServiceUnavailableError`); 520–523 → `UPSTREAM_ERROR`, 524 → `TIMEOUT`; any other status → `INTERNAL`
|
|
343
|
+
(unmapped 4xx such as 409/413 are a base `LexAPIError`, not an `InternalServerError`); a legacy string `error`
|
|
344
|
+
is human text, never a code; top-level `details` is kept even on bodies without an `error` member; a 204 or
|
|
345
|
+
empty 2xx body is `{}` (was `undefined`); a non-empty non-JSON 2xx is `InvalidResponseError`.
|
|
346
|
+
- **Pagination (§1.4):** cites / cited-by advance by the sum of the page's `citationCount`s and stop on a short
|
|
347
|
+
page; deliveries are deduplicated on `id`.
|
|
348
|
+
- **Credit helper (§1.5):** `getCreditUsage().unitsCharged` is `0` (was `undefined`) on legacy accounts.
|
|
349
|
+
- Dev toolchain: vitest 2 → 4, tsup/TypeScript/@types/node patch updates (clears all `npm audit` advisories,
|
|
350
|
+
which were dev-only — the package has no runtime dependencies). CI uses `npm ci` and runs the unit suite on
|
|
351
|
+
Node 20/22/24 plus the dist smoke test on Node 18, Bun and Deno.
|
|
352
|
+
|
|
353
|
+
### Breaking changes (type-level) and migration
|
|
354
|
+
|
|
355
|
+
Runtime behaviour changes are listed under *Changed* and *Fixed*; the ones that can change what your code
|
|
356
|
+
sees are also in this table. TypeScript users may see new compile errors where the old types were wrong:
|
|
357
|
+
|
|
358
|
+
| Change | Why | Migrate |
|
|
359
|
+
| --- | --- | --- |
|
|
360
|
+
| `Document.content` is `DocumentContent \| null` | The API returns `content: null` for documents whose text EUR-Lex does not publish (since 2026-08). | Check `document.textAvailability?.available` (or `document.content`) before reading `content.*`. |
|
|
361
|
+
| `WebhookCreateRequest.searchCriteria` / `WebhookUpdateRequest.searchCriteria` are `WebhookCriteria` (not `SearchRequest`) | Webhooks accept a narrower vocabulary; `procedure`, `month`, `maxPages`, `textScope: "text"`, `domain: "NATIONAL_LAW"` are refused with 400. | Pass a `WebhookCriteria` object; drop unsupported filters. |
|
|
362
|
+
| `webhooks.delete()` resolves `WebhookDeleteResponse` (was `void`); any 204/empty 2xx body resolves `{}` (was `undefined`) | The server answers `200 { success, message }`; §1.3 empty-body rule. | No change needed unless you checked for `undefined`. |
|
|
363
|
+
| `ResolveResponse.resolvedVia` is `ResolvedVia` | Real values include `ecli-corpus` / `eli-corpus`. | Update exhaustive `switch`es. |
|
|
364
|
+
| `ExportDone` / `ExportMeta` field types | Matched to the real server shape. | Read `done.truncated` / `done.written` directly. |
|
|
365
|
+
| `DocumentMetadata.author` and `Document.author` are `string \| null` | Placeholder authors are now `null`. | Handle `null`. |
|
|
366
|
+
| `SearchResponse.searchParameters` is `Omit<SearchRequest, "fresh" \| "maxPages">` | The server's echo never contains them. | Read `maxPages` from your own request. |
|
|
367
|
+
| `SubscriptionTier` gains `SCALE` and an open `(string & {})`; `CitationType` gains `corrigendum`; `DocumentTypeCode` gains `consolidated_text` | New API values. | Add the cases; a `Record<SubscriptionTier, …>` needs a fallback. |
|
|
368
|
+
| `RecentDocumentsResponse.parameters.documentType/author/subdomain` are `string \| string[] \| null` | Echo of repeated query params. | Handle arrays. |
|
|
369
|
+
| `RecentDocumentsParams.documentType` is a single `DocumentType` | The endpoint uses only the first type. | Pass one type, or use `search()` for several. |
|
|
370
|
+
| `RecentDocumentsParams.subdomain` is a single `Subdomain` | A subdomain filter sends the request to EUR-Lex result pages, where EUR-Lex reads only the first `DTS_SUBDOM`. | Pass one subdomain, or use `search()` (the web service ORs several). |
|
|
371
|
+
| `BatchDocumentError` is `{ celex, error }` (`celexNumber` / `message` deprecated, never sent) | Matches the server. | Read `e.celex` and `e.error`. |
|
|
372
|
+
| `Section.number` / `Section.title` and `Recital.number` may be `null`; `SearchResult.celex` may be `null` | The parser emits `null` when the markup has no value. | Handle `null`. |
|
|
373
|
+
| `stream.done` is the lifted trailer (`done.truncated`, `done.written`) — 0.1 exposed the raw `{_done: {…}}` | Raw key kept as `done._done`. | Read the top-level fields. |
|
|
374
|
+
| An export without its `_done` trailer throws `IncompleteExportError`; a dropped connection throws `NetworkError` | It used to finish quietly / throw a raw `TypeError`. | Catch them; treat as an incomplete export. |
|
|
375
|
+
| Unmapped 4xx (409, 413, …) are a base `LexAPIError` (code `INTERNAL`, `status` kept) instead of an `InternalServerError` | They are client errors; §1.3 keeps the code. | Branch on `status`. |
|
|
376
|
+
| A 2xx with a non-JSON body throws `InvalidResponseError` (was a `SyntaxError`) | Typed. | Catch `LexAPIError`. |
|
|
377
|
+
| `timeoutMs` covers the response body (and is an idle timeout for exports) | A stalled body used to hang. | Raise `timeoutMs` if you read very large bodies on slow links. |
|
|
378
|
+
| Retry decisions follow §1.2 (see *Changed*): billed GETs no longer retry proxy 5xx/520/524 or post-send network errors; never-reached failures retry for every method | Billing safety. | `retry: { maxRetries: 0 }` disables retries. |
|
|
379
|
+
| `timeoutMs` default 95 s and now an inactivity limit (restarts per body chunk) | §1.6. | Pass `timeoutMs` to change it. |
|
|
380
|
+
| `IncompleteExportError` / `InvalidResponseError` / `RequestAbortedError` are new error types | §1.3 / §1.8. | Catch them or the base `LexAPIError`. |
|
|
381
|
+
| `UsageInfo.resetsAt` is `string \| null` | The credit-pool mirror can carry `null` until the first reset is set. | Handle `null`. |
|
|
382
|
+
| 503 throws `ServiceUnavailableError` (was `InternalServerError`); 520–523 throw `UpstreamError`, 524 `TimeoutError` (were `InternalServerError`) | §1.3 status table. | Catch the new classes or the base `LexAPIError`. |
|
|
383
|
+
| `NetworkError.code` is `CONNECTION_ERROR` (was `NETWORK_ERROR`); a client-side timeout is `TimeoutError` with `code: "REQUEST_TIMEOUT"` (was `TIMEOUT`) | §1.3 SDK-side codes; tells the SDK's timeout apart from the server's 504. | Branch on the new codes, or on `status === 0`. |
|
|
384
|
+
| `getCreditUsage().unitsCharged` is `number` (`0` on legacy accounts, was `undefined`) | §1.5. | Drop `undefined` checks. |
|
|
385
|
+
| `DEFAULT_TIMEOUT_MS` is `95_000` | See *Changed*. | Pass `timeoutMs` explicitly to keep 60 s. |
|
|
386
|
+
|
|
387
|
+
## [0.1.0] — 2026-07-02
|
|
388
|
+
|
|
389
|
+
Initial release: request core (auth, retries with `Retry-After`, typed errors, credit visibility),
|
|
390
|
+
search and document endpoints, citations, semantic search (incl. HyDE), webhooks, NDJSON export,
|
|
391
|
+
point-in-time versions.
|
|
392
|
+
|
|
393
|
+
[0.2.0]: https://github.com/Lex-API/lexapi-typescript/compare/583b501...v0.2.0
|
|
394
|
+
[0.1.0]: https://www.npmjs.com/package/@lexapi/client/v/0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Arieta Labs Ltd
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|