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/CHANGELOG.md +116 -0
- package/README.md +80 -4
- package/dist/{client-RAhXcpdY.d.mts → client-0sg4J53x.d.mts} +342 -23
- package/dist/{client-RAhXcpdY.d.ts → client-0sg4J53x.d.ts} +342 -23
- package/dist/{config-uvI_GS-x.d.mts → config-gjJ08BUJ.d.mts} +1 -1
- package/dist/{config-uvI_GS-x.d.ts → config-gjJ08BUJ.d.ts} +1 -1
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +122 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +119 -3
- 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 +2 -1
- package/src/caveats.ts +297 -21
- package/src/config.ts +1 -1
- package/src/index.ts +18 -1
- package/src/parse.ts +83 -0
- package/src/types.ts +138 -1
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.
|
|
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;
|