uvd-describe-sdk 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/README.md +56 -2
- package/dist/{client-s3KrgrCt.d.mts → client-RAhXcpdY.d.mts} +67 -13
- package/dist/{client-s3KrgrCt.d.ts → client-RAhXcpdY.d.ts} +67 -13
- package/dist/{config-Y2VK_neB.d.mts → config-uvI_GS-x.d.mts} +1 -1
- package/dist/{config-Y2VK_neB.d.ts → config-uvI_GS-x.d.ts} +1 -1
- package/dist/index.d.mts +46 -3
- package/dist/index.d.ts +46 -3
- package/dist/index.js +127 -22
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +127 -22
- package/dist/index.mjs.map +1 -1
- package/dist/partner/index.d.mts +2 -2
- package/dist/partner/index.d.ts +2 -2
- package/dist/partner/index.js.map +1 -1
- package/dist/partner/index.mjs.map +1 -1
- package/dist/x402/index.d.mts +1 -1
- package/dist/x402/index.d.ts +1 -1
- package/package.json +1 -1
- package/src/client.ts +153 -15
- package/src/config.ts +1 -1
- package/src/errors.ts +58 -17
- package/src/format.ts +17 -0
- package/src/parse.ts +72 -0
- package/src/types.ts +22 -6
package/dist/index.mjs
CHANGED
|
@@ -6,7 +6,7 @@ var DEFAULT_JITTER_MS = 400;
|
|
|
6
6
|
var TREASURY_EVM = "0xe4dc963c56979E0260fc146b87eE24F18220e545";
|
|
7
7
|
var PARTNER_CHAIN_ID = 8453;
|
|
8
8
|
var PARTNER_KEY_ENV = "DESCRIBE_PARTNER_PRIVATE_KEY";
|
|
9
|
-
var SDK_VERSION = "0.
|
|
9
|
+
var SDK_VERSION = "0.2.0";
|
|
10
10
|
var SDK_NAME = "uvd-describe-sdk-ts";
|
|
11
11
|
function userAgent(product) {
|
|
12
12
|
const base = `${SDK_NAME}/${SDK_VERSION}`;
|
|
@@ -133,19 +133,41 @@ var DescribeNotFound = class extends DescribeError {
|
|
|
133
133
|
}
|
|
134
134
|
};
|
|
135
135
|
var DescribeHTTPError = class extends DescribeError {
|
|
136
|
-
|
|
136
|
+
/**
|
|
137
|
+
* What the body SAID, not just the number it said it with — Execution
|
|
138
|
+
* Market's contribution, ported 2026-08-31 from the Python twin
|
|
139
|
+
* (`errors.py::DescribeHTTPError.server_reason` — same field, same
|
|
140
|
+
* `' — the server says: '` text): this class's recovery has promised since
|
|
141
|
+
* day one that *"the body names the field"*, and until today the exception
|
|
142
|
+
* threw that body away and carried the bare status. Whoever caught a 422
|
|
143
|
+
* had to re-request to learn which field was wrong.
|
|
144
|
+
*
|
|
145
|
+
* It arrives ALREADY redacted and truncated by `client.ts::serverReason` —
|
|
146
|
+
* the body is server-written text and a 5xx can echo an upstream URL with
|
|
147
|
+
* an API key in its path — and it is appended to the MESSAGE, never to
|
|
148
|
+
* `recovery`, which stays the frozen literal `recovery.test.ts` pins. The
|
|
149
|
+
* parameter is third and optional so every existing call keeps meaning what
|
|
150
|
+
* it meant — additive, like the twin's keyword-only argument.
|
|
151
|
+
*/
|
|
152
|
+
serverReason;
|
|
153
|
+
constructor(status, message, opts = {}) {
|
|
137
154
|
const server = status >= 500;
|
|
138
|
-
super(
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
155
|
+
super(
|
|
156
|
+
server ? "http_5xx" : "http_4xx",
|
|
157
|
+
opts.serverReason ? `${message} \u2014 the server says: ${opts.serverReason}` : message,
|
|
158
|
+
{
|
|
159
|
+
// 429 is the one 4xx worth retrying: the 20 rps ceiling is shared with
|
|
160
|
+
// every other UVD consumer, so it says "someone else is loud right now",
|
|
161
|
+
// not "your request is wrong".
|
|
162
|
+
transient: server || status === 429,
|
|
163
|
+
// A 4xx is the caller's fault and must NOT vanish into failOpen — except
|
|
164
|
+
// 429, which is the shared limit and reads exactly like a brief outage.
|
|
165
|
+
serviceFault: server || status === 429,
|
|
166
|
+
status
|
|
167
|
+
}
|
|
168
|
+
);
|
|
148
169
|
this.name = "DescribeHTTPError";
|
|
170
|
+
this.serverReason = opts.serverReason;
|
|
149
171
|
}
|
|
150
172
|
};
|
|
151
173
|
var DescribePaymentRequired = class extends DescribeError {
|
|
@@ -418,6 +440,16 @@ function parseWalletReputation(payload) {
|
|
|
418
440
|
if (!isObj(payload) || typeof payload.wallet !== "string") {
|
|
419
441
|
throw new DescribeUnparseable("wallet-chains response is missing its essential shape (wallet)");
|
|
420
442
|
}
|
|
443
|
+
if ("globalScore" in payload || "finalScore" in payload || "weightedScore" in payload) {
|
|
444
|
+
throw new DescribeUnparseable(
|
|
445
|
+
"this payload is already parsed (it carries a camelCase score key, which the wire never does): do not parse twice. `client.wallet()` already parses, and the payload as served is in `.raw`."
|
|
446
|
+
);
|
|
447
|
+
}
|
|
448
|
+
if ("final_score" in payload && !("global_score" in payload)) {
|
|
449
|
+
throw new DescribeUnparseable(
|
|
450
|
+
"this is the METERED route's payload (`GET /reputation/wallet/{wallet}` \u2014 it carries a top-level `final_score` and no `global_score`): it goes to parseWalletBreakdown, not parseWalletReputation. Parsing it here would answer nulls for a score the metered route DID serve."
|
|
451
|
+
);
|
|
452
|
+
}
|
|
421
453
|
const rows = Array.isArray(payload.chains) ? payload.chains : [];
|
|
422
454
|
const chains = rows.filter(isObj).map((row) => ({
|
|
423
455
|
network: String(row.network ?? ""),
|
|
@@ -448,6 +480,16 @@ function parseWalletBreakdown(payload, payment) {
|
|
|
448
480
|
if (!isObj(payload) || typeof payload.wallet !== "string") {
|
|
449
481
|
throw new DescribeUnparseable("wallet-breakdown response is missing its essential shape (wallet)");
|
|
450
482
|
}
|
|
483
|
+
if ("finalScore" in payload || "weightedScore" in payload || "globalScore" in payload) {
|
|
484
|
+
throw new DescribeUnparseable(
|
|
485
|
+
"this payload is already parsed (it carries a camelCase score key, which the wire never does \u2014 `globalScore` means it is the OTHER parser's output): do not parse twice. The payload as served is in `.raw`."
|
|
486
|
+
);
|
|
487
|
+
}
|
|
488
|
+
if ("global_score" in payload && !("final_score" in payload)) {
|
|
489
|
+
throw new DescribeUnparseable(
|
|
490
|
+
"this is the FREE route's payload (`GET /wallets/{wallet}/chains` \u2014 it carries `global_score` and no top-level `final_score`): it goes to parseWalletReputation, not parseWalletBreakdown. Parsing it here would answer nulls for scores the free route never served."
|
|
491
|
+
);
|
|
492
|
+
}
|
|
451
493
|
return {
|
|
452
494
|
wallet: payload.wallet,
|
|
453
495
|
finalScore: optNumber(payload.final_score),
|
|
@@ -548,6 +590,39 @@ function parseHealth(payload) {
|
|
|
548
590
|
}
|
|
549
591
|
|
|
550
592
|
// src/client.ts
|
|
593
|
+
var URL_IN_BODY = /[a-z][a-z0-9+.-]*:\/\/\S+/gi;
|
|
594
|
+
async function serverReason(response) {
|
|
595
|
+
let body;
|
|
596
|
+
try {
|
|
597
|
+
body = await response.json();
|
|
598
|
+
} catch {
|
|
599
|
+
return void 0;
|
|
600
|
+
}
|
|
601
|
+
if (typeof body !== "object" || body === null || Array.isArray(body)) return void 0;
|
|
602
|
+
const record = body;
|
|
603
|
+
const parts = [];
|
|
604
|
+
for (const key of ["error", "code", "message"]) {
|
|
605
|
+
const value = record[key];
|
|
606
|
+
if (value !== null && value !== void 0) parts.push(`${key}=${String(value)}`);
|
|
607
|
+
}
|
|
608
|
+
if (parts.length === 0) return void 0;
|
|
609
|
+
let reason = parts.join(" \xB7 ").replace(URL_IN_BODY, "[url-redacted]");
|
|
610
|
+
if (reason.length > 300) reason = `${reason.slice(0, 300)}\u2026`;
|
|
611
|
+
return reason;
|
|
612
|
+
}
|
|
613
|
+
var KNOWN_CONFIG_KEYS = {
|
|
614
|
+
baseUrl: true,
|
|
615
|
+
timeoutMs: true,
|
|
616
|
+
product: true,
|
|
617
|
+
failOpen: true,
|
|
618
|
+
onFailure: true,
|
|
619
|
+
jitterMs: true,
|
|
620
|
+
payer: true,
|
|
621
|
+
partner: true,
|
|
622
|
+
partnerFallsBackToPaying: true,
|
|
623
|
+
expectedPayTo: true,
|
|
624
|
+
fetchImpl: true
|
|
625
|
+
};
|
|
551
626
|
var DescribeClient = class {
|
|
552
627
|
baseUrl;
|
|
553
628
|
timeoutMs;
|
|
@@ -561,6 +636,14 @@ var DescribeClient = class {
|
|
|
561
636
|
expectedPayTo;
|
|
562
637
|
fetchImpl;
|
|
563
638
|
constructor(config = {}) {
|
|
639
|
+
for (const key of Object.keys(config)) {
|
|
640
|
+
if (!(key in KNOWN_CONFIG_KEYS)) {
|
|
641
|
+
const hint = key === "userAgent" ? " The User-Agent is built for you; name your product with `product` \u2014 it becomes the '(+name)' suffix." : "";
|
|
642
|
+
throw new TypeError(
|
|
643
|
+
`Unknown DescribeClient option '${key}'.${hint} Valid options: ${Object.keys(KNOWN_CONFIG_KEYS).join(", ")}.`
|
|
644
|
+
);
|
|
645
|
+
}
|
|
646
|
+
}
|
|
564
647
|
this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
565
648
|
this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
|
|
566
649
|
this.ua = userAgent(config.product);
|
|
@@ -851,7 +934,9 @@ var DescribeClient = class {
|
|
|
851
934
|
throw new DescribeNotFound(`GET ${path} -> HTTP 404`);
|
|
852
935
|
}
|
|
853
936
|
if (!response.ok) {
|
|
854
|
-
throw new DescribeHTTPError(response.status, `GET ${path} -> HTTP ${response.status}
|
|
937
|
+
throw new DescribeHTTPError(response.status, `GET ${path} -> HTTP ${response.status}`, {
|
|
938
|
+
serverReason: await serverReason(response)
|
|
939
|
+
});
|
|
855
940
|
}
|
|
856
941
|
return this.readJson(response, path);
|
|
857
942
|
}
|
|
@@ -880,7 +965,9 @@ var DescribeClient = class {
|
|
|
880
965
|
throw new DescribeNotFound(`GET ${path} -> HTTP 404`);
|
|
881
966
|
}
|
|
882
967
|
if (first.status !== 402) {
|
|
883
|
-
throw new DescribeHTTPError(first.status, `GET ${path} -> HTTP ${first.status}
|
|
968
|
+
throw new DescribeHTTPError(first.status, `GET ${path} -> HTTP ${first.status}`, {
|
|
969
|
+
serverReason: await serverReason(first)
|
|
970
|
+
});
|
|
884
971
|
}
|
|
885
972
|
const challenge = await this.readChallenge(first, path);
|
|
886
973
|
if (this.partner && !this.partnerFallsBackToPaying) {
|
|
@@ -903,10 +990,17 @@ var DescribeClient = class {
|
|
|
903
990
|
try {
|
|
904
991
|
second = await this.request(path, { "X-PAYMENT": header });
|
|
905
992
|
} catch (error) {
|
|
906
|
-
throw attachPayment(error, {
|
|
993
|
+
throw attachPayment(error, {
|
|
994
|
+
settlement: "unknown",
|
|
995
|
+
receipt: null,
|
|
996
|
+
settlementPending: false,
|
|
997
|
+
reused: null,
|
|
998
|
+
...terms
|
|
999
|
+
});
|
|
907
1000
|
}
|
|
908
1001
|
const receipt = second.headers.get("X-Payment-Receipt");
|
|
909
1002
|
const reused = second.headers.get("X-Payment-Reused");
|
|
1003
|
+
const receiptPending = receipt === SETTLEMENT_PENDING;
|
|
910
1004
|
const attempt = {
|
|
911
1005
|
// A receipt is the settlement transaction hash, put there by the seller:
|
|
912
1006
|
// proof, not inference. Its absence proves nothing — an unhandled 500 is
|
|
@@ -914,12 +1008,19 @@ var DescribeClient = class {
|
|
|
914
1008
|
//
|
|
915
1009
|
// ⚠️ Since 2026-08-30 the header must also LOOK like a settlement id (a
|
|
916
1010
|
// hash, or the `pending` the OpenAPI declares) before it may be called
|
|
917
|
-
// proof. `'settled'` means *
|
|
918
|
-
//
|
|
919
|
-
//
|
|
920
|
-
// honest verdict: ask the chain.
|
|
1011
|
+
// proof. `'settled'` means *the seller stated settlement*: we hold the
|
|
1012
|
+
// hash, or the seller answered the literal `pending` and
|
|
1013
|
+
// `settlementPending` says so. A string that is neither is neither, and
|
|
1014
|
+
// `'unknown'` is the honest verdict: ask the chain.
|
|
1015
|
+
//
|
|
1016
|
+
// ⚠️ Since 2026-08-31 the `pending` sentinel never rides in `receipt` —
|
|
1017
|
+
// Execution Market's INC-2026-08-26: a placeholder stored in the column
|
|
1018
|
+
// meant for the hash gets archived as proof. Here `receipt` is null and
|
|
1019
|
+
// the flag carries the state. Garbage, by contrast, IS kept verbatim on
|
|
1020
|
+
// this failure path: there it is forensic evidence, not a typed field.
|
|
921
1021
|
settlement: receipt !== null && looksLikeSettlementReceipt(receipt) ? "settled" : "unknown",
|
|
922
|
-
receipt,
|
|
1022
|
+
receipt: receiptPending ? null : receipt,
|
|
1023
|
+
settlementPending: receiptPending,
|
|
923
1024
|
reused: reused === null ? null : reused.toLowerCase() === "true",
|
|
924
1025
|
status: second.status,
|
|
925
1026
|
...terms
|
|
@@ -928,7 +1029,10 @@ var DescribeClient = class {
|
|
|
928
1029
|
throw attachPayment(
|
|
929
1030
|
new DescribeHTTPError(
|
|
930
1031
|
second.status,
|
|
931
|
-
`GET ${path} -> HTTP ${second.status} AFTER paying (settlement: ${attempt.settlement}${receipt ? `, receipt ${receipt}` : ""}). Read \`error.payment\` before retrying: the same receipt unlocks only this byte-identical resource
|
|
1032
|
+
`GET ${path} -> HTTP ${second.status} AFTER paying (settlement: ${attempt.settlement}${receipt ? `, receipt ${receipt}` : ""}). Read \`error.payment\` before retrying: the same receipt unlocks only this byte-identical resource.`,
|
|
1033
|
+
// The most expensive door gets the reason too: a 4xx/5xx AFTER money
|
|
1034
|
+
// moved is exactly where "what did they SAY" matters most.
|
|
1035
|
+
{ serverReason: await serverReason(second) }
|
|
932
1036
|
),
|
|
933
1037
|
attempt
|
|
934
1038
|
);
|
|
@@ -943,7 +1047,8 @@ var DescribeClient = class {
|
|
|
943
1047
|
return {
|
|
944
1048
|
body,
|
|
945
1049
|
payment: {
|
|
946
|
-
receipt: receiptOk ? receipt : null,
|
|
1050
|
+
receipt: receiptOk && !receiptPending ? receipt : null,
|
|
1051
|
+
settlementPending: receiptPending,
|
|
947
1052
|
reused: (reused ?? "").toLowerCase() === "true",
|
|
948
1053
|
malformedHashes: receipt !== null && !receiptOk ? ["receipt"] : []
|
|
949
1054
|
},
|