uvd-describe-sdk 0.3.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-BMfgl1zP.d.mts → client-0sg4J53x.d.mts} +256 -23
- package/dist/{client-BMfgl1zP.d.ts → client-0sg4J53x.d.ts} +256 -23
- package/dist/{config-DzzhWFYr.d.mts → config-gjJ08BUJ.d.mts} +1 -1
- package/dist/{config-DzzhWFYr.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 +95 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +92 -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 +16 -1
- package/src/parse.ts +42 -0
- package/src/types.ts +50 -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 = {};
|
|
@@ -439,6 +520,12 @@ function parseRatings(v) {
|
|
|
439
520
|
const malformed = [];
|
|
440
521
|
return {
|
|
441
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,
|
|
442
529
|
feedbackIndex: num(r.feedback_index),
|
|
443
530
|
value: num(r.value),
|
|
444
531
|
valueDecimals: num(r.value_decimals),
|
|
@@ -492,6 +579,8 @@ function parseWalletReputation(payload) {
|
|
|
492
579
|
chainsWithIdentity: num(payload.chains_with_identity),
|
|
493
580
|
chainsWithReputation: num(payload.chains_with_reputation),
|
|
494
581
|
totalReviews: num(payload.total_reviews),
|
|
582
|
+
// `null` when absent or unreadable — NEVER `[]`. See `parseNotComputed`.
|
|
583
|
+
caveatsNotComputed: parseNotComputed(payload.caveats_not_computed),
|
|
495
584
|
policyVersion: optString(payload.policy_version),
|
|
496
585
|
caveats: parseCaveats(payload.caveats),
|
|
497
586
|
caveatScope: CAVEAT_SCOPE_FREE,
|
|
@@ -1165,6 +1254,6 @@ function resolveDistinctRaters(wallet) {
|
|
|
1165
1254
|
return best;
|
|
1166
1255
|
}
|
|
1167
1256
|
|
|
1168
|
-
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 };
|
|
1169
1258
|
//# sourceMappingURL=index.mjs.map
|
|
1170
1259
|
//# sourceMappingURL=index.mjs.map
|