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/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.1.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
- constructor(status, message) {
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(server ? "http_5xx" : "http_4xx", message, {
139
- // 429 is the one 4xx worth retrying: the 20 rps ceiling is shared with
140
- // every other UVD consumer, so it says "someone else is loud right now",
141
- // not "your request is wrong".
142
- transient: server || status === 429,
143
- // A 4xx is the caller's fault and must NOT vanish into failOpen — except
144
- // 429, which is the shared limit and reads exactly like a brief outage.
145
- serviceFault: server || status === 429,
146
- status
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, { settlement: "unknown", receipt: null, reused: null, ...terms });
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 *we hold the hash*, and a string that is not
918
- // one is not one. The value is still carried in `receipt` — on this path
919
- // it is forensic evidence, not a typed field — and `'unknown'` is the
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
  },