@lexapi/client 0.1.0 → 0.2.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 +226 -0
- package/LICENSE +21 -0
- package/README.md +251 -96
- package/dist/index.cjs +1238 -321
- package/dist/index.d.cts +1420 -328
- package/dist/index.d.ts +1420 -328
- package/dist/index.js +1222 -320
- package/package.json +32 -13
package/dist/index.js
CHANGED
|
@@ -6,10 +6,43 @@ var STATUS_TO_CODE = {
|
|
|
6
6
|
403: "TIER_FORBIDDEN",
|
|
7
7
|
404: "NOT_FOUND",
|
|
8
8
|
429: "RATE_LIMITED",
|
|
9
|
+
500: "INTERNAL",
|
|
9
10
|
502: "UPSTREAM_ERROR",
|
|
10
|
-
|
|
11
|
+
503: "SERVICE_UNAVAILABLE",
|
|
12
|
+
504: "TIMEOUT",
|
|
13
|
+
// Cloudflare edge errors (non-JSON bodies). SDK contract §1.3.
|
|
14
|
+
520: "UPSTREAM_ERROR",
|
|
15
|
+
521: "UPSTREAM_ERROR",
|
|
16
|
+
522: "UPSTREAM_ERROR",
|
|
17
|
+
523: "UPSTREAM_ERROR",
|
|
18
|
+
524: "TIMEOUT"
|
|
11
19
|
};
|
|
20
|
+
var ERROR_KINDS = /* @__PURE__ */ Symbol.for("@lexapi/client.errorKinds");
|
|
21
|
+
function collectKinds(ctor) {
|
|
22
|
+
const kinds = [];
|
|
23
|
+
let current = ctor;
|
|
24
|
+
while (typeof current === "function") {
|
|
25
|
+
const kind = current.kind;
|
|
26
|
+
if (Object.prototype.hasOwnProperty.call(current, "kind") && typeof kind === "string") {
|
|
27
|
+
kinds.push(kind);
|
|
28
|
+
}
|
|
29
|
+
current = Object.getPrototypeOf(current);
|
|
30
|
+
}
|
|
31
|
+
return kinds;
|
|
32
|
+
}
|
|
33
|
+
function brandedHasInstance(ctor, value) {
|
|
34
|
+
if (typeof value !== "object" || value === null) return false;
|
|
35
|
+
if (Function.prototype[Symbol.hasInstance].call(ctor, value)) return true;
|
|
36
|
+
if (!Object.prototype.hasOwnProperty.call(ctor, "kind")) return false;
|
|
37
|
+
const kinds = value[ERROR_KINDS];
|
|
38
|
+
return Array.isArray(kinds) && kinds.includes(ctor.kind);
|
|
39
|
+
}
|
|
12
40
|
var LexAPIError = class _LexAPIError extends Error {
|
|
41
|
+
/** Stable class tag used by the cross-build `instanceof` brand check. */
|
|
42
|
+
static kind = "LexAPIError";
|
|
43
|
+
static [Symbol.hasInstance](value) {
|
|
44
|
+
return brandedHasInstance(this, value);
|
|
45
|
+
}
|
|
13
46
|
/** Stable machine-readable code (`error.code`, or derived from the HTTP status for legacy bodies). */
|
|
14
47
|
code;
|
|
15
48
|
/** HTTP status. `0` for client-side failures (network error, client-side timeout). */
|
|
@@ -24,20 +57,33 @@ var LexAPIError = class _LexAPIError extends Error {
|
|
|
24
57
|
* normalized to a delta).
|
|
25
58
|
*/
|
|
26
59
|
retryAfter;
|
|
27
|
-
|
|
60
|
+
/**
|
|
61
|
+
* The parsed JSON error body, verbatim. Useful for legacy-shape fields the
|
|
62
|
+
* typed properties don't cover (`upgradeUrl` on tier gates, `current` /
|
|
63
|
+
* `limit` on the webhook ceiling, `usage` on legacy quota 429s).
|
|
64
|
+
*/
|
|
65
|
+
body;
|
|
66
|
+
/** Parsed response headers, when the error came from an HTTP response. */
|
|
67
|
+
headers;
|
|
68
|
+
constructor(code, message, status, details, retryAfter, context) {
|
|
28
69
|
super(`[${code}] ${message} (HTTP ${status})`);
|
|
29
70
|
this.name = "LexAPIError";
|
|
30
71
|
this.code = code;
|
|
31
72
|
this.status = status;
|
|
32
73
|
this.details = details;
|
|
33
74
|
this.retryAfter = retryAfter;
|
|
75
|
+
this.body = context?.body;
|
|
76
|
+
this.headers = context?.headers;
|
|
77
|
+
Object.defineProperty(this, ERROR_KINDS, { value: collectKinds(new.target), enumerable: false });
|
|
34
78
|
}
|
|
35
79
|
/**
|
|
36
80
|
* Build the most specific error subclass for a non-2xx response.
|
|
37
81
|
* Accepts both the typed envelope and the legacy bare `{error, message}` shape.
|
|
38
82
|
*/
|
|
39
|
-
static fromResponse(status, body, headerRetryAfter) {
|
|
40
|
-
|
|
83
|
+
static fromResponse(status, body, headerRetryAfter, headers) {
|
|
84
|
+
const statusCode = STATUS_TO_CODE[status];
|
|
85
|
+
let code = statusCode ?? "INTERNAL";
|
|
86
|
+
let typedCode = false;
|
|
41
87
|
let message = `HTTP ${status}`;
|
|
42
88
|
let details;
|
|
43
89
|
let retryAfter = headerRetryAfter;
|
|
@@ -47,125 +93,241 @@ var LexAPIError = class _LexAPIError extends Error {
|
|
|
47
93
|
const err = record["error"];
|
|
48
94
|
if (typeof err === "object" && err !== null) {
|
|
49
95
|
const e = err;
|
|
50
|
-
if (typeof e["code"] === "string")
|
|
96
|
+
if (typeof e["code"] === "string") {
|
|
97
|
+
code = e["code"];
|
|
98
|
+
typedCode = true;
|
|
99
|
+
}
|
|
51
100
|
if (typeof e["message"] === "string") message = e["message"];
|
|
52
101
|
details = e["details"];
|
|
53
102
|
} else if (typeof err === "string") {
|
|
103
|
+
if (typeof record["code"] === "string" && record["code"] !== "") {
|
|
104
|
+
code = record["code"];
|
|
105
|
+
typedCode = true;
|
|
106
|
+
}
|
|
54
107
|
message = typeof record["message"] === "string" && record["message"] !== err ? `${err}: ${record["message"]}` : err;
|
|
55
|
-
|
|
56
|
-
|
|
108
|
+
details = record["details"];
|
|
109
|
+
} else {
|
|
110
|
+
if (typeof record["code"] === "string" && record["code"] !== "") {
|
|
111
|
+
code = record["code"];
|
|
112
|
+
typedCode = true;
|
|
113
|
+
}
|
|
114
|
+
if (typeof record["message"] === "string") message = record["message"];
|
|
115
|
+
details = record["details"];
|
|
57
116
|
}
|
|
58
|
-
if (retryAfter === void 0) {
|
|
117
|
+
if (retryAfter === void 0 && status === 429) {
|
|
59
118
|
const jsonRetryAfter = readNumber(record["retryAfter"]) ?? readNumber(detailsField(details, "retryAfter"));
|
|
60
119
|
if (jsonRetryAfter !== void 0) retryAfter = normalizeRetryAfterSeconds(jsonRetryAfter);
|
|
61
120
|
}
|
|
62
121
|
resetsAt = readString(detailsField(details, "resetsAt")) ?? readString(usageField(record, "resetsAt"));
|
|
63
122
|
}
|
|
123
|
+
const context = { body, ...headers ? { headers } : {} };
|
|
124
|
+
if (!typedCode && statusCode === void 0 && status < 500) {
|
|
125
|
+
return new _LexAPIError(code, message, status, details, retryAfter, context);
|
|
126
|
+
}
|
|
127
|
+
if (code === "QUOTA_EXHAUSTED" || code === "RATE_LIMITED" && isQuota429(body, headers)) {
|
|
128
|
+
return new RateLimitedError(
|
|
129
|
+
message,
|
|
130
|
+
status,
|
|
131
|
+
details,
|
|
132
|
+
void 0,
|
|
133
|
+
context,
|
|
134
|
+
code === "QUOTA_EXHAUSTED" ? "QUOTA_EXHAUSTED" : "RATE_LIMITED"
|
|
135
|
+
);
|
|
136
|
+
}
|
|
64
137
|
switch (code) {
|
|
65
138
|
case "NOT_FOUND":
|
|
66
|
-
return new NotFoundError(message, status, details, retryAfter);
|
|
139
|
+
return new NotFoundError(message, status, details, retryAfter, context);
|
|
67
140
|
case "INVALID_CELEX":
|
|
68
|
-
return new InvalidCelexError(message, status, details, retryAfter);
|
|
141
|
+
return new InvalidCelexError(message, status, details, retryAfter, context);
|
|
69
142
|
case "INVALID_URL":
|
|
70
|
-
return new InvalidUrlError(message, status, details, retryAfter);
|
|
143
|
+
return new InvalidUrlError(message, status, details, retryAfter, context);
|
|
71
144
|
case "INVALID_PARAMS":
|
|
72
|
-
return new InvalidParamsError(message, status, details, retryAfter);
|
|
145
|
+
return new InvalidParamsError(message, status, details, retryAfter, context);
|
|
73
146
|
case "RATE_LIMITED":
|
|
74
|
-
return new RateLimitedError(message, status, details, retryAfter);
|
|
147
|
+
return new RateLimitedError(message, status, details, retryAfter, context);
|
|
75
148
|
case "TIER_FORBIDDEN":
|
|
76
|
-
return new TierForbiddenError(message, status, details, retryAfter);
|
|
149
|
+
return new TierForbiddenError(message, status, details, retryAfter, context);
|
|
77
150
|
case "CREDITS_EXHAUSTED":
|
|
78
|
-
return new CreditsExhaustedError(message, status, details, retryAfter, resetsAt);
|
|
151
|
+
return new CreditsExhaustedError(message, status, details, retryAfter, resetsAt, context);
|
|
79
152
|
case "UPSTREAM_ERROR":
|
|
80
|
-
return new UpstreamError(message, status, details, retryAfter);
|
|
153
|
+
return new UpstreamError(message, status, details, retryAfter, context);
|
|
81
154
|
case "TIMEOUT":
|
|
82
|
-
return new TimeoutError(message, status, details, retryAfter);
|
|
155
|
+
return new TimeoutError(message, status, details, retryAfter, context);
|
|
83
156
|
case "UNAUTHORIZED":
|
|
84
|
-
return new AuthenticationError(message, status, details, retryAfter);
|
|
157
|
+
return new AuthenticationError(message, status, details, retryAfter, context);
|
|
158
|
+
case "SERVICE_UNAVAILABLE":
|
|
159
|
+
return new ServiceUnavailableError(message, status, details, retryAfter, context);
|
|
85
160
|
case "INTERNAL":
|
|
86
|
-
return new InternalServerError(message, status, details, retryAfter);
|
|
161
|
+
return new InternalServerError(message, status, details, retryAfter, context);
|
|
87
162
|
default:
|
|
88
|
-
return new _LexAPIError(code, message, status, details, retryAfter);
|
|
163
|
+
return new _LexAPIError(code, message, status, details, retryAfter, context);
|
|
89
164
|
}
|
|
90
165
|
}
|
|
91
166
|
};
|
|
92
167
|
var NotFoundError = class extends LexAPIError {
|
|
93
|
-
|
|
94
|
-
|
|
168
|
+
static kind = "NotFoundError";
|
|
169
|
+
constructor(message, status = 404, details, retryAfter, context) {
|
|
170
|
+
super("NOT_FOUND", message, status, details, retryAfter, context);
|
|
95
171
|
this.name = "NotFoundError";
|
|
96
172
|
}
|
|
97
173
|
};
|
|
98
174
|
var InvalidCelexError = class extends LexAPIError {
|
|
99
|
-
|
|
100
|
-
|
|
175
|
+
static kind = "InvalidCelexError";
|
|
176
|
+
constructor(message, status = 400, details, retryAfter, context) {
|
|
177
|
+
super("INVALID_CELEX", message, status, details, retryAfter, context);
|
|
101
178
|
this.name = "InvalidCelexError";
|
|
102
179
|
}
|
|
103
180
|
};
|
|
104
181
|
var InvalidUrlError = class extends LexAPIError {
|
|
105
|
-
|
|
106
|
-
|
|
182
|
+
static kind = "InvalidUrlError";
|
|
183
|
+
constructor(message, status = 400, details, retryAfter, context) {
|
|
184
|
+
super("INVALID_URL", message, status, details, retryAfter, context);
|
|
107
185
|
this.name = "InvalidUrlError";
|
|
108
186
|
}
|
|
109
187
|
};
|
|
110
188
|
var InvalidParamsError = class extends LexAPIError {
|
|
111
|
-
|
|
112
|
-
|
|
189
|
+
static kind = "InvalidParamsError";
|
|
190
|
+
constructor(message, status = 400, details, retryAfter, context) {
|
|
191
|
+
super("INVALID_PARAMS", message, status, details, retryAfter, context);
|
|
113
192
|
this.name = "InvalidParamsError";
|
|
114
193
|
}
|
|
115
194
|
};
|
|
116
195
|
var AuthenticationError = class extends LexAPIError {
|
|
117
|
-
|
|
118
|
-
|
|
196
|
+
static kind = "AuthenticationError";
|
|
197
|
+
constructor(message, status = 401, details, retryAfter, context) {
|
|
198
|
+
super("UNAUTHORIZED", message, status, details, retryAfter, context);
|
|
119
199
|
this.name = "AuthenticationError";
|
|
120
200
|
}
|
|
121
201
|
};
|
|
122
202
|
var RateLimitedError = class extends LexAPIError {
|
|
123
|
-
|
|
124
|
-
|
|
203
|
+
static kind = "RateLimitedError";
|
|
204
|
+
constructor(message, status = 429, details, retryAfter, context, code = "RATE_LIMITED") {
|
|
205
|
+
super(code, message, status, details, retryAfter, context);
|
|
125
206
|
this.name = "RateLimitedError";
|
|
126
207
|
}
|
|
208
|
+
/** `RateLimit-*` headers from the 429 response (limit / remaining / reset seconds). */
|
|
209
|
+
get rateLimit() {
|
|
210
|
+
return this.headers?.rateLimit;
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* `true` for a legacy-plan quota 429 (daily call quota, or the monthly
|
|
214
|
+
* semantic quota) rather than the per-minute limiter (SDK contract §1.2):
|
|
215
|
+
* `code` is `QUOTA_EXHAUSTED`, or — servers before lex-api #304, which
|
|
216
|
+
* send no code — the body carries `usage.resetsAt` with neither a
|
|
217
|
+
* `Retry-After` header nor a `retryAfter` body field. It cannot succeed
|
|
218
|
+
* before `resetsAt`, so the SDK does not retry it and `retryAfter` is
|
|
219
|
+
* `undefined`.
|
|
220
|
+
*/
|
|
221
|
+
get quotaExhausted() {
|
|
222
|
+
return this.code === "QUOTA_EXHAUSTED" || isQuota429(this.body, this.headers);
|
|
223
|
+
}
|
|
224
|
+
/** When a legacy quota resets: the body's `resetsAt`, else `usage.resetsAt`. */
|
|
225
|
+
get resetsAt() {
|
|
226
|
+
return readString(bodyField(this.body, "resetsAt")) ?? readString(detailsField(bodyField(this.body, "usage"), "resetsAt"));
|
|
227
|
+
}
|
|
127
228
|
};
|
|
128
229
|
var TierForbiddenError = class extends LexAPIError {
|
|
129
|
-
|
|
130
|
-
|
|
230
|
+
static kind = "TierForbiddenError";
|
|
231
|
+
constructor(message, status = 403, details, retryAfter, context) {
|
|
232
|
+
super("TIER_FORBIDDEN", message, status, details, retryAfter, context);
|
|
131
233
|
this.name = "TierForbiddenError";
|
|
132
234
|
}
|
|
133
235
|
};
|
|
134
236
|
var CreditsExhaustedError = class extends LexAPIError {
|
|
237
|
+
static kind = "CreditsExhaustedError";
|
|
135
238
|
/** When the monthly credit allowance resets (ISO date-time), when the server said so. */
|
|
136
239
|
resetsAt;
|
|
137
|
-
constructor(message, status = 402, details, retryAfter, resetsAt) {
|
|
138
|
-
super("CREDITS_EXHAUSTED", message, status, details, retryAfter);
|
|
240
|
+
constructor(message, status = 402, details, retryAfter, resetsAt, context) {
|
|
241
|
+
super("CREDITS_EXHAUSTED", message, status, details, retryAfter, context);
|
|
139
242
|
this.name = "CreditsExhaustedError";
|
|
140
243
|
this.resetsAt = resetsAt;
|
|
141
244
|
}
|
|
245
|
+
/** The refused operation's credit weight (`details.weight`). */
|
|
246
|
+
get weight() {
|
|
247
|
+
return readNumber(this.details?.weight);
|
|
248
|
+
}
|
|
249
|
+
/** Credits left in the pool (`details.available`). */
|
|
250
|
+
get available() {
|
|
251
|
+
return readNumber(this.details?.available);
|
|
252
|
+
}
|
|
253
|
+
/** The refused operation (`details.operation`). */
|
|
254
|
+
get operation() {
|
|
255
|
+
return readString(this.details?.operation);
|
|
256
|
+
}
|
|
142
257
|
};
|
|
143
258
|
var UpstreamError = class extends LexAPIError {
|
|
144
|
-
|
|
145
|
-
|
|
259
|
+
static kind = "UpstreamError";
|
|
260
|
+
constructor(message, status = 502, details, retryAfter, context) {
|
|
261
|
+
super("UPSTREAM_ERROR", message, status, details, retryAfter, context);
|
|
146
262
|
this.name = "UpstreamError";
|
|
147
263
|
}
|
|
148
264
|
};
|
|
149
265
|
var TimeoutError = class extends LexAPIError {
|
|
150
|
-
|
|
151
|
-
|
|
266
|
+
static kind = "TimeoutError";
|
|
267
|
+
constructor(message, status = 0, details, retryAfter, context) {
|
|
268
|
+
super(status === 0 ? "REQUEST_TIMEOUT" : "TIMEOUT", message, status, details, retryAfter, context);
|
|
152
269
|
this.name = "TimeoutError";
|
|
153
270
|
}
|
|
154
271
|
};
|
|
272
|
+
var ServiceUnavailableError = class extends LexAPIError {
|
|
273
|
+
static kind = "ServiceUnavailableError";
|
|
274
|
+
constructor(message, status = 503, details, retryAfter, context) {
|
|
275
|
+
super("SERVICE_UNAVAILABLE", message, status, details, retryAfter, context);
|
|
276
|
+
this.name = "ServiceUnavailableError";
|
|
277
|
+
}
|
|
278
|
+
};
|
|
155
279
|
var InternalServerError = class extends LexAPIError {
|
|
156
|
-
|
|
157
|
-
|
|
280
|
+
static kind = "InternalServerError";
|
|
281
|
+
constructor(message, status = 500, details, retryAfter, context) {
|
|
282
|
+
super("INTERNAL", message, status, details, retryAfter, context);
|
|
158
283
|
this.name = "InternalServerError";
|
|
159
284
|
}
|
|
160
285
|
};
|
|
161
286
|
var NetworkError = class extends LexAPIError {
|
|
287
|
+
static kind = "NetworkError";
|
|
162
288
|
cause;
|
|
163
289
|
constructor(message, cause) {
|
|
164
|
-
super("
|
|
290
|
+
super("CONNECTION_ERROR", message, 0);
|
|
165
291
|
this.name = "NetworkError";
|
|
166
292
|
this.cause = cause;
|
|
167
293
|
}
|
|
168
294
|
};
|
|
295
|
+
var RequestAbortedError = class extends LexAPIError {
|
|
296
|
+
static kind = "RequestAbortedError";
|
|
297
|
+
cause;
|
|
298
|
+
constructor(message, cause) {
|
|
299
|
+
super("ABORTED", message, 0);
|
|
300
|
+
this.name = "RequestAbortedError";
|
|
301
|
+
this.cause = cause;
|
|
302
|
+
}
|
|
303
|
+
};
|
|
304
|
+
var InvalidResponseError = class extends LexAPIError {
|
|
305
|
+
static kind = "InvalidResponseError";
|
|
306
|
+
constructor(message, status, rawText, context) {
|
|
307
|
+
super("INVALID_RESPONSE", message, status, void 0, void 0, {
|
|
308
|
+
...context,
|
|
309
|
+
body: rawText === void 0 ? void 0 : rawText.slice(0, 500)
|
|
310
|
+
});
|
|
311
|
+
this.name = "InvalidResponseError";
|
|
312
|
+
}
|
|
313
|
+
};
|
|
314
|
+
var IncompleteExportError = class extends LexAPIError {
|
|
315
|
+
static kind = "IncompleteExportError";
|
|
316
|
+
/** Rows yielded before the stream ended. */
|
|
317
|
+
rowsRead;
|
|
318
|
+
/**
|
|
319
|
+
* @param details the server's `_error` line body (`{ code, message }`) when
|
|
320
|
+
* one arrived; `undefined` for a missing or `complete: false` trailer.
|
|
321
|
+
*/
|
|
322
|
+
constructor(message, rowsRead, details) {
|
|
323
|
+
super("INCOMPLETE_EXPORT", message, 0, details);
|
|
324
|
+
this.name = "IncompleteExportError";
|
|
325
|
+
this.rowsRead = rowsRead;
|
|
326
|
+
}
|
|
327
|
+
};
|
|
328
|
+
function isLexAPIError(value, errorClass) {
|
|
329
|
+
return value instanceof (errorClass ?? LexAPIError);
|
|
330
|
+
}
|
|
169
331
|
function normalizeRetryAfterSeconds(value) {
|
|
170
332
|
if (!Number.isFinite(value)) return 0;
|
|
171
333
|
if (value > 1e12) return Math.max(0, Math.round((value - Date.now()) / 1e3));
|
|
@@ -184,54 +346,202 @@ function detailsField(details, key) {
|
|
|
184
346
|
}
|
|
185
347
|
return void 0;
|
|
186
348
|
}
|
|
349
|
+
function isQuota429(body, headers) {
|
|
350
|
+
if (detailsField(body, "code") === "QUOTA_EXHAUSTED") return true;
|
|
351
|
+
const resetsAt = detailsField(detailsField(body, "usage"), "resetsAt");
|
|
352
|
+
if (typeof resetsAt !== "string") return false;
|
|
353
|
+
if (headers?.retryAfter !== void 0 && headers.retryAfter.trim() !== "") return false;
|
|
354
|
+
return detailsField(body, "retryAfter") === void 0;
|
|
355
|
+
}
|
|
356
|
+
function bodyField(body, key) {
|
|
357
|
+
return detailsField(body, key);
|
|
358
|
+
}
|
|
187
359
|
function usageField(record, key) {
|
|
188
360
|
return detailsField(record["usage"], key);
|
|
189
361
|
}
|
|
190
362
|
|
|
363
|
+
// src/headers.ts
|
|
364
|
+
function str(headers, name) {
|
|
365
|
+
const value = headers.get(name);
|
|
366
|
+
return value === null ? void 0 : value;
|
|
367
|
+
}
|
|
368
|
+
function int(headers, name) {
|
|
369
|
+
const value = headers.get(name);
|
|
370
|
+
if (value === null) return void 0;
|
|
371
|
+
const parsed = Number.parseInt(value, 10);
|
|
372
|
+
return Number.isNaN(parsed) ? void 0 : parsed;
|
|
373
|
+
}
|
|
374
|
+
function compact(obj) {
|
|
375
|
+
const out = {};
|
|
376
|
+
for (const [k, v] of Object.entries(obj)) if (v !== void 0) out[k] = v;
|
|
377
|
+
return Object.keys(out).length ? out : void 0;
|
|
378
|
+
}
|
|
379
|
+
function parseResponseHeaders(source) {
|
|
380
|
+
const h = "headers" in source ? source.headers : source;
|
|
381
|
+
const textAvailable = str(h, "x-text-available");
|
|
382
|
+
const ignored = str(h, "x-ignored-documenttypes");
|
|
383
|
+
const parsed = {
|
|
384
|
+
source: str(h, "x-source"),
|
|
385
|
+
searchSource: str(h, "x-search-source"),
|
|
386
|
+
searchCache: str(h, "x-search-cache"),
|
|
387
|
+
language: str(h, "x-language"),
|
|
388
|
+
languageFallback: str(h, "x-language-fallback"),
|
|
389
|
+
textAvailable: textAvailable === void 0 ? void 0 : textAvailable !== "false",
|
|
390
|
+
corpusVersion: int(h, "x-corpus-version"),
|
|
391
|
+
corpusFetchedAt: str(h, "x-corpus-fetchedat"),
|
|
392
|
+
cache: str(h, "x-cache"),
|
|
393
|
+
warning: str(h, "x-warning"),
|
|
394
|
+
ignoredDocumentTypes: ignored === void 0 ? void 0 : ignored.split(",").filter(Boolean),
|
|
395
|
+
postFilteredBy: str(h, "x-postfiltered-by"),
|
|
396
|
+
postFilteredKept: str(h, "x-postfiltered-kept"),
|
|
397
|
+
documentTypeFanOut: int(h, "x-documenttype-fanout"),
|
|
398
|
+
languageFilter: str(h, "x-language-filter"),
|
|
399
|
+
languageKept: str(h, "x-language-kept"),
|
|
400
|
+
batch: compact({
|
|
401
|
+
corpusHits: int(h, "x-batch-corpus-hits"),
|
|
402
|
+
cellarServed: int(h, "x-batch-cellar-served"),
|
|
403
|
+
ojRecovered: int(h, "x-batch-oj-recovered"),
|
|
404
|
+
liveFetches: int(h, "x-batch-live-fetches"),
|
|
405
|
+
textUnavailable: int(h, "x-batch-text-unavailable")
|
|
406
|
+
}),
|
|
407
|
+
retryAfter: str(h, "retry-after"),
|
|
408
|
+
apiVersion: str(h, "x-lexapi-version")?.trim() || void 0,
|
|
409
|
+
release: str(h, "x-lexapi-release"),
|
|
410
|
+
languagePartialKept: int(h, "x-language-partial-kept"),
|
|
411
|
+
cacheAge: int(h, "x-cache-age"),
|
|
412
|
+
rateLimit: compact({
|
|
413
|
+
limit: int(h, "ratelimit-limit"),
|
|
414
|
+
remaining: int(h, "ratelimit-remaining"),
|
|
415
|
+
reset: int(h, "ratelimit-reset"),
|
|
416
|
+
policy: str(h, "ratelimit-policy")
|
|
417
|
+
})
|
|
418
|
+
};
|
|
419
|
+
return compact(parsed) ?? {};
|
|
420
|
+
}
|
|
421
|
+
|
|
191
422
|
// src/version.ts
|
|
192
|
-
var VERSION = "0.
|
|
423
|
+
var VERSION = "0.2.0";
|
|
193
424
|
|
|
194
425
|
// src/http.ts
|
|
195
426
|
var DEFAULT_BASE_URL = "https://lex-api.com/api/v1";
|
|
196
|
-
var DEFAULT_TIMEOUT_MS =
|
|
197
|
-
var
|
|
427
|
+
var DEFAULT_TIMEOUT_MS = 95e3;
|
|
428
|
+
var NEVER_REACHED_CODES = /* @__PURE__ */ new Set([
|
|
429
|
+
// DNS
|
|
430
|
+
"ENOTFOUND",
|
|
431
|
+
"EAI_AGAIN",
|
|
432
|
+
// TCP connect
|
|
433
|
+
"ECONNREFUSED",
|
|
434
|
+
"EHOSTUNREACH",
|
|
435
|
+
"ENETUNREACH",
|
|
436
|
+
"UND_ERR_CONNECT_TIMEOUT",
|
|
437
|
+
// TLS certificate verification (handshake)
|
|
438
|
+
"CERT_HAS_EXPIRED",
|
|
439
|
+
"CERT_NOT_YET_VALID",
|
|
440
|
+
"CERT_REVOKED",
|
|
441
|
+
"CERT_UNTRUSTED",
|
|
442
|
+
"CERT_REJECTED",
|
|
443
|
+
"CERT_SIGNATURE_FAILURE",
|
|
444
|
+
"DEPTH_ZERO_SELF_SIGNED_CERT",
|
|
445
|
+
"SELF_SIGNED_CERT_IN_CHAIN",
|
|
446
|
+
"UNABLE_TO_GET_ISSUER_CERT",
|
|
447
|
+
"UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
|
|
448
|
+
"UNABLE_TO_VERIFY_LEAF_SIGNATURE",
|
|
449
|
+
"HOSTNAME_MISMATCH",
|
|
450
|
+
"ERR_TLS_CERT_ALTNAME_INVALID",
|
|
451
|
+
// TLS handshake alerts / protocol negotiation
|
|
452
|
+
"ERR_SSL_WRONG_VERSION_NUMBER",
|
|
453
|
+
"ERR_SSL_UNSUPPORTED_PROTOCOL",
|
|
454
|
+
"ERR_SSL_NO_PROTOCOLS_AVAILABLE",
|
|
455
|
+
"ERR_SSL_SSLV3_ALERT_HANDSHAKE_FAILURE",
|
|
456
|
+
"ERR_SSL_TLSV1_ALERT_PROTOCOL_VERSION",
|
|
457
|
+
"ERR_SSL_TLSV1_ALERT_UNKNOWN_CA",
|
|
458
|
+
"ERR_SSL_SSLV3_ALERT_BAD_CERTIFICATE",
|
|
459
|
+
"ERR_SSL_SSLV3_ALERT_CERTIFICATE_EXPIRED"
|
|
460
|
+
]);
|
|
461
|
+
var CONNECT_SYSCALL_CODES = /* @__PURE__ */ new Set(["ETIMEDOUT"]);
|
|
462
|
+
var NEVER_REACHED_STATUSES = /* @__PURE__ */ new Set([521, 522, 523]);
|
|
463
|
+
var ORIGIN_DEPENDENT_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
|
|
464
|
+
var PROXY_STATUSES = /* @__PURE__ */ new Set([520, 524]);
|
|
465
|
+
function isNeverReachedError(error, depth = 0) {
|
|
466
|
+
if (depth > 6 || typeof error !== "object" || error === null) return false;
|
|
467
|
+
const { code, syscall, cause, errors } = error;
|
|
468
|
+
if (typeof code === "string") {
|
|
469
|
+
if (NEVER_REACHED_CODES.has(code)) return true;
|
|
470
|
+
if (CONNECT_SYSCALL_CODES.has(code) && syscall === "connect") return true;
|
|
471
|
+
}
|
|
472
|
+
if (Array.isArray(errors) && errors.length > 0 && errors.every((e) => isNeverReachedError(e, depth + 1))) {
|
|
473
|
+
return true;
|
|
474
|
+
}
|
|
475
|
+
return isNeverReachedError(cause, depth + 1);
|
|
476
|
+
}
|
|
477
|
+
function isAppOrigin(error) {
|
|
478
|
+
return error.headers?.apiVersion !== void 0 || error.headers?.rateLimit?.limit !== void 0;
|
|
479
|
+
}
|
|
198
480
|
function isBrowserRuntime() {
|
|
199
481
|
return typeof window !== "undefined" && typeof document !== "undefined";
|
|
200
482
|
}
|
|
483
|
+
var INSPECT = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
|
|
201
484
|
var HttpClient = class {
|
|
485
|
+
#apiKey;
|
|
202
486
|
opts;
|
|
203
487
|
userAgent;
|
|
204
488
|
constructor(opts) {
|
|
205
|
-
|
|
489
|
+
const { apiKey, ...rest } = opts;
|
|
490
|
+
this.#apiKey = apiKey;
|
|
491
|
+
this.opts = rest;
|
|
206
492
|
this.userAgent = opts.userAgentSuffix ? `lexapi-typescript/${VERSION} ${opts.userAgentSuffix}` : `lexapi-typescript/${VERSION}`;
|
|
207
493
|
}
|
|
208
|
-
/**
|
|
494
|
+
/** API base URL. */
|
|
495
|
+
get baseUrl() {
|
|
496
|
+
return this.opts.baseUrl;
|
|
497
|
+
}
|
|
498
|
+
/** Client-level per-attempt timeout (ms). */
|
|
499
|
+
get timeoutMs() {
|
|
500
|
+
return this.opts.timeoutMs;
|
|
501
|
+
}
|
|
502
|
+
/** Redacted view for `JSON.stringify` — never includes the API key. */
|
|
503
|
+
toJSON() {
|
|
504
|
+
return { baseUrl: this.opts.baseUrl, apiKey: "[redacted]" };
|
|
505
|
+
}
|
|
506
|
+
/** Redacted view for `util.inspect` / `console.log`. */
|
|
507
|
+
[INSPECT]() {
|
|
508
|
+
return `HttpClient { baseUrl: '${this.opts.baseUrl}', apiKey: '[redacted]' }`;
|
|
509
|
+
}
|
|
510
|
+
/** Perform a request and parse the JSON body (204 / empty body yields `{}`). */
|
|
209
511
|
async requestJson(options) {
|
|
210
512
|
const { data } = await this.requestJsonWithResponse(options);
|
|
211
513
|
return data;
|
|
212
514
|
}
|
|
213
|
-
/**
|
|
515
|
+
/**
|
|
516
|
+
* Like `requestJson`, but also exposes the raw `Response` (for header
|
|
517
|
+
* signals). The body is read inside the attempt, under its timeout.
|
|
518
|
+
*/
|
|
214
519
|
async requestJsonWithResponse(options) {
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
}
|
|
219
|
-
return { data: await response.json(), response };
|
|
520
|
+
return this.execute(options, async (response, ctx) => ({
|
|
521
|
+
data: await readJsonBody(response, ctx.touch),
|
|
522
|
+
response
|
|
523
|
+
}));
|
|
220
524
|
}
|
|
221
525
|
/**
|
|
222
526
|
* Perform a request and return the raw successful `Response` without
|
|
223
|
-
* consuming the body (
|
|
224
|
-
*
|
|
225
|
-
*
|
|
527
|
+
* consuming the body (streaming endpoints such as `/export`). The attempt
|
|
528
|
+
* timeout covers only the response headers; the caller applies its own
|
|
529
|
+
* idle timeout to body reads. Non-2xx responses are parsed and thrown as
|
|
530
|
+
* typed errors; the retry policy applies before the first body byte.
|
|
226
531
|
*/
|
|
227
532
|
async requestRaw(options) {
|
|
228
|
-
|
|
533
|
+
return this.execute(options, async (response) => response);
|
|
534
|
+
}
|
|
535
|
+
async execute(options, onSuccess) {
|
|
536
|
+
const { method, path, query, body, signal } = options;
|
|
229
537
|
const url = `${this.opts.baseUrl}${path}${buildQuery(query)}`;
|
|
230
538
|
const timeoutMs = options.timeoutMs ?? this.opts.timeoutMs;
|
|
231
|
-
const { maxRetries, baseDelayMs, maxDelayMs } = this.opts.retry;
|
|
539
|
+
const { maxRetries, baseDelayMs, maxDelayMs, retryReadOnlyPosts } = this.opts.retry;
|
|
540
|
+
const isGet = method === "GET";
|
|
541
|
+
const free = isGet && options.free === true;
|
|
232
542
|
const headers = {
|
|
233
|
-
"x-api-key": this
|
|
234
|
-
accept: "application/json"
|
|
543
|
+
"x-api-key": this.#apiKey,
|
|
544
|
+
accept: options.accept ?? "application/json"
|
|
235
545
|
};
|
|
236
546
|
if (!isBrowserRuntime()) {
|
|
237
547
|
headers["user-agent"] = this.userAgent;
|
|
@@ -242,189 +552,440 @@ var HttpClient = class {
|
|
|
242
552
|
serializedBody = JSON.stringify(body);
|
|
243
553
|
}
|
|
244
554
|
for (let attempt = 0; ; attempt++) {
|
|
555
|
+
throwIfAborted(signal, method, path);
|
|
556
|
+
const controller = new AbortController();
|
|
557
|
+
let timedOut = false;
|
|
558
|
+
let timer;
|
|
559
|
+
const touch = () => {
|
|
560
|
+
if (timer !== void 0) clearTimeout(timer);
|
|
561
|
+
timer = setTimeout(() => {
|
|
562
|
+
timedOut = true;
|
|
563
|
+
controller.abort();
|
|
564
|
+
}, timeoutMs);
|
|
565
|
+
};
|
|
566
|
+
touch();
|
|
567
|
+
const onAbort = () => controller.abort();
|
|
568
|
+
signal?.addEventListener("abort", onAbort, { once: true });
|
|
569
|
+
let error;
|
|
245
570
|
let response;
|
|
571
|
+
let retryTransport = false;
|
|
246
572
|
try {
|
|
247
|
-
response = await this.
|
|
573
|
+
response = await this.opts.fetchFn(url, {
|
|
248
574
|
method,
|
|
249
575
|
headers,
|
|
250
576
|
...serializedBody !== void 0 ? { body: serializedBody } : {},
|
|
251
|
-
|
|
577
|
+
signal: controller.signal
|
|
252
578
|
});
|
|
579
|
+
touch();
|
|
580
|
+
if (response.ok) {
|
|
581
|
+
return await onSuccess(response, { signal: controller.signal, timeoutMs, touch });
|
|
582
|
+
}
|
|
583
|
+
error = await parseErrorResponse(response, touch);
|
|
253
584
|
} catch (cause) {
|
|
254
|
-
if (
|
|
255
|
-
|
|
256
|
-
await sleep(fullJitterBackoff(attempt, baseDelayMs, maxDelayMs));
|
|
257
|
-
continue;
|
|
585
|
+
if (signal?.aborted) {
|
|
586
|
+
throw new RequestAbortedError(`Request ${method} ${path} was aborted`, signal.reason);
|
|
258
587
|
}
|
|
259
|
-
|
|
588
|
+
if (cause instanceof LexAPIError && !timedOut) throw cause;
|
|
589
|
+
const failure = timedOut ? new TimeoutError(`No response bytes for ${timeoutMs}ms (${method} ${path})`, 0) : new NetworkError(
|
|
590
|
+
response === void 0 ? `Network error calling ${method} ${path}` : `Connection lost while reading the response to ${method} ${path}`,
|
|
591
|
+
cause
|
|
592
|
+
);
|
|
593
|
+
const neverReached = !timedOut && response === void 0 && isNeverReachedError(cause);
|
|
594
|
+
retryTransport = attempt < maxRetries && (neverReached || free);
|
|
595
|
+
if (!retryTransport) throw failure;
|
|
596
|
+
error = failure;
|
|
597
|
+
} finally {
|
|
598
|
+
if (timer !== void 0) clearTimeout(timer);
|
|
599
|
+
signal?.removeEventListener("abort", onAbort);
|
|
260
600
|
}
|
|
261
|
-
if (
|
|
262
|
-
|
|
263
|
-
const retryable = RETRYABLE_STATUSES.has(response.status) && (method === "GET" || response.status === 429);
|
|
264
|
-
if (attempt < maxRetries && retryable) {
|
|
265
|
-
const serverWaitSeconds = serverDirectedWaitSeconds(response, error);
|
|
266
|
-
const waitMs = serverWaitSeconds !== void 0 ? Math.min(serverWaitSeconds * 1e3, maxDelayMs) : fullJitterBackoff(attempt, baseDelayMs, maxDelayMs);
|
|
267
|
-
await sleep(waitMs);
|
|
601
|
+
if (retryTransport) {
|
|
602
|
+
await sleep(fullJitterBackoff(attempt, baseDelayMs, maxDelayMs), signal, method, path);
|
|
268
603
|
continue;
|
|
269
604
|
}
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
const controller = new AbortController();
|
|
275
|
-
const timer = setTimeout(() => controller.abort(), init.timeoutMs);
|
|
276
|
-
try {
|
|
277
|
-
return await this.opts.fetchFn(url, {
|
|
278
|
-
method: init.method,
|
|
279
|
-
headers: init.headers,
|
|
280
|
-
...init.body !== void 0 ? { body: init.body } : {},
|
|
281
|
-
signal: controller.signal
|
|
282
|
-
});
|
|
283
|
-
} catch (cause) {
|
|
284
|
-
if (controller.signal.aborted) {
|
|
285
|
-
throw new TimeoutError(`Request timed out after ${init.timeoutMs}ms`, 0);
|
|
605
|
+
if (attempt < maxRetries && shouldRetryStatus(error, { isGet, free, readOnly: options.idempotent === true && retryReadOnlyPosts })) {
|
|
606
|
+
const waitMs = error.retryAfter !== void 0 ? Math.min(error.retryAfter * 1e3, maxDelayMs) : fullJitterBackoff(attempt, baseDelayMs, maxDelayMs);
|
|
607
|
+
await sleep(waitMs, signal, method, path);
|
|
608
|
+
continue;
|
|
286
609
|
}
|
|
287
|
-
throw
|
|
288
|
-
} finally {
|
|
289
|
-
clearTimeout(timer);
|
|
610
|
+
throw error;
|
|
290
611
|
}
|
|
291
612
|
}
|
|
292
613
|
};
|
|
293
|
-
|
|
294
|
-
|
|
614
|
+
function shouldRetryStatus(error, call) {
|
|
615
|
+
const status = error.status;
|
|
616
|
+
if (status === 429) return !(error instanceof RateLimitedError && error.quotaExhausted);
|
|
617
|
+
if (NEVER_REACHED_STATUSES.has(status)) return true;
|
|
618
|
+
if (ORIGIN_DEPENDENT_STATUSES.has(status)) {
|
|
619
|
+
if (isAppOrigin(error)) return call.isGet || call.readOnly;
|
|
620
|
+
return call.free;
|
|
621
|
+
}
|
|
622
|
+
if (PROXY_STATUSES.has(status)) return call.free;
|
|
623
|
+
return false;
|
|
624
|
+
}
|
|
625
|
+
async function readBodyText(response, touch) {
|
|
626
|
+
if (response.body === null || touch === void 0) return response.text();
|
|
627
|
+
const reader = response.body.getReader();
|
|
628
|
+
const decoder = new TextDecoder();
|
|
629
|
+
const parts = [];
|
|
630
|
+
for (; ; ) {
|
|
631
|
+
const { done, value } = await reader.read();
|
|
632
|
+
if (done) break;
|
|
633
|
+
touch();
|
|
634
|
+
parts.push(decoder.decode(value, { stream: true }));
|
|
635
|
+
}
|
|
636
|
+
parts.push(decoder.decode());
|
|
637
|
+
return parts.join("");
|
|
638
|
+
}
|
|
639
|
+
async function readJsonBody(response, touch) {
|
|
640
|
+
if (response.status === 204) return {};
|
|
641
|
+
const text = await readBodyText(response, touch);
|
|
642
|
+
if (text.trim() === "") return {};
|
|
295
643
|
try {
|
|
296
|
-
|
|
644
|
+
return JSON.parse(text);
|
|
297
645
|
} catch {
|
|
646
|
+
throw new InvalidResponseError(
|
|
647
|
+
`Expected a JSON body (HTTP ${response.status}, content-type ${response.headers.get("content-type") ?? "none"})`,
|
|
648
|
+
response.status,
|
|
649
|
+
text,
|
|
650
|
+
{ headers: parseResponseHeaders(response) }
|
|
651
|
+
);
|
|
652
|
+
}
|
|
653
|
+
}
|
|
654
|
+
function throwIfAborted(signal, method, path) {
|
|
655
|
+
if (signal?.aborted) {
|
|
656
|
+
throw new RequestAbortedError(`Request ${method} ${path} was aborted`, signal.reason);
|
|
657
|
+
}
|
|
658
|
+
}
|
|
659
|
+
async function parseErrorResponse(response, touch) {
|
|
660
|
+
let body;
|
|
661
|
+
try {
|
|
662
|
+
const text = await readBodyText(response, touch);
|
|
663
|
+
body = text.trim() === "" ? void 0 : JSON.parse(text);
|
|
664
|
+
} catch (cause) {
|
|
665
|
+
if (!(cause instanceof SyntaxError)) throw cause;
|
|
298
666
|
body = void 0;
|
|
299
667
|
}
|
|
300
|
-
|
|
668
|
+
const hint = headerRetryAfterSeconds(response) ?? (response.status === 429 ? resetHeaderSeconds(response, "ratelimit-reset") : void 0);
|
|
669
|
+
return LexAPIError.fromResponse(response.status, body, hint, parseResponseHeaders(response));
|
|
301
670
|
}
|
|
302
671
|
function headerRetryAfterSeconds(response) {
|
|
303
|
-
const
|
|
304
|
-
if (
|
|
305
|
-
const
|
|
306
|
-
if (
|
|
672
|
+
const raw = response.headers.get("retry-after");
|
|
673
|
+
if (raw === null) return void 0;
|
|
674
|
+
const header = raw.trim();
|
|
675
|
+
if (header === "") return void 0;
|
|
676
|
+
if (/^\d+(\.\d+)?$/.test(header)) return normalizeRetryAfterSeconds(Number(header));
|
|
677
|
+
if (/^[-+]?\d/.test(header)) return void 0;
|
|
307
678
|
const date = Date.parse(header);
|
|
308
679
|
if (!Number.isNaN(date)) return Math.max(0, Math.round((date - Date.now()) / 1e3));
|
|
309
680
|
return void 0;
|
|
310
681
|
}
|
|
311
|
-
function
|
|
312
|
-
const
|
|
313
|
-
if (
|
|
314
|
-
const
|
|
315
|
-
if (
|
|
316
|
-
|
|
317
|
-
if (Number.isFinite(seconds)) return normalizeRetryAfterSeconds(seconds);
|
|
318
|
-
}
|
|
319
|
-
return error.retryAfter;
|
|
682
|
+
function resetHeaderSeconds(response, name) {
|
|
683
|
+
const raw = response.headers.get(name);
|
|
684
|
+
if (raw === null || raw.trim() === "") return void 0;
|
|
685
|
+
const seconds = Number(raw);
|
|
686
|
+
if (!Number.isFinite(seconds) || seconds < 0) return void 0;
|
|
687
|
+
return normalizeRetryAfterSeconds(seconds);
|
|
320
688
|
}
|
|
321
689
|
function fullJitterBackoff(attempt, baseDelayMs, maxDelayMs) {
|
|
322
690
|
return Math.random() * Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
|
|
323
691
|
}
|
|
324
|
-
function sleep(ms) {
|
|
325
|
-
return new Promise((resolve) =>
|
|
692
|
+
function sleep(ms, signal, method, path) {
|
|
693
|
+
return new Promise((resolve, reject) => {
|
|
694
|
+
if (signal?.aborted) {
|
|
695
|
+
reject(new RequestAbortedError(`Request ${method} ${path} was aborted`, signal.reason));
|
|
696
|
+
return;
|
|
697
|
+
}
|
|
698
|
+
const onAbort = () => {
|
|
699
|
+
clearTimeout(timer);
|
|
700
|
+
reject(new RequestAbortedError(`Request ${method} ${path} was aborted during a retry wait`, signal?.reason));
|
|
701
|
+
};
|
|
702
|
+
const timer = setTimeout(() => {
|
|
703
|
+
signal?.removeEventListener("abort", onAbort);
|
|
704
|
+
resolve();
|
|
705
|
+
}, ms);
|
|
706
|
+
signal?.addEventListener("abort", onAbort, { once: true });
|
|
707
|
+
});
|
|
326
708
|
}
|
|
327
709
|
function buildQuery(query) {
|
|
328
710
|
if (!query) return "";
|
|
329
711
|
const params = new URLSearchParams();
|
|
330
712
|
for (const [key, value] of Object.entries(query)) {
|
|
331
|
-
if (value
|
|
713
|
+
if (value === void 0) continue;
|
|
714
|
+
if (Array.isArray(value)) {
|
|
715
|
+
for (const item of value) {
|
|
716
|
+
params.append(key, String(item));
|
|
717
|
+
}
|
|
718
|
+
} else {
|
|
719
|
+
params.set(key, String(value));
|
|
720
|
+
}
|
|
332
721
|
}
|
|
333
722
|
const qs = params.toString();
|
|
334
723
|
return qs ? `?${qs}` : "";
|
|
335
724
|
}
|
|
336
725
|
|
|
337
726
|
// src/export.ts
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
727
|
+
var NdjsonReader = class {
|
|
728
|
+
constructor(body, options) {
|
|
729
|
+
this.options = options;
|
|
730
|
+
this.reader = body.getReader();
|
|
731
|
+
const { signal } = options;
|
|
732
|
+
if (signal?.aborted) this.cancel();
|
|
733
|
+
else signal?.addEventListener("abort", this.onAbort, { once: true });
|
|
734
|
+
}
|
|
735
|
+
reader;
|
|
736
|
+
decoder = new TextDecoder();
|
|
737
|
+
/** Pieces of the line currently being received. */
|
|
738
|
+
partial = [];
|
|
739
|
+
/** Complete lines not yet handed out. */
|
|
740
|
+
ready = [];
|
|
741
|
+
eof = false;
|
|
742
|
+
released = false;
|
|
743
|
+
/** Data rows handed out so far (for error messages). */
|
|
744
|
+
rows = 0;
|
|
745
|
+
/** Releases the connection the moment the caller aborts — even while nobody is reading. */
|
|
746
|
+
onAbort = () => this.cancel();
|
|
747
|
+
/** Next trimmed, non-empty line, or `undefined` at EOF. */
|
|
748
|
+
async nextLine() {
|
|
749
|
+
const { signal } = this.options;
|
|
750
|
+
if (signal?.aborted) {
|
|
751
|
+
this.cancel();
|
|
752
|
+
throw new RequestAbortedError("Export stream was aborted", signal.reason);
|
|
753
|
+
}
|
|
343
754
|
for (; ; ) {
|
|
344
|
-
const
|
|
345
|
-
if (
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
755
|
+
const line = this.ready.shift();
|
|
756
|
+
if (line !== void 0) return line;
|
|
757
|
+
if (this.eof) {
|
|
758
|
+
const tail = this.partial.join("").trim();
|
|
759
|
+
this.partial = [];
|
|
760
|
+
return tail || void 0;
|
|
761
|
+
}
|
|
762
|
+
const chunk = await this.read();
|
|
763
|
+
if (chunk === void 0) {
|
|
764
|
+
this.eof = true;
|
|
765
|
+
this.ingest(this.decoder.decode());
|
|
766
|
+
this.release();
|
|
767
|
+
} else {
|
|
768
|
+
this.ingest(this.decoder.decode(chunk, { stream: true }));
|
|
352
769
|
}
|
|
353
770
|
}
|
|
354
|
-
buffer += decoder.decode();
|
|
355
|
-
const tail = buffer.trim();
|
|
356
|
-
if (tail) yield tail;
|
|
357
|
-
} finally {
|
|
358
|
-
reader.releaseLock();
|
|
359
771
|
}
|
|
772
|
+
ingest(text) {
|
|
773
|
+
let pos = 0;
|
|
774
|
+
for (; ; ) {
|
|
775
|
+
const newline = text.indexOf("\n", pos);
|
|
776
|
+
if (newline === -1) break;
|
|
777
|
+
this.partial.push(text.slice(pos, newline));
|
|
778
|
+
const line = this.partial.join("").trim();
|
|
779
|
+
this.partial = [];
|
|
780
|
+
if (line) this.ready.push(line);
|
|
781
|
+
pos = newline + 1;
|
|
782
|
+
}
|
|
783
|
+
if (pos < text.length) this.partial.push(text.slice(pos));
|
|
784
|
+
}
|
|
785
|
+
async read() {
|
|
786
|
+
const { idleTimeoutMs, signal } = this.options;
|
|
787
|
+
if (signal?.aborted) {
|
|
788
|
+
this.cancel();
|
|
789
|
+
throw new RequestAbortedError("Export stream was aborted", signal.reason);
|
|
790
|
+
}
|
|
791
|
+
let timer;
|
|
792
|
+
let onAbort;
|
|
793
|
+
const interruptions = new Promise((_, reject) => {
|
|
794
|
+
if (idleTimeoutMs !== void 0 && idleTimeoutMs > 0) {
|
|
795
|
+
timer = setTimeout(() => {
|
|
796
|
+
reject(
|
|
797
|
+
new TimeoutError(`Export stream received no data for ${idleTimeoutMs}ms (after ${this.rows} rows)`, 0)
|
|
798
|
+
);
|
|
799
|
+
}, idleTimeoutMs);
|
|
800
|
+
}
|
|
801
|
+
if (signal) {
|
|
802
|
+
onAbort = () => reject(new RequestAbortedError("Export stream was aborted", signal.reason));
|
|
803
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
804
|
+
}
|
|
805
|
+
});
|
|
806
|
+
try {
|
|
807
|
+
const result = await Promise.race([this.reader.read(), interruptions]);
|
|
808
|
+
if (signal?.aborted) throw new RequestAbortedError("Export stream was aborted", signal.reason);
|
|
809
|
+
return result.done ? void 0 : result.value;
|
|
810
|
+
} catch (cause) {
|
|
811
|
+
this.cancel();
|
|
812
|
+
if (cause instanceof LexAPIError) throw cause;
|
|
813
|
+
throw new NetworkError(`Export stream interrupted after ${this.rows} rows`, cause);
|
|
814
|
+
} finally {
|
|
815
|
+
if (timer !== void 0) clearTimeout(timer);
|
|
816
|
+
if (onAbort) signal?.removeEventListener("abort", onAbort);
|
|
817
|
+
}
|
|
818
|
+
}
|
|
819
|
+
/**
|
|
820
|
+
* Cancel the body immediately (even while a read is pending) and release
|
|
821
|
+
* the connection. Not awaited: a tee'd (cloned) body only settles
|
|
822
|
+
* `cancel()` once every branch is cancelled.
|
|
823
|
+
*/
|
|
824
|
+
cancel() {
|
|
825
|
+
if (this.released) return;
|
|
826
|
+
this.eof = true;
|
|
827
|
+
void this.reader.cancel().catch(() => void 0);
|
|
828
|
+
this.release();
|
|
829
|
+
}
|
|
830
|
+
release() {
|
|
831
|
+
if (this.released) return;
|
|
832
|
+
this.released = true;
|
|
833
|
+
this.options.signal?.removeEventListener("abort", this.onAbort);
|
|
834
|
+
try {
|
|
835
|
+
this.reader.releaseLock();
|
|
836
|
+
} catch {
|
|
837
|
+
}
|
|
838
|
+
}
|
|
839
|
+
};
|
|
840
|
+
function liftEnvelope(parsed, key) {
|
|
841
|
+
const inner = parsed[key];
|
|
842
|
+
if (typeof inner === "object" && inner !== null && !Array.isArray(inner)) {
|
|
843
|
+
return { ...inner, ...parsed };
|
|
844
|
+
}
|
|
845
|
+
return parsed;
|
|
846
|
+
}
|
|
847
|
+
function errorLine(parsed) {
|
|
848
|
+
const keys = Object.keys(parsed);
|
|
849
|
+
if (keys.length !== 1 || keys[0] !== "_error") return void 0;
|
|
850
|
+
const value = parsed._error;
|
|
851
|
+
return typeof value === "object" && value !== null && !Array.isArray(value) ? value : { message: String(value) };
|
|
360
852
|
}
|
|
361
853
|
function parseLine(line) {
|
|
362
854
|
try {
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
`Malformed NDJSON line in export stream: ${line.slice(0, 120)}`,
|
|
368
|
-
0,
|
|
369
|
-
cause
|
|
370
|
-
);
|
|
855
|
+
const value = JSON.parse(line);
|
|
856
|
+
return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
|
|
857
|
+
} catch {
|
|
858
|
+
return void 0;
|
|
371
859
|
}
|
|
372
860
|
}
|
|
373
861
|
var ExportStreamImpl = class {
|
|
374
862
|
meta;
|
|
375
863
|
done;
|
|
864
|
+
error;
|
|
376
865
|
headers;
|
|
377
866
|
lines;
|
|
378
867
|
pendingFirstRow;
|
|
379
868
|
consumed = false;
|
|
869
|
+
invalidLines = 0;
|
|
870
|
+
get complete() {
|
|
871
|
+
return this.done !== void 0 && this.done.complete !== false && this.error === void 0;
|
|
872
|
+
}
|
|
873
|
+
incomplete(reason) {
|
|
874
|
+
return new IncompleteExportError(
|
|
875
|
+
`Export stream is incomplete after ${this.lines.rows} rows: ${reason}`,
|
|
876
|
+
this.lines.rows,
|
|
877
|
+
this.error
|
|
878
|
+
);
|
|
879
|
+
}
|
|
880
|
+
failureReason() {
|
|
881
|
+
if (this.error !== void 0) {
|
|
882
|
+
return `the server reported an error mid-stream (${String(this.error.code ?? "UNKNOWN")}: ${String(this.error.message ?? "")})`;
|
|
883
|
+
}
|
|
884
|
+
return "its _done trailer says complete: false";
|
|
885
|
+
}
|
|
886
|
+
get rowsRead() {
|
|
887
|
+
return this.lines.rows;
|
|
888
|
+
}
|
|
889
|
+
get truncated() {
|
|
890
|
+
if (typeof this.done?.truncated === "boolean") return this.done.truncated;
|
|
891
|
+
if (this.headers.truncated !== void 0) return this.headers.truncated;
|
|
892
|
+
if (typeof this.meta?.truncated === "boolean") return this.meta.truncated;
|
|
893
|
+
return void 0;
|
|
894
|
+
}
|
|
380
895
|
constructor(lines, headers) {
|
|
381
896
|
this.lines = lines;
|
|
382
897
|
this.headers = headers;
|
|
383
898
|
}
|
|
899
|
+
async cancel() {
|
|
900
|
+
this.consumed = true;
|
|
901
|
+
this.lines.cancel();
|
|
902
|
+
}
|
|
384
903
|
/** Read the leading line so `meta` is available before iteration starts. */
|
|
385
904
|
async init() {
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
905
|
+
let parsed;
|
|
906
|
+
for (; ; ) {
|
|
907
|
+
const first = await this.lines.nextLine();
|
|
908
|
+
if (first === void 0) return;
|
|
909
|
+
parsed = parseLine(first);
|
|
910
|
+
if (parsed !== void 0) {
|
|
911
|
+
const error = errorLine(parsed);
|
|
912
|
+
if (error === void 0) break;
|
|
913
|
+
this.error = error;
|
|
914
|
+
continue;
|
|
915
|
+
}
|
|
916
|
+
this.invalidLines++;
|
|
917
|
+
}
|
|
389
918
|
if ("_meta" in parsed) {
|
|
390
|
-
this.meta = parsed;
|
|
919
|
+
this.meta = liftEnvelope(parsed, "_meta");
|
|
391
920
|
} else if ("_done" in parsed) {
|
|
392
|
-
this.done = parsed;
|
|
921
|
+
this.done = liftEnvelope(parsed, "_done");
|
|
922
|
+
this.lines.cancel();
|
|
393
923
|
} else {
|
|
394
924
|
this.pendingFirstRow = parsed;
|
|
395
925
|
}
|
|
396
926
|
}
|
|
397
927
|
async *[Symbol.asyncIterator]() {
|
|
398
928
|
if (this.consumed) {
|
|
399
|
-
|
|
929
|
+
if (this.complete) return;
|
|
930
|
+
if (this.done !== void 0 || this.error !== void 0) throw this.incomplete(this.failureReason());
|
|
931
|
+
throw new IncompleteExportError(
|
|
932
|
+
`Export stream was ended before its _done trailer (after ${this.lines.rows} rows) \u2014 call export() again to re-read`,
|
|
933
|
+
this.lines.rows
|
|
934
|
+
);
|
|
400
935
|
}
|
|
401
936
|
this.consumed = true;
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
if (
|
|
410
|
-
|
|
411
|
-
if ("_done" in parsed) {
|
|
412
|
-
this.done = parsed;
|
|
937
|
+
try {
|
|
938
|
+
if (this.pendingFirstRow !== void 0) {
|
|
939
|
+
const row = this.pendingFirstRow;
|
|
940
|
+
this.pendingFirstRow = void 0;
|
|
941
|
+
this.lines.rows++;
|
|
942
|
+
yield row;
|
|
943
|
+
}
|
|
944
|
+
if (this.done !== void 0) {
|
|
945
|
+
if (!this.complete) throw this.incomplete(this.failureReason());
|
|
413
946
|
return;
|
|
414
947
|
}
|
|
415
|
-
|
|
416
|
-
|
|
948
|
+
for (; ; ) {
|
|
949
|
+
const line = await this.lines.nextLine();
|
|
950
|
+
if (line === void 0) {
|
|
951
|
+
if (this.error !== void 0) throw this.incomplete(this.failureReason());
|
|
952
|
+
throw new IncompleteExportError(
|
|
953
|
+
`Export stream ended without its _done trailer after ${this.lines.rows} rows \u2014 the export is incomplete`,
|
|
954
|
+
this.lines.rows
|
|
955
|
+
);
|
|
956
|
+
}
|
|
957
|
+
const parsed = parseLine(line);
|
|
958
|
+
if (parsed === void 0) {
|
|
959
|
+
this.invalidLines++;
|
|
960
|
+
continue;
|
|
961
|
+
}
|
|
962
|
+
if ("_done" in parsed) {
|
|
963
|
+
this.done = liftEnvelope(parsed, "_done");
|
|
964
|
+
if (!this.complete) throw this.incomplete(this.failureReason());
|
|
965
|
+
return;
|
|
966
|
+
}
|
|
967
|
+
if ("_meta" in parsed) continue;
|
|
968
|
+
const error = errorLine(parsed);
|
|
969
|
+
if (error !== void 0) {
|
|
970
|
+
this.error = error;
|
|
971
|
+
continue;
|
|
972
|
+
}
|
|
973
|
+
this.lines.rows++;
|
|
974
|
+
yield parsed;
|
|
975
|
+
}
|
|
976
|
+
} finally {
|
|
977
|
+
this.lines.cancel();
|
|
417
978
|
}
|
|
418
979
|
}
|
|
419
980
|
};
|
|
420
|
-
async function createExportStream(response) {
|
|
981
|
+
async function createExportStream(response, options = {}) {
|
|
421
982
|
if (response.body === null) {
|
|
422
983
|
throw new LexAPIError("INTERNAL", "Export response had no body stream", response.status);
|
|
423
984
|
}
|
|
424
985
|
const totalHeader = response.headers.get("x-export-total");
|
|
425
986
|
const streamingHeader = response.headers.get("x-export-streaming");
|
|
426
987
|
const truncatedHeader = response.headers.get("x-export-truncated");
|
|
427
|
-
const stream = new ExportStreamImpl(
|
|
988
|
+
const stream = new ExportStreamImpl(new NdjsonReader(response.body, options), {
|
|
428
989
|
total: totalHeader !== null ? Number(totalHeader) : void 0,
|
|
429
990
|
streaming: streamingHeader !== null ? Number(streamingHeader) : void 0,
|
|
430
991
|
truncated: truncatedHeader !== null ? truncatedHeader === "1" : void 0
|
|
@@ -439,87 +1000,139 @@ var WebhooksAPI = class {
|
|
|
439
1000
|
constructor(http) {
|
|
440
1001
|
this.http = http;
|
|
441
1002
|
}
|
|
1003
|
+
async call(options) {
|
|
1004
|
+
const { data, response } = await this.http.requestJsonWithResponse(options);
|
|
1005
|
+
if (typeof data !== "object" || data === null) return data;
|
|
1006
|
+
return { ...data, headers: parseResponseHeaders(response) };
|
|
1007
|
+
}
|
|
442
1008
|
/**
|
|
443
1009
|
* `GET /webhooks` — every webhook owned by the caller, newest first.
|
|
444
1010
|
* The `secret` is never returned here (only once, on creation).
|
|
445
1011
|
*/
|
|
446
1012
|
async list(options) {
|
|
447
|
-
return this.
|
|
1013
|
+
return this.call({
|
|
448
1014
|
method: "GET",
|
|
449
1015
|
path: "/webhooks",
|
|
450
|
-
|
|
1016
|
+
free: true,
|
|
1017
|
+
timeoutMs: options?.timeoutMs,
|
|
1018
|
+
signal: options?.signal
|
|
451
1019
|
});
|
|
452
1020
|
}
|
|
453
1021
|
/**
|
|
454
|
-
* `POST /webhooks` —
|
|
455
|
-
*
|
|
456
|
-
*
|
|
457
|
-
*
|
|
458
|
-
*
|
|
1022
|
+
* `POST /webhooks` — needs `searchCriteria`, `watchCelex`, or both. If
|
|
1023
|
+
* `secret` is omitted the server generates one and returns it in this
|
|
1024
|
+
* response ONLY — store it. Rejected with 400 (`InvalidParamsError`):
|
|
1025
|
+
* unsupported criteria or a watch list above the plan limit carry a
|
|
1026
|
+
* `details` list; the tier webhook ceiling (FREE=0, STARTER=2,
|
|
1027
|
+
* PROFESSIONAL=10, BUSINESS=50, SCALE=100, ENTERPRISE=100) has no
|
|
1028
|
+
* `details` — read `current` / `limit` from `error.body`.
|
|
459
1029
|
*/
|
|
460
1030
|
async create(request, options) {
|
|
461
|
-
return this.
|
|
1031
|
+
return this.call({
|
|
462
1032
|
method: "POST",
|
|
463
1033
|
path: "/webhooks",
|
|
464
1034
|
body: request,
|
|
465
|
-
timeoutMs: options?.timeoutMs
|
|
1035
|
+
timeoutMs: options?.timeoutMs,
|
|
1036
|
+
signal: options?.signal
|
|
466
1037
|
});
|
|
467
1038
|
}
|
|
468
|
-
/** `GET /webhooks/{id}` — full details
|
|
1039
|
+
/** `GET /webhooks/{id}` — full details incl. `retryPolicy` and the 20 most recent deliveries. */
|
|
469
1040
|
async get(id, options) {
|
|
470
|
-
return this.
|
|
1041
|
+
return this.call({
|
|
471
1042
|
method: "GET",
|
|
472
1043
|
path: `/webhooks/${encodeURIComponent(id)}`,
|
|
473
|
-
|
|
1044
|
+
free: true,
|
|
1045
|
+
timeoutMs: options?.timeoutMs,
|
|
1046
|
+
signal: options?.signal
|
|
474
1047
|
});
|
|
475
1048
|
}
|
|
476
1049
|
/**
|
|
477
1050
|
* `PUT /webhooks/{id}` — partial update; only supplied fields change.
|
|
478
|
-
*
|
|
479
|
-
* (
|
|
1051
|
+
* `watchCelex` replaces the whole list; `searchCriteria: null` removes the
|
|
1052
|
+
* criteria (one of the two must remain). Setting `status: "ACTIVE"`
|
|
1053
|
+
* resets `consecutiveFailures`; moving a `FAILED` or `PAUSED` webhook to
|
|
1054
|
+
* `ACTIVE` also re-queues its deliveries from the last 7 days that ran out
|
|
1055
|
+
* of retries (count in `requeuedDeliveries`, 0 otherwise).
|
|
480
1056
|
*/
|
|
481
1057
|
async update(id, request, options) {
|
|
482
|
-
return this.
|
|
1058
|
+
return this.call({
|
|
483
1059
|
method: "PUT",
|
|
484
1060
|
path: `/webhooks/${encodeURIComponent(id)}`,
|
|
485
1061
|
body: request,
|
|
486
|
-
timeoutMs: options?.timeoutMs
|
|
1062
|
+
timeoutMs: options?.timeoutMs,
|
|
1063
|
+
signal: options?.signal
|
|
487
1064
|
});
|
|
488
1065
|
}
|
|
489
1066
|
/**
|
|
490
1067
|
* `DELETE /webhooks/{id}` — permanently deletes the webhook and its
|
|
491
|
-
* delivery history. Resolves
|
|
492
|
-
* `
|
|
1068
|
+
* delivery history. Resolves with the server's `{ success, message }`
|
|
1069
|
+
* (an empty object plus `headers` on a bodiless 204); a repeat delete
|
|
1070
|
+
* throws `NotFoundError`.
|
|
493
1071
|
*/
|
|
494
1072
|
async delete(id, options) {
|
|
495
|
-
|
|
1073
|
+
return this.call({
|
|
496
1074
|
method: "DELETE",
|
|
497
1075
|
path: `/webhooks/${encodeURIComponent(id)}`,
|
|
498
|
-
timeoutMs: options?.timeoutMs
|
|
1076
|
+
timeoutMs: options?.timeoutMs,
|
|
1077
|
+
signal: options?.signal
|
|
499
1078
|
});
|
|
500
1079
|
}
|
|
501
1080
|
/**
|
|
502
1081
|
* `POST /webhooks/{id}/test` — synchronously POSTs a `webhook.test`
|
|
503
1082
|
* payload (HMAC-SHA256 signed via `X-Webhook-Signature`) to the webhook
|
|
504
1083
|
* URL and returns the upstream result. 10 s timeout; redirects are not
|
|
505
|
-
* followed.
|
|
1084
|
+
* followed; not recorded in the delivery history.
|
|
506
1085
|
*/
|
|
507
1086
|
async test(id, options) {
|
|
508
|
-
return this.
|
|
1087
|
+
return this.call({
|
|
509
1088
|
method: "POST",
|
|
510
1089
|
path: `/webhooks/${encodeURIComponent(id)}/test`,
|
|
511
|
-
timeoutMs: options?.timeoutMs
|
|
1090
|
+
timeoutMs: options?.timeoutMs,
|
|
1091
|
+
signal: options?.signal
|
|
512
1092
|
});
|
|
513
1093
|
}
|
|
514
1094
|
/** `GET /webhooks/{id}/deliveries` — delivery history, most recent first. */
|
|
515
1095
|
async deliveries(id, params = {}, options) {
|
|
516
|
-
return this.
|
|
1096
|
+
return this.call({
|
|
517
1097
|
method: "GET",
|
|
518
1098
|
path: `/webhooks/${encodeURIComponent(id)}/deliveries`,
|
|
1099
|
+
free: true,
|
|
519
1100
|
query: { limit: params.limit, offset: params.offset },
|
|
520
|
-
timeoutMs: options?.timeoutMs
|
|
1101
|
+
timeoutMs: options?.timeoutMs,
|
|
1102
|
+
signal: options?.signal
|
|
521
1103
|
});
|
|
522
1104
|
}
|
|
1105
|
+
/**
|
|
1106
|
+
* Walk the whole delivery history page by page (`limit` per page, default
|
|
1107
|
+
* 50), starting at `offset`, newest first (SDK contract §1.4). Each
|
|
1108
|
+
* delivery is yielded at most once (deduplicated on `id`): a delivery
|
|
1109
|
+
* created during the walk shifts later pages by one. Stops on an empty page
|
|
1110
|
+
* or when the offset reaches `total`. Pages are free (0 credits).
|
|
1111
|
+
*
|
|
1112
|
+
* ```ts
|
|
1113
|
+
* for await (const page of client.webhooks.paginateDeliveries(id)) {
|
|
1114
|
+
* for (const d of page.deliveries) console.log(d.status, d.responseStatus);
|
|
1115
|
+
* }
|
|
1116
|
+
* ```
|
|
1117
|
+
*/
|
|
1118
|
+
async *paginateDeliveries(id, params = {}, options) {
|
|
1119
|
+
const limit = params.limit ?? 50;
|
|
1120
|
+
let offset = params.offset ?? 0;
|
|
1121
|
+
const seen = /* @__PURE__ */ new Set();
|
|
1122
|
+
for (; ; ) {
|
|
1123
|
+
const page = await this.deliveries(id, { limit, offset }, options);
|
|
1124
|
+
const count = page.deliveries.length;
|
|
1125
|
+
const fresh = page.deliveries.filter((d) => {
|
|
1126
|
+
if (typeof d.id !== "string") return true;
|
|
1127
|
+
if (seen.has(d.id)) return false;
|
|
1128
|
+
seen.add(d.id);
|
|
1129
|
+
return true;
|
|
1130
|
+
});
|
|
1131
|
+
yield { ...page, deliveries: fresh };
|
|
1132
|
+
offset += count;
|
|
1133
|
+
if (count === 0 || page.total !== void 0 && offset >= page.total) return;
|
|
1134
|
+
}
|
|
1135
|
+
}
|
|
523
1136
|
};
|
|
524
1137
|
|
|
525
1138
|
// src/client.ts
|
|
@@ -540,83 +1153,125 @@ var LexAPI = class {
|
|
|
540
1153
|
retry: {
|
|
541
1154
|
maxRetries: options.retry?.maxRetries ?? 3,
|
|
542
1155
|
baseDelayMs: options.retry?.baseDelayMs ?? 500,
|
|
543
|
-
maxDelayMs: options.retry?.maxDelayMs ?? 3e4
|
|
1156
|
+
maxDelayMs: options.retry?.maxDelayMs ?? 3e4,
|
|
1157
|
+
retryReadOnlyPosts: options.retry?.retryReadOnlyPosts ?? false
|
|
544
1158
|
},
|
|
545
1159
|
userAgentSuffix: options.userAgentSuffix
|
|
546
1160
|
});
|
|
547
1161
|
this.webhooks = new WebhooksAPI(this.http);
|
|
548
1162
|
}
|
|
1163
|
+
/** Redacted view for `JSON.stringify` — never includes the API key. */
|
|
1164
|
+
toJSON() {
|
|
1165
|
+
return { client: "LexAPI", http: this.http.toJSON() };
|
|
1166
|
+
}
|
|
1167
|
+
/** Redacted view for `util.inspect` / `console.log` — never includes the API key. */
|
|
1168
|
+
[/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
|
|
1169
|
+
return `LexAPI { baseUrl: '${this.http.baseUrl}', apiKey: '[redacted]' }`;
|
|
1170
|
+
}
|
|
1171
|
+
/** Perform a JSON request and attach the parsed response headers (+ legacy header fields). */
|
|
1172
|
+
async call(options, extra = {}) {
|
|
1173
|
+
const { data, response } = await this.http.requestJsonWithResponse(options);
|
|
1174
|
+
return withHeaders(data, response, extra.corpusVersion === true);
|
|
1175
|
+
}
|
|
549
1176
|
/**
|
|
550
1177
|
* `GET /info` — API capabilities, subscription tier, and current usage.
|
|
551
1178
|
* Free operation (0 credits); useful as a connection probe.
|
|
552
1179
|
*/
|
|
553
1180
|
async getInfo(options) {
|
|
554
|
-
return this.
|
|
1181
|
+
return this.call({
|
|
555
1182
|
method: "GET",
|
|
556
1183
|
path: "/info",
|
|
557
|
-
|
|
1184
|
+
free: true,
|
|
1185
|
+
timeoutMs: options?.timeoutMs,
|
|
1186
|
+
signal: options?.signal
|
|
558
1187
|
});
|
|
559
1188
|
}
|
|
560
1189
|
/**
|
|
561
1190
|
* `POST /search` — search EUR-Lex with structured filters.
|
|
562
1191
|
*
|
|
1192
|
+
* **Cost: 3 credits per result page** (`maxPages`, tier-clamped), charged
|
|
1193
|
+
* upfront and refunded for pages never fetched; a search that fails
|
|
1194
|
+
* before its first page is refunded in full. Identical searches within
|
|
1195
|
+
* 60 minutes are served from a result cache (`headers.searchCache: "hit"`,
|
|
1196
|
+
* same price) — pass `fresh: true` to force a re-fetch.
|
|
1197
|
+
*
|
|
563
1198
|
* At least one filter is required. Truncation and partial-result signals
|
|
564
|
-
* are surfaced
|
|
565
|
-
*
|
|
566
|
-
* `
|
|
567
|
-
*
|
|
568
|
-
* `
|
|
569
|
-
* (the `X-Warning`
|
|
1199
|
+
* are surfaced, not hidden: `truncated` / `truncatedAt` / `truncatedReason`
|
|
1200
|
+
* (tier-capped pagination), `partial` / `partialReason` (an upstream page
|
|
1201
|
+
* timed out, or `source: "corpus"` — EUR-Lex unreachable, answered from
|
|
1202
|
+
* the corpus mirror), `postFilteredBy` (`"date"` → raise `maxPages`),
|
|
1203
|
+
* `ignoredDocumentTypes`, `hint` (zero results → try semantic search), and
|
|
1204
|
+
* `xWarning` (the `X-Warning` header, e.g. `maxPages` clamped).
|
|
570
1205
|
*/
|
|
571
1206
|
async search(request, options) {
|
|
572
|
-
|
|
1207
|
+
return this.call({
|
|
573
1208
|
method: "POST",
|
|
574
1209
|
path: "/search",
|
|
575
1210
|
body: request,
|
|
576
|
-
|
|
1211
|
+
idempotent: true,
|
|
1212
|
+
timeoutMs: options?.timeoutMs,
|
|
1213
|
+
signal: options?.signal
|
|
577
1214
|
});
|
|
578
|
-
return withHeaderSignals(data, response);
|
|
579
1215
|
}
|
|
580
1216
|
/**
|
|
581
1217
|
* `POST /documentContent` — fetch a single fully-parsed document by CELEX.
|
|
582
1218
|
*
|
|
583
|
-
*
|
|
584
|
-
*
|
|
1219
|
+
* **Cost: 5 credits, settled by source** — 1 from the LexAPI corpus
|
|
1220
|
+
* (`headers.source === "corpus"`), 4 from the Publications Office Cellar
|
|
1221
|
+
* API (`"cellar"` / `"cellar-oj"`), 5 for a browser fetch (`"live"`).
|
|
1222
|
+
*
|
|
1223
|
+
* Check `document.textAvailability.available` before reading
|
|
1224
|
+
* `document.content`: a document whose text EUR-Lex does not publish is a
|
|
1225
|
+
* 200 with metadata and `content: null` (billed 1 credit), with the reason
|
|
1226
|
+
* and — for base acts — a pointer to the consolidated version. Use
|
|
1227
|
+
* `language` / `acceptLanguages` for other renditions and
|
|
1228
|
+
* `include`/`fields`/`articleId` to trim the payload.
|
|
585
1229
|
*/
|
|
586
1230
|
async getDocument(request, options) {
|
|
587
|
-
return this.
|
|
1231
|
+
return this.call({
|
|
588
1232
|
method: "POST",
|
|
589
1233
|
path: "/documentContent",
|
|
590
1234
|
body: request,
|
|
591
|
-
|
|
1235
|
+
idempotent: true,
|
|
1236
|
+
timeoutMs: options?.timeoutMs,
|
|
1237
|
+
signal: options?.signal
|
|
592
1238
|
});
|
|
593
1239
|
}
|
|
594
1240
|
/**
|
|
595
1241
|
* `POST /documentContent/batch` — fetch multiple documents in one request.
|
|
596
1242
|
*
|
|
597
|
-
*
|
|
598
|
-
*
|
|
599
|
-
*
|
|
600
|
-
*
|
|
601
|
-
*
|
|
1243
|
+
* **Cost: 5 credits per processed item, settled by source** (corpus 1,
|
|
1244
|
+
* Cellar / OJ 4, browser 5; `headers.batch` has the source counts). The
|
|
1245
|
+
* batch is clamped to the tier ceiling (FREE=1, STARTER=5,
|
|
1246
|
+
* PROFESSIONAL=20, BUSINESS+=50); trimmed items are not charged. Clamping
|
|
1247
|
+
* is surfaced: `trimmed` / `trimmedTo` / `trimmedReason` and `xWarning`.
|
|
1248
|
+
* Per-CELEX failures are collected in `errors`; text-unavailable items
|
|
1249
|
+
* stay in `documents` (counted in `textUnavailable`).
|
|
602
1250
|
*/
|
|
603
1251
|
async getDocumentsBatch(request, options) {
|
|
604
|
-
|
|
1252
|
+
return this.call({
|
|
605
1253
|
method: "POST",
|
|
606
1254
|
path: "/documentContent/batch",
|
|
607
1255
|
body: request,
|
|
608
|
-
|
|
1256
|
+
idempotent: true,
|
|
1257
|
+
timeoutMs: options?.timeoutMs,
|
|
1258
|
+
signal: options?.signal
|
|
609
1259
|
});
|
|
610
|
-
return withHeaderSignals(data, response);
|
|
611
1260
|
}
|
|
612
1261
|
/**
|
|
613
1262
|
* `GET /documents/recent` — recently-published documents (last `days`
|
|
614
|
-
* days, default 7
|
|
615
|
-
*
|
|
616
|
-
*
|
|
1263
|
+
* days, default 7; up to `limit`, default 50).
|
|
1264
|
+
*
|
|
1265
|
+
* **Cost: 3 credits per result page** (~10 results each, tier-capped);
|
|
1266
|
+
* unfiltered requests are answered from Cellar in one query
|
|
1267
|
+
* (`headers.source === "cellar"`) and settle at a single page. `author`
|
|
1268
|
+
* arrays are sent as repeated query parameters; `documentType` and
|
|
1269
|
+
* `subdomain` take ONE value — EUR-Lex applies only the first of several
|
|
1270
|
+
* on this path (use `search` for multi-type / multi-subdomain queries). `languageFilter`
|
|
1271
|
+
* reports rows dropped by the language post-filter.
|
|
617
1272
|
*/
|
|
618
1273
|
async getRecentDocuments(params = {}, options) {
|
|
619
|
-
|
|
1274
|
+
return this.call({
|
|
620
1275
|
method: "GET",
|
|
621
1276
|
path: "/documents/recent",
|
|
622
1277
|
query: {
|
|
@@ -628,62 +1283,72 @@ var LexAPI = class {
|
|
|
628
1283
|
language: params.language,
|
|
629
1284
|
limit: params.limit
|
|
630
1285
|
},
|
|
631
|
-
timeoutMs: options?.timeoutMs
|
|
1286
|
+
timeoutMs: options?.timeoutMs,
|
|
1287
|
+
signal: options?.signal
|
|
632
1288
|
});
|
|
633
|
-
return withHeaderSignals(data, response);
|
|
634
1289
|
}
|
|
635
1290
|
/**
|
|
636
|
-
* `POST /documents/url` — fetch a document by any EUR-Lex URL.
|
|
637
|
-
*
|
|
638
|
-
*
|
|
1291
|
+
* `POST /documents/url` — fetch a document by any EUR-Lex URL. Shaped like
|
|
1292
|
+
* `getDocument` plus `sourceUrl` and `extractedCelex` echo-backs. Same
|
|
1293
|
+
* settle-by-source pricing (corpus 1, Cellar 4, browser 5).
|
|
639
1294
|
*/
|
|
640
1295
|
async getDocumentByUrl(request, options) {
|
|
641
|
-
return this.
|
|
1296
|
+
return this.call({
|
|
642
1297
|
method: "POST",
|
|
643
1298
|
path: "/documents/url",
|
|
644
1299
|
body: request,
|
|
645
|
-
|
|
1300
|
+
idempotent: true,
|
|
1301
|
+
timeoutMs: options?.timeoutMs,
|
|
1302
|
+
signal: options?.signal
|
|
646
1303
|
});
|
|
647
1304
|
}
|
|
648
1305
|
/**
|
|
649
1306
|
* `POST /documents/metadata` — metadata only (title, dates, ECLI/ELI,
|
|
650
|
-
* keywords, subjects). Skips the body parse:
|
|
651
|
-
*
|
|
1307
|
+
* keywords, subjects, URLs). Skips the body parse: faster than
|
|
1308
|
+
* `getDocument`. **Cost: 5 credits, settled by source** (corpus 1, Cellar 4).
|
|
652
1309
|
*/
|
|
653
1310
|
async getDocumentMetadata(request, options) {
|
|
654
|
-
return this.
|
|
1311
|
+
return this.call({
|
|
655
1312
|
method: "POST",
|
|
656
1313
|
path: "/documents/metadata",
|
|
657
1314
|
body: request,
|
|
658
|
-
|
|
1315
|
+
idempotent: true,
|
|
1316
|
+
timeoutMs: options?.timeoutMs,
|
|
1317
|
+
signal: options?.signal
|
|
659
1318
|
});
|
|
660
1319
|
}
|
|
661
1320
|
/**
|
|
662
1321
|
* `POST /resolve` — resolve any legal identifier (bare CELEX, EUR-Lex
|
|
663
1322
|
* URL, ELI URI, or ECLI) to the canonical CELEX plus access URLs.
|
|
1323
|
+
* 1 credit. ECLIs (and unmappable ELIs) resolve via the corpus
|
|
1324
|
+
* (`resolvedVia: "ecli-corpus"` / `"eli-corpus"`).
|
|
664
1325
|
*/
|
|
665
1326
|
async resolve(identifier, options) {
|
|
666
|
-
return this.
|
|
1327
|
+
return this.call({
|
|
667
1328
|
method: "POST",
|
|
668
1329
|
path: "/resolve",
|
|
669
1330
|
body: { identifier },
|
|
670
|
-
|
|
1331
|
+
idempotent: true,
|
|
1332
|
+
timeoutMs: options?.timeoutMs,
|
|
1333
|
+
signal: options?.signal
|
|
671
1334
|
});
|
|
672
1335
|
}
|
|
673
1336
|
// ── Point-in-time versions ────────────────────────────────────────
|
|
674
|
-
//
|
|
675
|
-
//
|
|
676
|
-
//
|
|
1337
|
+
// Versions are LexAPI observation snapshots (content-hash changes between
|
|
1338
|
+
// fetches), NOT legal in-force reconstructions; history begins at first
|
|
1339
|
+
// ingestion. For the text in force on a date, use a consolidated CELEX or
|
|
1340
|
+
// semanticLegislationSearch({ asOf }).
|
|
677
1341
|
/**
|
|
678
1342
|
* `GET /documents/{celex}/versions` — version history, newest first,
|
|
679
1343
|
* current version included and flagged. 1 credit.
|
|
680
1344
|
*/
|
|
681
1345
|
async listDocumentVersions(celex, params = {}, options) {
|
|
682
|
-
return this.
|
|
1346
|
+
return this.call({
|
|
683
1347
|
method: "GET",
|
|
684
1348
|
path: `/documents/${encodeURIComponent(celex)}/versions`,
|
|
685
1349
|
query: { language: params.language },
|
|
686
|
-
timeoutMs: options?.timeoutMs
|
|
1350
|
+
timeoutMs: options?.timeoutMs,
|
|
1351
|
+
signal: options?.signal
|
|
687
1352
|
});
|
|
688
1353
|
}
|
|
689
1354
|
/**
|
|
@@ -692,13 +1357,13 @@ var LexAPI = class {
|
|
|
692
1357
|
* `X-Corpus-Version` response header. 1 credit.
|
|
693
1358
|
*/
|
|
694
1359
|
async getDocumentVersion(celex, version, params = {}, options) {
|
|
695
|
-
|
|
1360
|
+
return this.call({
|
|
696
1361
|
method: "GET",
|
|
697
1362
|
path: `/documents/${encodeURIComponent(celex)}/versions/${version}`,
|
|
698
1363
|
query: { language: params.language },
|
|
699
|
-
timeoutMs: options?.timeoutMs
|
|
700
|
-
|
|
701
|
-
|
|
1364
|
+
timeoutMs: options?.timeoutMs,
|
|
1365
|
+
signal: options?.signal
|
|
1366
|
+
}, { corpusVersion: true });
|
|
702
1367
|
}
|
|
703
1368
|
/**
|
|
704
1369
|
* `GET /documents/{celex}/at/{date}` — the snapshot LexAPI observed as
|
|
@@ -707,102 +1372,147 @@ var LexAPI = class {
|
|
|
707
1372
|
* carrying the tracking start date. 1 credit.
|
|
708
1373
|
*/
|
|
709
1374
|
async getDocumentAtDate(celex, date, params = {}, options) {
|
|
710
|
-
|
|
1375
|
+
return this.call({
|
|
711
1376
|
method: "GET",
|
|
712
1377
|
path: `/documents/${encodeURIComponent(celex)}/at/${encodeURIComponent(date)}`,
|
|
713
1378
|
query: { language: params.language },
|
|
714
|
-
timeoutMs: options?.timeoutMs
|
|
715
|
-
|
|
716
|
-
|
|
1379
|
+
timeoutMs: options?.timeoutMs,
|
|
1380
|
+
signal: options?.signal
|
|
1381
|
+
}, { corpusVersion: true });
|
|
717
1382
|
}
|
|
718
1383
|
// ── Citations ─────────────────────────────────────────────────────
|
|
719
1384
|
/**
|
|
720
1385
|
* `POST /citations/extract` — crawl a document's EUR-Lex metadata page
|
|
721
1386
|
* for citations and persist them into the graph. Idempotent: an already
|
|
722
|
-
* processed document returns
|
|
1387
|
+
* processed document returns `alreadyExtracted: true`. 5 credits,
|
|
1388
|
+
* refunded to 1 on `alreadyExtracted`.
|
|
723
1389
|
*/
|
|
724
1390
|
async extractCitations(celexNumber, options) {
|
|
725
|
-
return this.
|
|
1391
|
+
return this.call({
|
|
726
1392
|
method: "POST",
|
|
727
1393
|
path: "/citations/extract",
|
|
728
1394
|
body: { celexNumber },
|
|
729
|
-
timeoutMs: options?.timeoutMs
|
|
1395
|
+
timeoutMs: options?.timeoutMs,
|
|
1396
|
+
signal: options?.signal
|
|
730
1397
|
});
|
|
731
1398
|
}
|
|
732
1399
|
/**
|
|
733
1400
|
* `GET /citations/cites/{celexNumber}` — documents this one cites
|
|
734
1401
|
* (outbound edges), grouped by target. The document must first have been
|
|
735
|
-
* crawled via `extractCitations` to appear here.
|
|
1402
|
+
* crawled via `extractCitations` to appear here. 1 credit.
|
|
736
1403
|
*/
|
|
737
1404
|
async getCites(celexNumber, params = {}, options) {
|
|
738
|
-
return this.
|
|
1405
|
+
return this.call({
|
|
739
1406
|
method: "GET",
|
|
740
1407
|
path: `/citations/cites/${encodeURIComponent(celexNumber)}`,
|
|
741
|
-
query:
|
|
742
|
-
timeoutMs: options?.timeoutMs
|
|
1408
|
+
query: edgeQuery(params),
|
|
1409
|
+
timeoutMs: options?.timeoutMs,
|
|
1410
|
+
signal: options?.signal
|
|
743
1411
|
});
|
|
744
1412
|
}
|
|
745
1413
|
/**
|
|
746
1414
|
* `GET /citations/cited-by/{celexNumber}` — documents that cite this one
|
|
747
|
-
* (inbound edges), grouped by source.
|
|
1415
|
+
* (inbound edges), grouped by source. 1 credit. For legislation, inbound
|
|
1416
|
+
* amendment / corrigendum / repeal edges are refreshed from Cellar when
|
|
1417
|
+
* older than 7 days (waits ≤ ~2.5 s) — see `relationSync`.
|
|
748
1418
|
*/
|
|
749
1419
|
async getCitedBy(celexNumber, params = {}, options) {
|
|
750
|
-
return this.
|
|
1420
|
+
return this.call({
|
|
751
1421
|
method: "GET",
|
|
752
1422
|
path: `/citations/cited-by/${encodeURIComponent(celexNumber)}`,
|
|
753
|
-
query:
|
|
754
|
-
timeoutMs: options?.timeoutMs
|
|
1423
|
+
query: edgeQuery(params),
|
|
1424
|
+
timeoutMs: options?.timeoutMs,
|
|
1425
|
+
signal: options?.signal
|
|
755
1426
|
});
|
|
756
1427
|
}
|
|
1428
|
+
/**
|
|
1429
|
+
* Walk every page of `getCites` (offset in edge rows) until a short or
|
|
1430
|
+
* empty page (SDK contract §1.4). Each page is a billed call (1 credit).
|
|
1431
|
+
* Edges are ordered by extraction time only, so edges extracted at the
|
|
1432
|
+
* same instant or during the walk can shift: an edge may repeat or be
|
|
1433
|
+
* missed. A target's edges can straddle a page boundary, so the same
|
|
1434
|
+
* `celexNumber` may appear in two consecutive pages — merge by
|
|
1435
|
+
* `celexNumber` if you need one group per document.
|
|
1436
|
+
*/
|
|
1437
|
+
async *paginateCites(celexNumber, params = {}, options) {
|
|
1438
|
+
yield* paginateEdges(
|
|
1439
|
+
(p) => this.getCites(celexNumber, p, options),
|
|
1440
|
+
(page) => page.cites.reduce((n, g) => n + (g.citationCount ?? g.citations?.length ?? 0), 0),
|
|
1441
|
+
params
|
|
1442
|
+
);
|
|
1443
|
+
}
|
|
1444
|
+
/**
|
|
1445
|
+
* Walk every page of `getCitedBy` (offset in edge rows) until a short or
|
|
1446
|
+
* empty page (SDK contract §1.4). Each page is a billed call (1 credit);
|
|
1447
|
+
* edges may repeat or be missed if extractions happen during the walk. A source's edges can straddle a page boundary, so the same
|
|
1448
|
+
* `celexNumber` may appear in two consecutive pages.
|
|
1449
|
+
*/
|
|
1450
|
+
async *paginateCitedBy(celexNumber, params = {}, options) {
|
|
1451
|
+
yield* paginateEdges(
|
|
1452
|
+
(p) => this.getCitedBy(celexNumber, p, options),
|
|
1453
|
+
(page) => page.citedBy.reduce((n, g) => n + (g.citationCount ?? g.citations?.length ?? 0), 0),
|
|
1454
|
+
params
|
|
1455
|
+
);
|
|
1456
|
+
}
|
|
757
1457
|
/**
|
|
758
1458
|
* `GET /citations/network/{celexNumber}` — inbound and outbound
|
|
759
|
-
* neighbourhood in one call, paginated per direction.
|
|
1459
|
+
* neighbourhood in one call, paginated per direction. 20 credits.
|
|
760
1460
|
*
|
|
761
1461
|
* If the server-side wall-clock budget expires the endpoint still
|
|
762
1462
|
* returns 200 with `partial: true`, an EMPTY `network`, and `null`
|
|
763
1463
|
* paging totals — check `partial` before treating the network as empty.
|
|
764
1464
|
*/
|
|
765
1465
|
async getCitationNetwork(celexNumber, params = {}, options) {
|
|
766
|
-
return this.
|
|
1466
|
+
return this.call({
|
|
767
1467
|
method: "GET",
|
|
768
1468
|
path: `/citations/network/${encodeURIComponent(celexNumber)}`,
|
|
769
|
-
query: {
|
|
770
|
-
|
|
1469
|
+
query: {
|
|
1470
|
+
citationType: params.citationType,
|
|
1471
|
+
limit: params.limit,
|
|
1472
|
+
offset: params.offset,
|
|
1473
|
+
language: params.language
|
|
1474
|
+
},
|
|
1475
|
+
timeoutMs: options?.timeoutMs,
|
|
1476
|
+
signal: options?.signal
|
|
771
1477
|
});
|
|
772
1478
|
}
|
|
773
1479
|
/**
|
|
774
1480
|
* `GET /citations/path/{from}/{to}` — shortest citation path (BFS over
|
|
775
|
-
* outbound edges). `found: false` is a graceful HTTP 200,
|
|
776
|
-
* Default `maxDepth` 3 (max 8); the visited set is bounded
|
|
1481
|
+
* outbound edges). 20 credits. `found: false` is a graceful HTTP 200,
|
|
1482
|
+
* not an error. Default `maxDepth` 3 (max 8); the visited set is bounded
|
|
1483
|
+
* to 5000 nodes.
|
|
777
1484
|
*/
|
|
778
1485
|
async getCitationPath(from, to, params = {}, options) {
|
|
779
|
-
return this.
|
|
1486
|
+
return this.call({
|
|
780
1487
|
method: "GET",
|
|
781
1488
|
path: `/citations/path/${encodeURIComponent(from)}/${encodeURIComponent(to)}`,
|
|
782
|
-
query: { maxDepth: params.maxDepth },
|
|
783
|
-
timeoutMs: options?.timeoutMs
|
|
1489
|
+
query: { maxDepth: params.maxDepth, language: params.language },
|
|
1490
|
+
timeoutMs: options?.timeoutMs,
|
|
1491
|
+
signal: options?.signal
|
|
784
1492
|
});
|
|
785
1493
|
}
|
|
786
1494
|
/**
|
|
787
1495
|
* `GET /citations/related/{celexNumber}` — bibliographic-coupling
|
|
788
1496
|
* neighbours (documents sharing the most outbound citation targets with
|
|
789
|
-
* the seed). Returns a graceful empty list with `message`
|
|
790
|
-
* has no outbound citations to couple on.
|
|
1497
|
+
* the seed). 20 credits. Returns a graceful empty list with `message`
|
|
1498
|
+
* when the seed has no outbound citations to couple on.
|
|
791
1499
|
*/
|
|
792
1500
|
async getRelatedDocuments(celexNumber, params = {}, options) {
|
|
793
|
-
return this.
|
|
1501
|
+
return this.call({
|
|
794
1502
|
method: "GET",
|
|
795
1503
|
path: `/citations/related/${encodeURIComponent(celexNumber)}`,
|
|
796
|
-
query: { limit: params.limit },
|
|
797
|
-
timeoutMs: options?.timeoutMs
|
|
1504
|
+
query: { limit: params.limit, language: params.language },
|
|
1505
|
+
timeoutMs: options?.timeoutMs,
|
|
1506
|
+
signal: options?.signal
|
|
798
1507
|
});
|
|
799
1508
|
}
|
|
800
|
-
/** `GET /citations/stats` — global citation graph statistics. */
|
|
1509
|
+
/** `GET /citations/stats` — global citation graph statistics. 20 credits. */
|
|
801
1510
|
async getCitationStats(options) {
|
|
802
|
-
return this.
|
|
1511
|
+
return this.call({
|
|
803
1512
|
method: "GET",
|
|
804
1513
|
path: "/citations/stats",
|
|
805
|
-
timeoutMs: options?.timeoutMs
|
|
1514
|
+
timeoutMs: options?.timeoutMs,
|
|
1515
|
+
signal: options?.signal
|
|
806
1516
|
});
|
|
807
1517
|
}
|
|
808
1518
|
// ── Semantic search ───────────────────────────────────────────────
|
|
@@ -812,89 +1522,118 @@ var LexAPI = class {
|
|
|
812
1522
|
* keyword matching is literal.
|
|
813
1523
|
*
|
|
814
1524
|
* **Billing:** 5 credits per call — **15 credits with `hyde: true`**
|
|
815
|
-
* (HyDE query rewriting
|
|
816
|
-
*
|
|
817
|
-
*
|
|
818
|
-
*
|
|
819
|
-
* 10-credit premium is **refunded automatically** — verify via
|
|
820
|
-
* `credits.operation_weight`.
|
|
821
|
-
*
|
|
822
|
-
* The response exposes `hint` (present only on low-confidence,
|
|
823
|
-
* best-effort result sets — its presence is itself the signal), `hyde`
|
|
824
|
-
* (whether HyDE actually ran), and `hypotheticalDocument` (the drafted
|
|
825
|
-
* passage, present only when HyDE ran).
|
|
1525
|
+
* (HyDE query rewriting; ~1–3 s extra latency). HyDE is best-effort: on
|
|
1526
|
+
* LLM failure the search falls back to plain retrieval, the response
|
|
1527
|
+
* reports `hyde: false`, and the 10-credit premium is **refunded
|
|
1528
|
+
* automatically**.
|
|
826
1529
|
*
|
|
827
|
-
*
|
|
828
|
-
*
|
|
1530
|
+
* Hits carry a ~600-char `snippet` by default; `includeText: true`
|
|
1531
|
+
* returns the full text instead. `hint` is present only on
|
|
1532
|
+
* low-confidence result sets. Fewer results than `limit`? The ~0.7
|
|
1533
|
+
* default relevance floor cut in — pass `minScore: 0.5` (or `0`).
|
|
829
1534
|
*
|
|
830
1535
|
* Persistent document identity is `(metadata.celex_id,
|
|
831
|
-
* metadata.document_type)`; `case_id` is snapshot-scoped
|
|
832
|
-
* survive index rebuilds.
|
|
1536
|
+
* metadata.document_type)`; `case_id` is snapshot-scoped.
|
|
833
1537
|
*/
|
|
834
1538
|
async semanticSearch(request, options) {
|
|
835
|
-
return this.
|
|
1539
|
+
return this.call({
|
|
836
1540
|
method: "POST",
|
|
837
1541
|
path: "/search/semantic",
|
|
838
1542
|
body: semanticWireBody(request),
|
|
839
|
-
|
|
1543
|
+
idempotent: true,
|
|
1544
|
+
timeoutMs: options?.timeoutMs,
|
|
1545
|
+
signal: options?.signal
|
|
840
1546
|
});
|
|
841
1547
|
}
|
|
842
1548
|
/**
|
|
843
1549
|
* `POST /legislation/semantic` — embedding-based semantic search over EU
|
|
844
1550
|
* legislation; results are article-level matches (`article_ref`,
|
|
845
|
-
* `law_id`, `law_title`, `score`).
|
|
1551
|
+
* `law_id`, `law_title`, `score`). `limit` is never above 50 here.
|
|
846
1552
|
*
|
|
847
|
-
*
|
|
848
|
-
*
|
|
849
|
-
*
|
|
850
|
-
*
|
|
1553
|
+
* **Consolidated texts:** when an act and its consolidated version match
|
|
1554
|
+
* the same article you get ONE hit — the consolidated article, labelled
|
|
1555
|
+
* `consolidated` / `consolidatedAsOf` / `baseCelex` / `consolidatedNote`,
|
|
1556
|
+
* with the authentic act's own match under `baseAct`. Consolidated texts
|
|
1557
|
+
* are not authentic; cite `baseCelex`.
|
|
1558
|
+
*
|
|
1559
|
+
* **`asOf` (YYYY-MM-DD):** each hit answers with the version in force on
|
|
1560
|
+
* that date (`asOfResolved`, `asOfVersion`, `matchedVersion`); a hit that
|
|
1561
|
+
* cannot be answered keeps its latest text with `asOfResolved: false` and
|
|
1562
|
+
* an `asOfReason`. The response adds `asOf` and `asOfSummary`.
|
|
1563
|
+
*
|
|
1564
|
+
* **Cost:** 5 credits for the search; with `asOf`, each live fetch of a
|
|
1565
|
+
* version the corpus does not hold reserves 5 and settles by outcome
|
|
1566
|
+
* (Cellar 4, browser 5, no text 1, failed 0) — at most 3 per request by
|
|
1567
|
+
* default. Corpus reads are free; an unaffordable fetch is skipped
|
|
1568
|
+
* (`insufficient_credits`), never a 402. The `hyde` option is case-law only.
|
|
851
1569
|
*/
|
|
852
1570
|
async semanticLegislationSearch(request, options) {
|
|
853
|
-
return this.
|
|
1571
|
+
return this.call({
|
|
854
1572
|
method: "POST",
|
|
855
1573
|
path: "/legislation/semantic",
|
|
856
1574
|
body: semanticWireBody(request),
|
|
857
|
-
|
|
1575
|
+
idempotent: true,
|
|
1576
|
+
timeoutMs: options?.timeoutMs,
|
|
1577
|
+
signal: options?.signal
|
|
858
1578
|
});
|
|
859
1579
|
}
|
|
860
1580
|
// ── Export ────────────────────────────────────────────────────────
|
|
861
1581
|
/**
|
|
862
|
-
* `GET /export` — stream matching corpus rows as NDJSON (BUSINESS
|
|
863
|
-
*
|
|
1582
|
+
* `GET /export` — stream matching corpus rows as NDJSON (BUSINESS, SCALE
|
|
1583
|
+
* and ENTERPRISE; lower tiers get 403 `TierForbiddenError`). Metadata-only
|
|
1584
|
+
* rows are skipped unless `includeStubs: true`.
|
|
1585
|
+
*
|
|
1586
|
+
* Billing (credit plans, API 2.3.0): 1 credit per row written, at least 1
|
|
1587
|
+
* per export. The call is admitted for 1 credit, the matching rows are
|
|
1588
|
+
* counted, and the rest of 1 credit per row it can return is reserved; a
|
|
1589
|
+
* pool that cannot cover it throws `CreditsExhaustedError` before anything
|
|
1590
|
+
* streams. Unwritten rows are refunded when the stream ends; the settled
|
|
1591
|
+
* charge is `stream.done?.credits` (`charged`).
|
|
864
1592
|
*
|
|
865
1593
|
* Returns a single-pass async iterator over document rows. The leading
|
|
866
1594
|
* `_meta` envelope is parsed before this resolves (`stream.meta`); the
|
|
867
|
-
* trailing `_done` line is exposed as `stream.done` after iteration
|
|
868
|
-
*
|
|
869
|
-
*
|
|
870
|
-
*
|
|
1595
|
+
* trailing `_done` line is exposed as `stream.done` after iteration —
|
|
1596
|
+
* check `stream.truncated` (`_done.truncated` once read; the header / `_meta`
|
|
1597
|
+
* hints before) to detect rows the export did not reach instead of assuming
|
|
1598
|
+
* it was complete.
|
|
871
1599
|
*
|
|
872
1600
|
* ```ts
|
|
873
|
-
* const stream = await client.export({
|
|
874
|
-
* console.log(stream.meta, stream.headers.total);
|
|
1601
|
+
* const stream = await client.export({ documentTypeCode: "regulation", limit: 1000 });
|
|
1602
|
+
* console.log(stream.meta?.totalMatching, stream.headers.total);
|
|
875
1603
|
* for await (const row of stream) process(row.celex, row.parsedContent);
|
|
876
|
-
* if (stream.
|
|
1604
|
+
* if (stream.truncated) console.warn(`not every row reached (${stream.done?.truncatedBy}) — narrow the filters or resume with changedSince`);
|
|
877
1605
|
* ```
|
|
878
1606
|
*/
|
|
879
1607
|
async export(params = {}, options) {
|
|
1608
|
+
if (params.limit !== void 0 && !(Number.isInteger(params.limit) && params.limit >= 1)) {
|
|
1609
|
+
throw new RangeError(`limit must be a positive integer, got ${String(params.limit)}`);
|
|
1610
|
+
}
|
|
880
1611
|
const response = await this.http.requestRaw({
|
|
881
1612
|
method: "GET",
|
|
882
1613
|
path: "/export",
|
|
1614
|
+
accept: "application/x-ndjson, application/json",
|
|
883
1615
|
query: {
|
|
884
|
-
documentType: params.documentType,
|
|
885
|
-
|
|
886
|
-
|
|
1616
|
+
documentType: listParam(params.documentType),
|
|
1617
|
+
documentTypeCode: listParam(params.documentTypeCode),
|
|
1618
|
+
author: listParam(params.author),
|
|
1619
|
+
subdomain: listParam(params.subdomain),
|
|
887
1620
|
language: params.language,
|
|
888
1621
|
dateFrom: params.dateFrom,
|
|
889
1622
|
dateTo: params.dateTo,
|
|
890
|
-
fetchedSince: params.fetchedSince,
|
|
1623
|
+
fetchedSince: timestampParam(params.fetchedSince),
|
|
1624
|
+
changedSince: timestampParam(params.changedSince),
|
|
891
1625
|
includeHtml: params.includeHtml,
|
|
892
1626
|
includeContent: params.includeContent,
|
|
1627
|
+
includeStubs: params.includeStubs,
|
|
893
1628
|
limit: params.limit
|
|
894
1629
|
},
|
|
895
|
-
timeoutMs: options?.timeoutMs
|
|
1630
|
+
timeoutMs: options?.timeoutMs,
|
|
1631
|
+
signal: options?.signal
|
|
1632
|
+
});
|
|
1633
|
+
return createExportStream(response, {
|
|
1634
|
+
idleTimeoutMs: options?.timeoutMs ?? this.http.timeoutMs,
|
|
1635
|
+
...options?.signal ? { signal: options.signal } : {}
|
|
896
1636
|
});
|
|
897
|
-
return createExportStream(response);
|
|
898
1637
|
}
|
|
899
1638
|
};
|
|
900
1639
|
function semanticWireBody(request) {
|
|
@@ -905,50 +1644,213 @@ function semanticWireBody(request) {
|
|
|
905
1644
|
if (request.includeText) body["include"] = ["text"];
|
|
906
1645
|
if (request.filters !== void 0) body["filters"] = request.filters;
|
|
907
1646
|
if (request.hyde !== void 0) body["hyde"] = request.hyde;
|
|
1647
|
+
if (request.asOf !== void 0) body["asOf"] = request.asOf;
|
|
908
1648
|
return body;
|
|
909
1649
|
}
|
|
910
|
-
function
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
1650
|
+
function edgeQuery(params) {
|
|
1651
|
+
return {
|
|
1652
|
+
citationType: params.citationType,
|
|
1653
|
+
limit: params.limit,
|
|
1654
|
+
offset: params.offset,
|
|
1655
|
+
language: params.language
|
|
1656
|
+
};
|
|
1657
|
+
}
|
|
1658
|
+
function timestampParam(value) {
|
|
1659
|
+
return value instanceof Date ? value.toISOString() : value;
|
|
1660
|
+
}
|
|
1661
|
+
function listParam(value) {
|
|
1662
|
+
if (value === void 0) return void 0;
|
|
1663
|
+
return typeof value === "string" ? value : value.join(",");
|
|
1664
|
+
}
|
|
1665
|
+
async function* paginateEdges(fetchPage, rawRowsIn, params) {
|
|
1666
|
+
const limit = params.limit ?? 100;
|
|
1667
|
+
let offset = params.offset ?? 0;
|
|
1668
|
+
for (; ; ) {
|
|
1669
|
+
const page = await fetchPage({ ...params, limit, offset });
|
|
1670
|
+
yield page;
|
|
1671
|
+
const pageLimit = page.limit && page.limit > 0 ? page.limit : limit;
|
|
1672
|
+
const rows = rawRowsIn(page);
|
|
1673
|
+
offset += rows;
|
|
1674
|
+
if (rows === 0 || rows < pageLimit) return;
|
|
914
1675
|
}
|
|
915
|
-
return data;
|
|
916
1676
|
}
|
|
917
|
-
function
|
|
918
|
-
|
|
919
|
-
const
|
|
920
|
-
|
|
921
|
-
|
|
1677
|
+
function withHeaders(data, response, corpusVersion) {
|
|
1678
|
+
if (typeof data !== "object" || data === null || Array.isArray(data)) return data;
|
|
1679
|
+
const headers = parseResponseHeaders(response);
|
|
1680
|
+
const out = { ...data, headers };
|
|
1681
|
+
if (headers.warning !== void 0) out["xWarning"] = headers.warning;
|
|
1682
|
+
if (corpusVersion && headers.corpusVersion !== void 0) {
|
|
1683
|
+
out["corpusVersion"] = headers.corpusVersion;
|
|
922
1684
|
}
|
|
923
|
-
return
|
|
1685
|
+
return out;
|
|
924
1686
|
}
|
|
925
1687
|
|
|
926
1688
|
// src/credits.ts
|
|
927
1689
|
function getCreditUsage(response) {
|
|
928
1690
|
return {
|
|
929
|
-
unitsCharged: response.credits?.operation_weight,
|
|
1691
|
+
unitsCharged: response.credits?.operation_weight ?? 0,
|
|
930
1692
|
creditsRemaining: response.credits?.remaining ?? response.usage?.remaining,
|
|
931
1693
|
resetsAt: response.credits?.resetsAt ?? response.usage?.resetsAt
|
|
932
1694
|
};
|
|
933
1695
|
}
|
|
1696
|
+
|
|
1697
|
+
// src/webhookSignature.ts
|
|
1698
|
+
var WEBHOOK_SIGNATURE_HEADER = "x-webhook-signature";
|
|
1699
|
+
var WEBHOOK_DELIVERY_HEADER = "x-webhook-delivery";
|
|
1700
|
+
var WEBHOOK_ID_HEADER = "x-webhook-id";
|
|
1701
|
+
var VERIFICATION_BRAND = /* @__PURE__ */ Symbol.for("@lexapi/client.webhookSignatureError");
|
|
1702
|
+
var WebhookSignatureError = class _WebhookSignatureError extends Error {
|
|
1703
|
+
reason;
|
|
1704
|
+
static [Symbol.hasInstance](value) {
|
|
1705
|
+
if (typeof value !== "object" || value === null) return false;
|
|
1706
|
+
if (Function.prototype[Symbol.hasInstance].call(this, value)) return true;
|
|
1707
|
+
return this === _WebhookSignatureError && value[VERIFICATION_BRAND] === true;
|
|
1708
|
+
}
|
|
1709
|
+
constructor(reason, message) {
|
|
1710
|
+
super(message);
|
|
1711
|
+
this.name = "WebhookSignatureError";
|
|
1712
|
+
this.reason = reason;
|
|
1713
|
+
Object.defineProperty(this, VERIFICATION_BRAND, { value: true, enumerable: false });
|
|
1714
|
+
}
|
|
1715
|
+
};
|
|
1716
|
+
function assertSecret(secret) {
|
|
1717
|
+
if (typeof secret !== "string" || secret.length === 0) {
|
|
1718
|
+
throw new WebhookSignatureError(
|
|
1719
|
+
"missing_secret",
|
|
1720
|
+
"Webhook secret is empty \u2014 pass the secret returned when the webhook was created"
|
|
1721
|
+
);
|
|
1722
|
+
}
|
|
1723
|
+
}
|
|
1724
|
+
async function getSubtle() {
|
|
1725
|
+
const globalCrypto = globalThis.crypto;
|
|
1726
|
+
if (globalCrypto?.subtle) return globalCrypto.subtle;
|
|
1727
|
+
const specifier = "node:crypto";
|
|
1728
|
+
const nodeCrypto = await import(
|
|
1729
|
+
/* webpackIgnore: true */
|
|
1730
|
+
/* @vite-ignore */
|
|
1731
|
+
specifier
|
|
1732
|
+
);
|
|
1733
|
+
if (nodeCrypto.webcrypto?.subtle) return nodeCrypto.webcrypto.subtle;
|
|
1734
|
+
throw new Error("Web Crypto (crypto.subtle) is not available in this runtime");
|
|
1735
|
+
}
|
|
1736
|
+
function toBytes(body) {
|
|
1737
|
+
if (typeof body === "string") return new TextEncoder().encode(body);
|
|
1738
|
+
if (body instanceof Uint8Array) return body;
|
|
1739
|
+
return new Uint8Array(body);
|
|
1740
|
+
}
|
|
1741
|
+
function toHex(buffer) {
|
|
1742
|
+
let hex = "";
|
|
1743
|
+
for (const byte of new Uint8Array(buffer)) hex += byte.toString(16).padStart(2, "0");
|
|
1744
|
+
return hex;
|
|
1745
|
+
}
|
|
1746
|
+
function timingSafeEqual(a, b) {
|
|
1747
|
+
if (a.length !== b.length) return false;
|
|
1748
|
+
let diff = 0;
|
|
1749
|
+
for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
|
|
1750
|
+
return diff === 0;
|
|
1751
|
+
}
|
|
1752
|
+
async function computeSignature(rawBody, secret) {
|
|
1753
|
+
assertSecret(secret);
|
|
1754
|
+
const subtle = await getSubtle();
|
|
1755
|
+
const key = await subtle.importKey(
|
|
1756
|
+
"raw",
|
|
1757
|
+
new TextEncoder().encode(secret),
|
|
1758
|
+
{ name: "HMAC", hash: "SHA-256" },
|
|
1759
|
+
false,
|
|
1760
|
+
["sign"]
|
|
1761
|
+
);
|
|
1762
|
+
return toHex(await subtle.sign("HMAC", key, toBytes(rawBody)));
|
|
1763
|
+
}
|
|
1764
|
+
async function verifySignature(rawBody, signature, secret) {
|
|
1765
|
+
const candidate = typeof signature === "string" ? signature.trim().toLowerCase() : "";
|
|
1766
|
+
const expected = await computeSignature(rawBody, secret);
|
|
1767
|
+
if (!/^[0-9a-f]{64}$/.test(candidate)) return false;
|
|
1768
|
+
return timingSafeEqual(expected, candidate);
|
|
1769
|
+
}
|
|
1770
|
+
async function verifyWebhook(rawBody, signature, secret, options = {}) {
|
|
1771
|
+
assertSecret(secret);
|
|
1772
|
+
if (!signature) {
|
|
1773
|
+
throw new WebhookSignatureError("missing_signature", "Missing X-Webhook-Signature header");
|
|
1774
|
+
}
|
|
1775
|
+
if (!await verifySignature(rawBody, signature, secret)) {
|
|
1776
|
+
throw new WebhookSignatureError("invalid_signature", "X-Webhook-Signature does not match the body");
|
|
1777
|
+
}
|
|
1778
|
+
let payload;
|
|
1779
|
+
try {
|
|
1780
|
+
const text = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(toBytes(rawBody));
|
|
1781
|
+
payload = JSON.parse(text);
|
|
1782
|
+
} catch {
|
|
1783
|
+
throw new WebhookSignatureError("malformed_body", "Webhook body is not valid JSON");
|
|
1784
|
+
}
|
|
1785
|
+
const toleranceMs = options.toleranceMs ?? 3e5;
|
|
1786
|
+
if (toleranceMs > 0) {
|
|
1787
|
+
const sentAt = Date.parse(String(payload.timestamp));
|
|
1788
|
+
const now = options.now ?? Date.now();
|
|
1789
|
+
if (Number.isNaN(sentAt) || Math.abs(now - sentAt) > toleranceMs) {
|
|
1790
|
+
throw new WebhookSignatureError(
|
|
1791
|
+
"stale_timestamp",
|
|
1792
|
+
`Webhook timestamp is outside the ${toleranceMs} ms tolerance window`
|
|
1793
|
+
);
|
|
1794
|
+
}
|
|
1795
|
+
}
|
|
1796
|
+
return payload;
|
|
1797
|
+
}
|
|
1798
|
+
|
|
1799
|
+
// src/types.ts
|
|
1800
|
+
var AS_OF_REASONS = [
|
|
1801
|
+
"not_yet_adopted",
|
|
1802
|
+
"not_yet_in_force",
|
|
1803
|
+
"no_longer_in_force",
|
|
1804
|
+
"in_force_dates_unknown",
|
|
1805
|
+
"not_in_language",
|
|
1806
|
+
"text_unavailable",
|
|
1807
|
+
"article_not_in_version",
|
|
1808
|
+
"part_not_resolvable",
|
|
1809
|
+
"article_unknown",
|
|
1810
|
+
"version_list_unavailable",
|
|
1811
|
+
"version_lookup_cap",
|
|
1812
|
+
"fetch_budget_exhausted",
|
|
1813
|
+
"fetch_pending",
|
|
1814
|
+
"fetch_capacity",
|
|
1815
|
+
"fetch_failed",
|
|
1816
|
+
"fetch_timeout",
|
|
1817
|
+
"request_deadline",
|
|
1818
|
+
"insufficient_credits",
|
|
1819
|
+
"credit_check_failed"
|
|
1820
|
+
];
|
|
934
1821
|
export {
|
|
1822
|
+
AS_OF_REASONS,
|
|
935
1823
|
AuthenticationError,
|
|
936
1824
|
CreditsExhaustedError,
|
|
937
1825
|
DEFAULT_BASE_URL,
|
|
938
1826
|
DEFAULT_TIMEOUT_MS,
|
|
1827
|
+
IncompleteExportError,
|
|
939
1828
|
InternalServerError,
|
|
940
1829
|
InvalidCelexError,
|
|
941
1830
|
InvalidParamsError,
|
|
1831
|
+
InvalidResponseError,
|
|
942
1832
|
InvalidUrlError,
|
|
943
1833
|
LexAPI,
|
|
944
1834
|
LexAPIError,
|
|
945
1835
|
NetworkError,
|
|
946
1836
|
NotFoundError,
|
|
947
1837
|
RateLimitedError,
|
|
1838
|
+
RequestAbortedError,
|
|
1839
|
+
ServiceUnavailableError,
|
|
948
1840
|
TierForbiddenError,
|
|
949
1841
|
TimeoutError,
|
|
950
1842
|
UpstreamError,
|
|
951
1843
|
VERSION,
|
|
1844
|
+
WEBHOOK_DELIVERY_HEADER,
|
|
1845
|
+
WEBHOOK_ID_HEADER,
|
|
1846
|
+
WEBHOOK_SIGNATURE_HEADER,
|
|
1847
|
+
WebhookSignatureError,
|
|
952
1848
|
WebhooksAPI,
|
|
953
|
-
|
|
1849
|
+
computeSignature,
|
|
1850
|
+
getCreditUsage,
|
|
1851
|
+
isLexAPIError,
|
|
1852
|
+
normalizeRetryAfterSeconds,
|
|
1853
|
+
parseResponseHeaders,
|
|
1854
|
+
verifySignature,
|
|
1855
|
+
verifyWebhook
|
|
954
1856
|
};
|