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