uvd-describe-sdk 0.1.0 → 0.3.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.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { D as DescribeErrorKind, P as PaymentEvidence, A as AgentReputation, I as IndexHealth, L as LeaderboardRow, W as WalletBreakdown, a as WalletReputation } from './client-s3KrgrCt.js';
2
- export { b as Activity, C as CAVEAT_CODES, c as CAVEAT_SCOPE_FREE, d as CAVEAT_SCOPE_METERED, e as Caveat, f as CaveatCode, g as Concentration, h as Confidence, i as DescribeClient, j as DescribeClientConfig, k as DescribeError, l as DescribeFailure, m as DescribeHTTPError, n as DescribeMalformedHash, o as DescribeNotFound, p as DescribePartnerRejected, q as DescribePartnerUnsigned, r as DescribePaymentRefused, s as DescribePaymentRequired, t as DescribeTimeout, u as DescribeUnparseable, v as DescribeUnreachable, F as Facet, H as HealthChain, K as KnownCaveatCode, N as Network, O as Ownership, w as PartnerSigner, x as PaymentAttempt, R as Rating, S as Sealed, y as SelfRated, z as Snapshot, T as Timestamp, B as WalletChainRow, X as X402Challenge, E as X402Payer, G as failOpenCovers, J as failedAfterPaying, M as hasCaveat, Q as isKnownCaveatCode } from './client-s3KrgrCt.js';
3
- export { D as DEFAULT_BASE_URL, a as DEFAULT_JITTER_MS, b as DEFAULT_SITE_URL, c as DEFAULT_TIMEOUT_MS, P as PARTNER_CHAIN_ID, d as PARTNER_KEY_ENV, S as SDK_NAME, e as SDK_VERSION, T as TREASURY_EVM, u as userAgent } from './config-Y2VK_neB.js';
1
+ import { D as DescribeErrorKind, P as PaymentEvidence, A as AgentReputation, I as IndexHealth, L as LeaderboardRow, W as WalletBreakdown, a as WalletReputation } from './client-BMfgl1zP.js';
2
+ export { b as Activity, C as CAVEAT_CODES, c as CAVEAT_SCOPE_FREE, d as CAVEAT_SCOPE_METERED, e as Caveat, f as CaveatCode, g as Concentration, h as Confidence, i as DescribeClient, j as DescribeClientConfig, k as DescribeError, l as DescribeFailure, m as DescribeHTTPError, n as DescribeMalformedHash, o as DescribeNotFound, p as DescribePartnerRejected, q as DescribePartnerUnsigned, r as DescribePaymentRefused, s as DescribePaymentRequired, t as DescribeTimeout, u as DescribeUnparseable, v as DescribeUnreachable, F as Facet, w as Freshness, x as FreshnessScope, H as HealthChain, K as KnownCaveatCode, N as Network, O as Ownership, y as PartnerSigner, z as PaymentAttempt, R as Rating, S as Sealed, B as SelfRated, E as Snapshot, T as Timestamp, G as WalletChainRow, X as X402Challenge, J as X402Payer, M as failOpenCovers, Q as failedAfterPaying, U as hasCaveat, V as isKnownCaveatCode } from './client-BMfgl1zP.js';
3
+ export { D as DEFAULT_BASE_URL, a as DEFAULT_JITTER_MS, b as DEFAULT_SITE_URL, c as DEFAULT_TIMEOUT_MS, P as PARTNER_CHAIN_ID, d as PARTNER_KEY_ENV, S as SDK_NAME, e as SDK_VERSION, T as TREASURY_EVM, u as userAgent } from './config-DzzhWFYr.js';
4
4
 
