uvd-describe-sdk 0.2.0 → 0.4.1

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.2.0";
9
+ var SDK_VERSION = "0.4.1";
10
10
  var SDK_NAME = "uvd-describe-sdk-ts";
11
11
  function userAgent(product) {
12
12
  const base = `${SDK_NAME}/${SDK_VERSION}`;
@@ -296,7 +296,25 @@ var CAVEAT_CODES = [
296
296
  * nobody can answer for its reputation. The ratings are real on-chain facts
297
297
  * — which is why they are still served — but the subject is not an identity.
298
298
  */
299
- "burn-address"
299
+ "burn-address",
300
+ /**
301
+ * At least one of two or more scored chains rests on fewer than
302
+ * `reading_policy.min_raters` distinct raters. Its weight in the global score
303
+ * is small but never zero, so it still moves the number: read the per-chain
304
+ * composition before the global. Never fires on a single chain — there the
305
+ * weight cancels and `single-rater` / `few-raters` already say it. Wallet
306
+ * scope, and evaluated on the FREE route too (from `chains[]`). Since
307
+ * 2026-09-04; mirrored since 0.4.1.
308
+ */
309
+ "thin-chain",
310
+ /**
311
+ * Some rows of `ratings[]` carry `authorClass: 'facilitator-authored'`: a
312
+ * relayer signed them, so their `client` is not the counterparty and every
313
+ * per-rater count merges them into one voice. AGENT scope only — the one
314
+ * metered answer that lists rows — and it carries no numbers, on purpose: the
315
+ * aggregate by author was cancelled upstream on 2026-08-29. Since 2026-09-14.
316
+ */
317
+ "facilitator-authored"
300
318
  ];
301
319
  var CAVEAT_SCOPE_FREE = "public-data-subset";
302
320
  var CAVEAT_SCOPE_METERED = "full";
@@ -306,6 +324,60 @@ function isKnownCaveatCode(code) {
306
324
  function hasCaveat(subject, code) {
307
325
  return (subject?.caveats ?? []).some((c) => c.code === code);
308
326
  }
327
+ var CaveatsNotComputedError = class _CaveatsNotComputedError extends Error {
328
+ /**
329
+ * What to do INSTEAD, as a frozen literal that interpolates nothing — the
330
+ * redaction rule of `recovery.ts` (invariant 11), without being an entry of
331
+ * that table, because this is not a `kind`. Same text on the class and on
332
+ * every instance.
333
+ *
334
+ * ⚠️ Not byte-identical to the Python twin's, and that is declared rather than
335
+ * hidden: theirs names `wallet_breakdown()`, `payer=`, `partner=` and
336
+ * `fallback_reader`, which are Python spellings. This one names what both SDKs
337
+ * share — the route, and the two ways through it.
338
+ */
339
+ static recovery = "What this free answer did not evaluate is what the metered decomposition sells: `GET /reputation/wallet/{wallet}` evaluates the wallet-scope cuts this error lists \u2014 paid per call with x402, or free for a wallet on describe.net's partner allowlist. If the error lists nothing, the answer declared nothing (a server older than 2026-09-14, or a payload stored before then), and that is not a pass either: the decomposition is still the route that evaluates them.";
340
+ /** Same literal as {@link CaveatsNotComputedError.recovery}, on the instance. */
341
+ recovery = _CaveatsNotComputedError.recovery;
342
+ /** The wallet whose answer was refused, as served. */
343
+ wallet;
344
+ /** A COPY of what the answer declared, or `null` if it declared nothing. */
345
+ notComputed;
346
+ constructor(message, opts) {
347
+ super(message);
348
+ this.name = "CaveatsNotComputedError";
349
+ this.wallet = opts.wallet;
350
+ this.notComputed = opts.notComputed === null ? null : [...opts.notComputed];
351
+ }
352
+ };
353
+ function isWalletReputation(v) {
354
+ if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
355
+ return typeof v.wallet === "string" && "globalScore" in v && !("finalScore" in v) && !("agentId" in v);
356
+ }
357
+ function requireFullCaveats(result) {
358
+ if (!isWalletReputation(result)) {
359
+ throw new TypeError(
360
+ "requireFullCaveats() takes the WalletReputation that wallet() returns. A null means describe.net did NOT answer \u2014 handle that before asking about caveats. A WalletBreakdown or an AgentReputation comes from a metered route, which evaluates its own caveat scope and declares no omissions. A raw payload goes through parseWalletReputation() first."
361
+ );
362
+ }
363
+ const declared = result.caveatsNotComputed;
364
+ if (!Array.isArray(declared)) {
365
+ throw new CaveatsNotComputedError(
366
+ `the answer for ${result.wallet} did not declare which caveat codes it left out (no \`caveats_not_computed\`): a server older than 2026-09-14, or a payload stored before then. Undeclared is not \`[]\`, so this gate does not pass.`,
367
+ { wallet: result.wallet, notComputed: null }
368
+ );
369
+ }
370
+ if (declared.length === 0) return result;
371
+ const codes = declared.map(String);
372
+ throw new CaveatsNotComputedError(
373
+ `the answer for ${result.wallet} declares ${codes.length} caveat code(s) it did not compute: ${codes.join(", ")}. Unverified, not passed.`,
374
+ { wallet: result.wallet, notComputed: codes }
375
+ );
376
+ }
377
+ var AUTHOR_CLASSES = ["facilitator-authored", "rater-authored"];
378
+ function isKnownAuthorClass(value) {
379
+ return AUTHOR_CLASSES.includes(value);
380
+ }
309
381
 
310
382
  // src/parse.ts
311
383
  var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -334,6 +406,15 @@ function parseCaveats(v) {
334
406
  }
335
407
  return out;
336
408
  }
409
+ function parseNotComputed(v) {
410
+ if (!Array.isArray(v)) return null;
411
+ const codes = [];
412
+ for (const item of v) {
413
+ if (typeof item !== "string" || item === "") return null;
414
+ codes.push(item);
415
+ }
416
+ return codes;
417
+ }
337
418
  function parseFacets(v) {
338
419
  if (!isObj(v)) return {};
339
420
  const out = {};
@@ -381,6 +462,30 @@ function parseActivity(v) {
381
462
  if (!isObj(v)) return null;
382
463
  return { firstRatingAt: optString(v.first_rating_at), lastRatingAt: optString(v.last_rating_at) };
383
464
  }
465
+ function parseFreshness(v) {
466
+ if (!isObj(v)) return null;
467
+ const scope = isObj(v.scope) ? v.scope : {};
468
+ return {
469
+ scope: {
470
+ kind: optString(scope.kind),
471
+ direction: optString(scope.direction),
472
+ id: optString(scope.id),
473
+ network: optString(scope.network),
474
+ declaredType: optString(scope.declared_type)
475
+ },
476
+ lastReceivedFeedbackAt: optString(v.last_received_feedback_at),
477
+ lastEligibleRatingAt: optString(v.last_eligible_rating_at),
478
+ datedFeedbackCount: num(v.dated_feedback_count),
479
+ undatedFeedbackCount: num(v.undated_feedback_count),
480
+ timestampCoverage: optString(v.timestamp_coverage),
481
+ eligibleDatedCount: num(v.eligible_dated_count),
482
+ eligibleUndatedCount: num(v.eligible_undated_count),
483
+ eligibleTimestampCoverage: optString(v.eligible_timestamp_coverage),
484
+ refreshedAt: optString(v.refreshed_at),
485
+ indexerCheckedAt: optString(v.indexer_checked_at),
486
+ freshnessVersion: optString(v.freshness_version)
487
+ };
488
+ }
384
489
  function parseSnapshot(v) {
385
490
  if (!isObj(v)) return null;
386
491
  const malformed = [];
@@ -415,6 +520,12 @@ function parseRatings(v) {
415
520
  const malformed = [];
416
521
  return {
417
522
  client: String(r.client ?? ""),
523
+ // Tolerant on purpose, the `isKnownCaveatCode` pattern: a class this SDK
524
+ // has not heard of arrives verbatim, never thrown (one advisory field
525
+ // must not destroy a paid read) and never nulled (dropping it would read
526
+ // as "no class served"). Only a non-string or an empty string is `null`:
527
+ // there is nothing to keep (the Python twin's `_author_class`, same rule).
528
+ authorClass: typeof r.author_class === "string" && r.author_class !== "" ? r.author_class : null,
418
529
  feedbackIndex: num(r.feedback_index),
419
530
  value: num(r.value),
420
531
  valueDecimals: num(r.value_decimals),
@@ -468,6 +579,8 @@ function parseWalletReputation(payload) {
468
579
  chainsWithIdentity: num(payload.chains_with_identity),
469
580
  chainsWithReputation: num(payload.chains_with_reputation),
470
581
  totalReviews: num(payload.total_reviews),
582
+ // `null` when absent or unreadable — NEVER `[]`. See `parseNotComputed`.
583
+ caveatsNotComputed: parseNotComputed(payload.caveats_not_computed),
471
584
  policyVersion: optString(payload.policy_version),
472
585
  caveats: parseCaveats(payload.caveats),
473
586
  caveatScope: CAVEAT_SCOPE_FREE,
@@ -503,6 +616,7 @@ function parseWalletBreakdown(payload, payment) {
503
616
  concentration: parseConcentration(payload.concentration),
504
617
  confidence: parseConfidence(payload.confidence),
505
618
  activity: parseActivity(payload.activity),
619
+ freshness: parseFreshness(payload.freshness),
506
620
  snapshot: parseSnapshot(payload.snapshot),
507
621
  payment,
508
622
  policyVersion: optString(payload.policy_version),
@@ -578,6 +692,8 @@ function parseHealth(payload) {
578
692
  orderingPolicy: String(payload.ordering_policy ?? ""),
579
693
  raterWeightPolicy: String(payload.rater_weight_policy ?? ""),
580
694
  confidencePolicy: String(payload.confidence_policy ?? ""),
695
+ credibilityM: optNumber(payload.credibility_m),
696
+ freshness: parseFreshness(payload.freshness),
581
697
  confidenceThresholds: isObj(payload.confidence_thresholds) ? payload.confidence_thresholds : {},
582
698
  readingPolicy: isObj(payload.reading_policy) ? payload.reading_policy : {},
583
699
  buildSha: optString(payload.build_sha),
@@ -1138,6 +1254,6 @@ function resolveDistinctRaters(wallet) {
1138
1254
  return best;
1139
1255
  }
1140
1256
 
1141
- export { CAVEAT_CODES, CAVEAT_SCOPE_FREE, CAVEAT_SCOPE_METERED, DEFAULT_BASE_URL, DEFAULT_JITTER_MS, DEFAULT_SITE_URL, DEFAULT_TIMEOUT_MS, DescribeClient, DescribeError, DescribeHTTPError, DescribeMalformedHash, DescribeNotFound, DescribePartnerRejected, DescribePartnerUnsigned, DescribePaymentRefused, DescribePaymentRequired, DescribeTimeout, DescribeUnparseable, DescribeUnreachable, PARTNER_CHAIN_ID, PARTNER_KEY_ENV, RECOVERY, SDK_NAME, SDK_VERSION, SETTLEMENT_PENDING, TREASURY_EVM, failOpenCovers, failedAfterPaying, formatScore, hasCaveat, isKnownCaveatCode, looksLikeOnchainId, looksLikeSettlementReceipt, malformedHashReport, parseAgentReputation, parseHealth, parseLeaderboard, parseWalletBreakdown, parseWalletReputation, recoveryFor, resolveDistinctRaters, roundScore, userAgent };
1257
+ export { AUTHOR_CLASSES, CAVEAT_CODES, CAVEAT_SCOPE_FREE, CAVEAT_SCOPE_METERED, CaveatsNotComputedError, DEFAULT_BASE_URL, DEFAULT_JITTER_MS, DEFAULT_SITE_URL, DEFAULT_TIMEOUT_MS, DescribeClient, DescribeError, DescribeHTTPError, DescribeMalformedHash, DescribeNotFound, DescribePartnerRejected, DescribePartnerUnsigned, DescribePaymentRefused, DescribePaymentRequired, DescribeTimeout, DescribeUnparseable, DescribeUnreachable, PARTNER_CHAIN_ID, PARTNER_KEY_ENV, RECOVERY, SDK_NAME, SDK_VERSION, SETTLEMENT_PENDING, TREASURY_EVM, failOpenCovers, failedAfterPaying, formatScore, hasCaveat, isKnownAuthorClass, isKnownCaveatCode, looksLikeOnchainId, looksLikeSettlementReceipt, malformedHashReport, parseAgentReputation, parseHealth, parseLeaderboard, parseWalletBreakdown, parseWalletReputation, recoveryFor, requireFullCaveats, resolveDistinctRaters, roundScore, userAgent };
1142
1258
  //# sourceMappingURL=index.mjs.map
1143
1259
  //# sourceMappingURL=index.mjs.map