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.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.2.0";
11
+ var SDK_VERSION = "0.4.1";
12
12
  var SDK_NAME = "uvd-describe-sdk-ts";
13
13
  function userAgent(product) {
14
14
  const base = `${SDK_NAME}/${SDK_VERSION}`;
@@ -298,7 +298,25 @@ var CAVEAT_CODES = [
298
298
  * nobody can answer for its reputation. The ratings are real on-chain facts
299
299
  * — which is why they are still served — but the subject is not an identity.
300
300
  */
301
- "burn-address"
301
+ "burn-address",
302
+ /**
303
+ * At least one of two or more scored chains rests on fewer than
304
+ * `reading_policy.min_raters` distinct raters. Its weight in the global score
305
+ * is small but never zero, so it still moves the number: read the per-chain
306
+ * composition before the global. Never fires on a single chain — there the
307
+ * weight cancels and `single-rater` / `few-raters` already say it. Wallet
308
+ * scope, and evaluated on the FREE route too (from `chains[]`). Since
309
+ * 2026-09-04; mirrored since 0.4.1.
310
+ */
311
+ "thin-chain",
312
+ /**
313
+ * Some rows of `ratings[]` carry `authorClass: 'facilitator-authored'`: a
314
+ * relayer signed them, so their `client` is not the counterparty and every
315
+ * per-rater count merges them into one voice. AGENT scope only — the one
316
+ * metered answer that lists rows — and it carries no numbers, on purpose: the
317
+ * aggregate by author was cancelled upstream on 2026-08-29. Since 2026-09-14.
318
+ */
319
+ "facilitator-authored"
302
320
  ];
303
321
  var CAVEAT_SCOPE_FREE = "public-data-subset";
304
322
  var CAVEAT_SCOPE_METERED = "full";
@@ -308,6 +326,60 @@ function isKnownCaveatCode(code) {
308
326
  function hasCaveat(subject, code) {
309
327
  return (subject?.caveats ?? []).some((c) => c.code === code);
310
328
  }
329
+ var CaveatsNotComputedError = class _CaveatsNotComputedError extends Error {
330
+ /**
331
+ * What to do INSTEAD, as a frozen literal that interpolates nothing — the
332
+ * redaction rule of `recovery.ts` (invariant 11), without being an entry of
333
+ * that table, because this is not a `kind`. Same text on the class and on
334
+ * every instance.
335
+ *
336
+ * ⚠️ Not byte-identical to the Python twin's, and that is declared rather than
337
+ * hidden: theirs names `wallet_breakdown()`, `payer=`, `partner=` and
338
+ * `fallback_reader`, which are Python spellings. This one names what both SDKs
339
+ * share — the route, and the two ways through it.
340
+ */
341
+ 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.";
342
+ /** Same literal as {@link CaveatsNotComputedError.recovery}, on the instance. */
343
+ recovery = _CaveatsNotComputedError.recovery;
344
+ /** The wallet whose answer was refused, as served. */
345
+ wallet;
346
+ /** A COPY of what the answer declared, or `null` if it declared nothing. */
347
+ notComputed;
348
+ constructor(message, opts) {
349
+ super(message);
350
+ this.name = "CaveatsNotComputedError";
351
+ this.wallet = opts.wallet;
352
+ this.notComputed = opts.notComputed === null ? null : [...opts.notComputed];
353
+ }
354
+ };
355
+ function isWalletReputation(v) {
356
+ if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
357
+ return typeof v.wallet === "string" && "globalScore" in v && !("finalScore" in v) && !("agentId" in v);
358
+ }
359
+ function requireFullCaveats(result) {
360
+ if (!isWalletReputation(result)) {
361
+ throw new TypeError(
362
+ "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."
363
+ );
364
+ }
365
+ const declared = result.caveatsNotComputed;
366
+ if (!Array.isArray(declared)) {
367
+ throw new CaveatsNotComputedError(
368
+ `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.`,
369
+ { wallet: result.wallet, notComputed: null }
370
+ );
371
+ }
372
+ if (declared.length === 0) return result;
373
+ const codes = declared.map(String);
374
+ throw new CaveatsNotComputedError(
375
+ `the answer for ${result.wallet} declares ${codes.length} caveat code(s) it did not compute: ${codes.join(", ")}. Unverified, not passed.`,
376
+ { wallet: result.wallet, notComputed: codes }
377
+ );
378
+ }
379
+ var AUTHOR_CLASSES = ["facilitator-authored", "rater-authored"];
380
+ function isKnownAuthorClass(value) {
381
+ return AUTHOR_CLASSES.includes(value);
382
+ }
311
383
 
312
384
  // src/parse.ts
313
385
  var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -336,6 +408,15 @@ function parseCaveats(v) {
336
408
  }
337
409
  return out;
338
410
  }
411
+ function parseNotComputed(v) {
412
+ if (!Array.isArray(v)) return null;
413
+ const codes = [];
414
+ for (const item of v) {
415
+ if (typeof item !== "string" || item === "") return null;
416
+ codes.push(item);
417
+ }
418
+ return codes;
419
+ }
339
420
  function parseFacets(v) {
340
421
  if (!isObj(v)) return {};
341
422
  const out = {};
@@ -383,6 +464,30 @@ function parseActivity(v) {
383
464
  if (!isObj(v)) return null;
384
465
  return { firstRatingAt: optString(v.first_rating_at), lastRatingAt: optString(v.last_rating_at) };
385
466
  }
467
+ function parseFreshness(v) {
468
+ if (!isObj(v)) return null;
469
+ const scope = isObj(v.scope) ? v.scope : {};
470
+ return {
471
+ scope: {
472
+ kind: optString(scope.kind),
473
+ direction: optString(scope.direction),
474
+ id: optString(scope.id),
475
+ network: optString(scope.network),
476
+ declaredType: optString(scope.declared_type)
477
+ },
478
+ lastReceivedFeedbackAt: optString(v.last_received_feedback_at),
479
+ lastEligibleRatingAt: optString(v.last_eligible_rating_at),
480
+ datedFeedbackCount: num(v.dated_feedback_count),
481
+ undatedFeedbackCount: num(v.undated_feedback_count),
482
+ timestampCoverage: optString(v.timestamp_coverage),
483
+ eligibleDatedCount: num(v.eligible_dated_count),
484
+ eligibleUndatedCount: num(v.eligible_undated_count),
485
+ eligibleTimestampCoverage: optString(v.eligible_timestamp_coverage),
486
+ refreshedAt: optString(v.refreshed_at),
487
+ indexerCheckedAt: optString(v.indexer_checked_at),
488
+ freshnessVersion: optString(v.freshness_version)
489
+ };
490
+ }
386
491
  function parseSnapshot(v) {
387
492
  if (!isObj(v)) return null;
388
493
  const malformed = [];
@@ -417,6 +522,12 @@ function parseRatings(v) {
417
522
  const malformed = [];
418
523
  return {
419
524
  client: String(r.client ?? ""),
525
+ // Tolerant on purpose, the `isKnownCaveatCode` pattern: a class this SDK
526
+ // has not heard of arrives verbatim, never thrown (one advisory field
527
+ // must not destroy a paid read) and never nulled (dropping it would read
528
+ // as "no class served"). Only a non-string or an empty string is `null`:
529
+ // there is nothing to keep (the Python twin's `_author_class`, same rule).
530
+ authorClass: typeof r.author_class === "string" && r.author_class !== "" ? r.author_class : null,
420
531
  feedbackIndex: num(r.feedback_index),
421
532
  value: num(r.value),
422
533
  valueDecimals: num(r.value_decimals),
@@ -470,6 +581,8 @@ function parseWalletReputation(payload) {
470
581
  chainsWithIdentity: num(payload.chains_with_identity),
471
582
  chainsWithReputation: num(payload.chains_with_reputation),
472
583
  totalReviews: num(payload.total_reviews),
584
+ // `null` when absent or unreadable — NEVER `[]`. See `parseNotComputed`.
585
+ caveatsNotComputed: parseNotComputed(payload.caveats_not_computed),
473
586
  policyVersion: optString(payload.policy_version),
474
587
  caveats: parseCaveats(payload.caveats),
475
588
  caveatScope: CAVEAT_SCOPE_FREE,
@@ -505,6 +618,7 @@ function parseWalletBreakdown(payload, payment) {
505
618
  concentration: parseConcentration(payload.concentration),
506
619
  confidence: parseConfidence(payload.confidence),
507
620
  activity: parseActivity(payload.activity),
621
+ freshness: parseFreshness(payload.freshness),
508
622
  snapshot: parseSnapshot(payload.snapshot),
509
623
  payment,
510
624
  policyVersion: optString(payload.policy_version),
@@ -580,6 +694,8 @@ function parseHealth(payload) {
580
694
  orderingPolicy: String(payload.ordering_policy ?? ""),
581
695
  raterWeightPolicy: String(payload.rater_weight_policy ?? ""),
582
696
  confidencePolicy: String(payload.confidence_policy ?? ""),
697
+ credibilityM: optNumber(payload.credibility_m),
698
+ freshness: parseFreshness(payload.freshness),
583
699
  confidenceThresholds: isObj(payload.confidence_thresholds) ? payload.confidence_thresholds : {},
584
700
  readingPolicy: isObj(payload.reading_policy) ? payload.reading_policy : {},
585
701
  buildSha: optString(payload.build_sha),
@@ -1140,9 +1256,11 @@ function resolveDistinctRaters(wallet) {
1140
1256
  return best;
1141
1257
  }
1142
1258
 
1259
+ exports.AUTHOR_CLASSES = AUTHOR_CLASSES;
1143
1260
  exports.CAVEAT_CODES = CAVEAT_CODES;
1144
1261
  exports.CAVEAT_SCOPE_FREE = CAVEAT_SCOPE_FREE;
1145
1262
  exports.CAVEAT_SCOPE_METERED = CAVEAT_SCOPE_METERED;
1263
+ exports.CaveatsNotComputedError = CaveatsNotComputedError;
1146
1264
  exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
1147
1265
  exports.DEFAULT_JITTER_MS = DEFAULT_JITTER_MS;
1148
1266
  exports.DEFAULT_SITE_URL = DEFAULT_SITE_URL;
@@ -1170,6 +1288,7 @@ exports.failOpenCovers = failOpenCovers;
1170
1288
  exports.failedAfterPaying = failedAfterPaying;
1171
1289
  exports.formatScore = formatScore;
1172
1290
  exports.hasCaveat = hasCaveat;
1291
+ exports.isKnownAuthorClass = isKnownAuthorClass;
1173
1292
  exports.isKnownCaveatCode = isKnownCaveatCode;
1174
1293
  exports.looksLikeOnchainId = looksLikeOnchainId;
1175
1294
  exports.looksLikeSettlementReceipt = looksLikeSettlementReceipt;
@@ -1180,6 +1299,7 @@ exports.parseLeaderboard = parseLeaderboard;
1180
1299
  exports.parseWalletBreakdown = parseWalletBreakdown;
1181
1300
  exports.parseWalletReputation = parseWalletReputation;
1182
1301
  exports.recoveryFor = recoveryFor;
1302
+ exports.requireFullCaveats = requireFullCaveats;
1183
1303
  exports.resolveDistinctRaters = resolveDistinctRaters;
1184
1304
  exports.roundScore = roundScore;
1185
1305
  exports.userAgent = userAgent;