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.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.
|
|
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
|