5
5
  /**
6
6
  * What to do INSTEAD — the sentence `transient` cannot say.
@@ -181,6 +181,15 @@ declare function recoveryFor(kind: DescribeErrorKind, status?: number): string |
181
181
  *
182
182
  * A non-finite input (a `NaN` from a malformed payload) is also `null`: a
183
183
  * number we cannot name is not a number we may put describe.net's name on.
184
+ *
185
+ * 🔴 **This returns a STRING, and the homonym trap is measured** (mesh,
186
+ * meshrelay migration review 2026-08-31; spec in
187
+ * `meshrelayserv/describenet.js@04f2ecf`): their pre-SDK code had a local
188
+ * `formatScore` that returned a NUMBER, so swapping the import compiles clean,
189
+ * every call site keeps working — and every score that flows into a JSON
190
+ * payload silently turns from `83` into `"83"`, one serialization away from
191
+ * whoever consumes it. If a number is what you need, {@link roundScore} is the
192
+ * drop-in; this one is for the pixel.
184
193
  */
185
194
  declare function formatScore(value: number | null | undefined): string | null;
186
195
  /**
@@ -192,6 +201,14 @@ declare function formatScore(value: number | null | undefined): string | null;
192
201
  * places" (`describenet.js:204-208`). If you do that, use this — and be aware
193
202
  * you have made the value lossy on purpose. Everything else should carry the
194
203
  * full-precision number and call `formatScore` at the pixel.
204
+ *
205
+ * 🔴 **This returns a NUMBER; {@link formatScore} returns a STRING** — and a
206
+ * migrating consumer whose old helper was called `formatScore` but returned a
207
+ * number wants THIS one, not the name-alike. mesh measured the collision
208
+ * (2026-08-31, spec in `meshrelayserv/describenet.js@04f2ecf`): importing the
209
+ * homonym type-checks wherever the value only ever meets `JSON.stringify` or a
210
+ * template literal, and the symptom is numbers arriving as strings downstream,
211
+ * with nothing red anywhere near the cause.
195
212
  */
196
213
  declare function roundScore(value: number | null | undefined): number | null;
197
214
 
@@ -468,6 +485,32 @@ declare function malformedHashReport(result: {
468
485
  * absence of a value and a value that is nonsense are different facts, and
469
486
  * collapsing them is the failure this file exists to prevent. See
470
487
  * `hashes.ts`, and `client.ts` for how the fact reaches the caller.
488
+ * 5. **A payload from the wrong door fails LOUD — in BOTH directions.** Added
489
+ * 2026-08-31 from mesh's migration review (meshrelay; spec in
490
+ * `meshrelayserv/describenet.js@04f2ecf`), which found rule 3 broken by its
491
+ * own parsers: `wallet` is a string in every shape this API serves AND in
492
+ * every shape this SDK returns, so the essential-shape check alone let
493
+ * wrong inputs "succeed" into exactly the object-full-of-nulls rule 3
494
+ * declares impossible — the FREE route's body fed to `parseWalletBreakdown`
495
+ * (`finalScore: null`, `weightedScore: null`, `perChain: {}`, reading as
496
+ * "paid and got nothing"), and a result that was ALREADY parsed fed back in
497
+ * (every snake_case lookup misses, all nulls, in silence). The guards are
498
+ * key-based — a marker key by PRESENCE, never by value — and each one names
499
+ * the door the caller actually wanted: `global_score` without `final_score`
500
+ * is the free route's body and belongs to `parseWalletReputation`;
501
+ * `final_score` without `global_score` is the METERED route's body and
502
+ * belongs to `parseWalletBreakdown`; a camelCase key (`globalScore`,
503
+ * `finalScore`, `weightedScore`) is OUR output, and output does not go back
504
+ * in — `client.wallet()` already parses, and the wire payload survives in
505
+ * `.raw` for whoever needs to re-read it.
506
+ * ⚠️ CORRECTED 2026-08-31, same day, by the symmetry review against the
507
+ * Python twin: as first written this rule guarded only ONE wrong door
508
+ * (free body → `parseWalletBreakdown`) and the code matched the text — the
509
+ * metered body fed to `parseWalletReputation` still "succeeded" into
510
+ * `globalScore: null`, `chains: []`, in silence, while both trees claimed
511
+ * mirror. The twin guards both directions
512
+ * (`models.py::parse_wallet_reputation`); now so does this file, and
513
+ * `parse.test.ts` mounts the bad state for each.
471
514
  */
472
515
 
473
516
  /** `GET /wallets/{wallet}/chains`. Requires `wallet` — everything else may be absent. */
package/dist/index.js CHANGED
@@ -8,7 +8,7 @@ var DEFAULT_JITTER_MS = 400;
8
8
  var TREASURY_EVM = "0xe4dc963c56979E0260fc146b87eE24F18220e545";
9
9
  var PARTNER_CHAIN_ID = 8453;
10
10
  var PARTNER_KEY_ENV = "DESCRIBE_PARTNER_PRIVATE_KEY";
11
- var SDK_VERSION = "0.1.0";
11
+ var SDK_VERSION = "0.3.0";
12
12
  var SDK_NAME = "uvd-describe-sdk-ts";
13
13
  function userAgent(product) {
14
14
  const base = `${SDK_NAME}/${SDK_VERSION}`;
@@ -135,19 +135,41 @@ var DescribeNotFound = class extends DescribeError {
135
135
  }
136
136
  };
137
137
  var DescribeHTTPError = class extends DescribeError {
138
- constructor(status, message) {
138
+ /**
139
+ * What the body SAID, not just the number it said it with — Execution
140
+ * Market's contribution, ported 2026-08-31 from the Python twin
141
+ * (`errors.py::DescribeHTTPError.server_reason` — same field, same
142
+ * `' — the server says: '` text): this class's recovery has promised since
143
+ * day one that *"the body names the field"*, and until today the exception
144
+ * threw that body away and carried the bare status. Whoever caught a 422
145
+ * had to re-request to learn which field was wrong.
146
+ *
147
+ * It arrives ALREADY redacted and truncated by `client.ts::serverReason` —
148
+ * the body is server-written text and a 5xx can echo an upstream URL with
149
+ * an API key in its path — and it is appended to the MESSAGE, never to
150
+ * `recovery`, which stays the frozen literal `recovery.test.ts` pins. The
151
+ * parameter is third and optional so every existing call keeps meaning what
152
+ * it meant — additive, like the twin's keyword-only argument.
153
+ */
154
+ serverReason;
155
+ constructor(status, message, opts = {}) {
139
156
  const server = status >= 500;
140
- super(server ? "http_5xx" : "http_4xx", message, {
141
- // 429 is the one 4xx worth retrying: the 20 rps ceiling is shared with
142
- // every other UVD consumer, so it says "someone else is loud right now",
143
- // not "your request is wrong".
144
- transient: server || status === 429,
145
- // A 4xx is the caller's fault and must NOT vanish into failOpen — except
146
- // 429, which is the shared limit and reads exactly like a brief outage.
147
- serviceFault: server || status === 429,
148
- status
149
- });
157
+ super(
158
+ server ? "http_5xx" : "http_4xx",
159
+ opts.serverReason ? `${message} \u2014 the server says: ${opts.serverReason}` : message,
160
+ {
161
+ // 429 is the one 4xx worth retrying: the 20 rps ceiling is shared with
162
+ // every other UVD consumer, so it says "someone else is loud right now",
163
+ // not "your request is wrong".
164
+ transient: server || status === 429,
165
+ // A 4xx is the caller's fault and must NOT vanish into failOpen — except
166
+ // 429, which is the shared limit and reads exactly like a brief outage.
167
+ serviceFault: server || status === 429,
168
+ status
169
+ }
170
+ );
150
171
  this.name = "DescribeHTTPError";
172
+ this.serverReason = opts.serverReason;
151
173
  }
152
174
  };
153
175
  var DescribePaymentRequired = class extends DescribeError {
@@ -361,6 +383,30 @@ function parseActivity(v) {
361
383
  if (!isObj(v)) return null;
362
384
  return { firstRatingAt: optString(v.first_rating_at), lastRatingAt: optString(v.last_rating_at) };
363
385
  }
386
+ function parseFreshness(v) {
387
+ if (!isObj(v)) return null;
388
+ const scope = isObj(v.scope) ? v.scope : {};
389
+ return {
390
+ scope: {
391
+ kind: optString(scope.kind),
392
+ direction: optString(scope.direction),
393
+ id: optString(scope.id),
394
+ network: optString(scope.network),
395
+ declaredType: optString(scope.declared_type)
396
+ },
397
+ lastReceivedFeedbackAt: optString(v.last_received_feedback_at),
398
+ lastEligibleRatingAt: optString(v.last_eligible_rating_at),
399
+ datedFeedbackCount: num(v.dated_feedback_count),
400
+ undatedFeedbackCount: num(v.undated_feedback_count),
401
+ timestampCoverage: optString(v.timestamp_coverage),
402
+ eligibleDatedCount: num(v.eligible_dated_count),
403
+ eligibleUndatedCount: num(v.eligible_undated_count),
404
+ eligibleTimestampCoverage: optString(v.eligible_timestamp_coverage),
405
+ refreshedAt: optString(v.refreshed_at),
406
+ indexerCheckedAt: optString(v.indexer_checked_at),
407
+ freshnessVersion: optString(v.freshness_version)
408
+ };
409
+ }
364
410
  function parseSnapshot(v) {
365
411
  if (!isObj(v)) return null;
366
412
  const malformed = [];
@@ -420,6 +466,16 @@ function parseWalletReputation(payload) {
420
466
  if (!isObj(payload) || typeof payload.wallet !== "string") {
421
467
  throw new DescribeUnparseable("wallet-chains response is missing its essential shape (wallet)");
422
468
  }
469
+ if ("globalScore" in payload || "finalScore" in payload || "weightedScore" in payload) {
470
+ throw new DescribeUnparseable(
471
+ "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`."
472
+ );
473
+ }
474
+ if ("final_score" in payload && !("global_score" in payload)) {
475
+ throw new DescribeUnparseable(
476
+ "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."
477
+ );
478
+ }
423
479
  const rows = Array.isArray(payload.chains) ? payload.chains : [];
424
480
  const chains = rows.filter(isObj).map((row) => ({
425
481
  network: String(row.network ?? ""),
@@ -450,6 +506,16 @@ function parseWalletBreakdown(payload, payment) {
450
506
  if (!isObj(payload) || typeof payload.wallet !== "string") {
451
507
  throw new DescribeUnparseable("wallet-breakdown response is missing its essential shape (wallet)");
452
508
  }
509
+ if ("finalScore" in payload || "weightedScore" in payload || "globalScore" in payload) {
510
+ throw new DescribeUnparseable(
511
+ "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`."
512
+ );
513
+ }
514
+ if ("global_score" in payload && !("final_score" in payload)) {
515
+ throw new DescribeUnparseable(
516
+ "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."
517
+ );
518
+ }
453
519
  return {
454
520
  wallet: payload.wallet,
455
521
  finalScore: optNumber(payload.final_score),
@@ -463,6 +529,7 @@ function parseWalletBreakdown(payload, payment) {
463
529
  concentration: parseConcentration(payload.concentration),
464
530
  confidence: parseConfidence(payload.confidence),
465
531
  activity: parseActivity(payload.activity),
532
+ freshness: parseFreshness(payload.freshness),
466
533
  snapshot: parseSnapshot(payload.snapshot),
467
534
  payment,
468
535
  policyVersion: optString(payload.policy_version),
@@ -538,6 +605,8 @@ function parseHealth(payload) {
538
605
  orderingPolicy: String(payload.ordering_policy ?? ""),
539
606
  raterWeightPolicy: String(payload.rater_weight_policy ?? ""),
540
607
  confidencePolicy: String(payload.confidence_policy ?? ""),
608
+ credibilityM: optNumber(payload.credibility_m),
609
+ freshness: parseFreshness(payload.freshness),
541
610
  confidenceThresholds: isObj(payload.confidence_thresholds) ? payload.confidence_thresholds : {},
542
611
  readingPolicy: isObj(payload.reading_policy) ? payload.reading_policy : {},
543
612
  buildSha: optString(payload.build_sha),
@@ -550,6 +619,39 @@ function parseHealth(payload) {
550
619
  }
551
620
 
552
621
  // src/client.ts
622
+ var URL_IN_BODY = /[a-z][a-z0-9+.-]*:\/\/\S+/gi;
623
+ async function serverReason(response) {
624
+ let body;
625
+ try {
626
+ body = await response.json();
627
+ } catch {
628
+ return void 0;
629
+ }
630
+ if (typeof body !== "object" || body === null || Array.isArray(body)) return void 0;
631
+ const record = body;
632
+ const parts = [];
633
+ for (const key of ["error", "code", "message"]) {
634
+ const value = record[key];
635
+ if (value !== null && value !== void 0) parts.push(`${key}=${String(value)}`);
636
+ }
637
+ if (parts.length === 0) return void 0;
638
+ let reason = parts.join(" \xB7 ").replace(URL_IN_BODY, "[url-redacted]");
639
+ if (reason.length > 300) reason = `${reason.slice(0, 300)}\u2026`;
640
+ return reason;
641
+ }
642
+ var KNOWN_CONFIG_KEYS = {
643
+ baseUrl: true,
644
+ timeoutMs: true,
645
+ product: true,
646
+ failOpen: true,
647
+ onFailure: true,
648
+ jitterMs: true,
649
+ payer: true,
650
+ partner: true,
651
+ partnerFallsBackToPaying: true,
652
+ expectedPayTo: true,
653
+ fetchImpl: true
654
+ };
553
655
  var DescribeClient = class {
554
656
  baseUrl;
555
657
  timeoutMs;
@@ -563,6 +665,14 @@ var DescribeClient = class {
563
665
  expectedPayTo;
564
666
  fetchImpl;
565
667
  constructor(config = {}) {
668
+ for (const key of Object.keys(config)) {
669
+ if (!(key in KNOWN_CONFIG_KEYS)) {
670
+ const hint = key === "userAgent" ? " The User-Agent is built for you; name your product with `product` \u2014 it becomes the '(+name)' suffix." : "";
671
+ throw new TypeError(
672
+ `Unknown DescribeClient option '${key}'.${hint} Valid options: ${Object.keys(KNOWN_CONFIG_KEYS).join(", ")}.`
673
+ );
674
+ }
675
+ }
566
676
  this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
567
677
  this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
568
678
  this.ua = userAgent(config.product);
@@ -853,7 +963,9 @@ var DescribeClient = class {
853
963
  throw new DescribeNotFound(`GET ${path} -> HTTP 404`);
854
964
  }
855
965
  if (!response.ok) {
856
- throw new DescribeHTTPError(response.status, `GET ${path} -> HTTP ${response.status}`);
966
+ throw new DescribeHTTPError(response.status, `GET ${path} -> HTTP ${response.status}`, {
967
+ serverReason: await serverReason(response)
968
+ });
857
969
  }
858
970
  return this.readJson(response, path);
859
971
  }
@@ -882,7 +994,9 @@ var DescribeClient = class {
882
994
  throw new DescribeNotFound(`GET ${path} -> HTTP 404`);
883
995
  }
884
996
  if (first.status !== 402) {
885
- throw new DescribeHTTPError(first.status, `GET ${path} -> HTTP ${first.status}`);
997
+ throw new DescribeHTTPError(first.status, `GET ${path} -> HTTP ${first.status}`, {
998
+ serverReason: await serverReason(first)
999
+ });
886
1000
  }
887
1001
  const challenge = await this.readChallenge(first, path);
888
1002
  if (this.partner && !this.partnerFallsBackToPaying) {
@@ -905,10 +1019,17 @@ var DescribeClient = class {
905
1019
  try {
906
1020
  second = await this.request(path, { "X-PAYMENT": header });
907
1021
  } catch (error) {
908
- throw attachPayment(error, { settlement: "unknown", receipt: null, reused: null, ...terms });
1022
+ throw attachPayment(error, {
1023
+ settlement: "unknown",
1024
+ receipt: null,
1025
+ settlementPending: false,
1026
+ reused: null,
1027
+ ...terms
1028
+ });
909
1029
  }
910
1030
  const receipt = second.headers.get("X-Payment-Receipt");
911
1031
  const reused = second.headers.get("X-Payment-Reused");
1032
+ const receiptPending = receipt === SETTLEMENT_PENDING;
912
1033
  const attempt = {
913
1034
  // A receipt is the settlement transaction hash, put there by the seller:
914
1035
  // proof, not inference. Its absence proves nothing — an unhandled 500 is
@@ -916,12 +1037,19 @@ var DescribeClient = class {
916
1037
  //
917
1038
  // ⚠️ Since 2026-08-30 the header must also LOOK like a settlement id (a
918
1039
  // hash, or the `pending` the OpenAPI declares) before it may be called
919
- // proof. `'settled'` means *we hold the hash*, and a string that is not
920
- // one is not one. The value is still carried in `receipt` — on this path
921
- // it is forensic evidence, not a typed field — and `'unknown'` is the
922
- // honest verdict: ask the chain.
1040
+ // proof. `'settled'` means *the seller stated settlement*: we hold the
1041
+ // hash, or the seller answered the literal `pending` and
1042
+ // `settlementPending` says so. A string that is neither is neither, and
1043
+ // `'unknown'` is the honest verdict: ask the chain.
1044
+ //
1045
+ // ⚠️ Since 2026-08-31 the `pending` sentinel never rides in `receipt` —
1046
+ // Execution Market's INC-2026-08-26: a placeholder stored in the column
1047
+ // meant for the hash gets archived as proof. Here `receipt` is null and
1048
+ // the flag carries the state. Garbage, by contrast, IS kept verbatim on
1049
+ // this failure path: there it is forensic evidence, not a typed field.
923
1050
  settlement: receipt !== null && looksLikeSettlementReceipt(receipt) ? "settled" : "unknown",
924
- receipt,
1051
+ receipt: receiptPending ? null : receipt,
1052
+ settlementPending: receiptPending,
925
1053
  reused: reused === null ? null : reused.toLowerCase() === "true",
926
1054
  status: second.status,
927
1055
  ...terms
@@ -930,7 +1058,10 @@ var DescribeClient = class {
930
1058
  throw attachPayment(
931
1059
  new DescribeHTTPError(
932
1060
  second.status,
933
- `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.`
1061
+ `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.`,
1062
+ // The most expensive door gets the reason too: a 4xx/5xx AFTER money
1063
+ // moved is exactly where "what did they SAY" matters most.
1064
+ { serverReason: await serverReason(second) }
934
1065
  ),
935
1066
  attempt
936
1067
  );
@@ -945,7 +1076,8 @@ var DescribeClient = class {
945
1076
  return {
946
1077
  body,
947
1078
  payment: {
948
- receipt: receiptOk ? receipt : null,
1079
+ receipt: receiptOk && !receiptPending ? receipt : null,
1080
+ settlementPending: receiptPending,
949
1081
  reused: (reused ?? "").toLowerCase() === "true",
950
1082
  malformedHashes: receipt !== null && !receiptOk ? ["receipt"] : []
951
1083
  },