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/src/types.ts
CHANGED
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
* nothing about which happened.
|
|
43
43
|
*/
|
|
44
44
|
|
|
45
|
-
import type { Caveat } from './caveats';
|
|
45
|
+
import type { AuthorClass, Caveat, CaveatCode } from './caveats';
|
|
46
46
|
|
|
47
47
|
/** The eleven indexed chains are strings on the wire. Never an enum here: the index adds chains. */
|
|
48
48
|
export type Network = string;
|
|
@@ -196,6 +196,34 @@ export interface WalletReputation extends Sealed {
|
|
|
196
196
|
chainsWithIdentity: number;
|
|
197
197
|
chainsWithReputation: number;
|
|
198
198
|
totalReviews: number;
|
|
199
|
+
/**
|
|
200
|
+
* The caveat codes that the paid decomposition evaluates and THIS free answer
|
|
201
|
+
* did not — sorted, served since describe.net 2026-09-14
|
|
202
|
+
* (`describenet/caveats.py:525-532`, `not_computed_public`, derived from the
|
|
203
|
+
* same module that builds `caveats`). **Names, never outcomes**: whether any of
|
|
204
|
+
* them fires for this wallet is exactly what stays paid.
|
|
205
|
+
*
|
|
206
|
+
* Seven codes on 2026-09-15, for a wallet with 471 raters and for `0xdead…beef`
|
|
207
|
+
* alike — the declaration depends on what the route evaluates, not on the
|
|
208
|
+
* subject. Read it live; the count is not a constant.
|
|
209
|
+
*
|
|
210
|
+
* 🔴 **Three states, and they stay three:**
|
|
211
|
+
*
|
|
212
|
+
* ```
|
|
213
|
+
* ['few-raters', …] NOT evaluated here — read each one as UNVERIFIED, never as passed
|
|
214
|
+
* [] the answer says it evaluated every wallet-scope cut
|
|
215
|
+
* null nothing readable was declared: a server older than 2026-09-14,
|
|
216
|
+
* a payload stored before then, or a value that is not a list
|
|
217
|
+
* of non-empty strings. NOT `[]` — nothing was promised, and
|
|
218
|
+
* `caveatScope` still says what was evaluated
|
|
219
|
+
* ```
|
|
220
|
+
*
|
|
221
|
+
* The failure this field closes is karma-hello's (2026-08-31): a quality gate
|
|
222
|
+
* built on this route passed every wallet, because `caveats: []` here is the
|
|
223
|
+
* silence of cuts that were never run. Do not gate on it by hand —
|
|
224
|
+
* `requireFullCaveats()` is the gate, and it reads the `null` correctly.
|
|
225
|
+
*/
|
|
226
|
+
caveatsNotComputed: CaveatCode[] | null;
|
|
199
227
|
}
|
|
200
228
|
|
|
201
229
|
// ---------------------------------------------------------------------------
|
|
@@ -229,11 +257,74 @@ export interface SelfRated {
|
|
|
229
257
|
gap: number | null;
|
|
230
258
|
}
|
|
231
259
|
|
|
260
|
+
/**
|
|
261
|
+
* First and last rating by ON-CHAIN time.
|
|
262
|
+
*
|
|
263
|
+
* `lastRatingAt` is the last **eligible** rating — the one that holds up the
|
|
264
|
+
* score being shown. Since describe.net 2026-09-10 it is documented as a
|
|
265
|
+
* compatibility alias of `Freshness.lastEligibleRatingAt` and keeps that exact
|
|
266
|
+
* meaning for the life of v1. Read `WalletBreakdown.freshness` for the question
|
|
267
|
+
* this pair never could answer: *was this subject described recently, whether
|
|
268
|
+
* or not it counts?*
|
|
269
|
+
*/
|
|
232
270
|
export interface Activity {
|
|
233
271
|
firstRatingAt: Timestamp;
|
|
234
272
|
lastRatingAt: Timestamp;
|
|
235
273
|
}
|
|
236
274
|
|
|
275
|
+
/**
|
|
276
|
+
* WHAT the dates are about. A date without a scope is a date that lies.
|
|
277
|
+
*
|
|
278
|
+
* `direction` is the field that matters most: `received` is reputation the
|
|
279
|
+
* subject GOT, `emitted` is the ratings a wallet WROTE
|
|
280
|
+
* (`GET /reputation/rater/{wallet}`). Reading the second as the first turns a
|
|
281
|
+
* busy rater into a much-described subject.
|
|
282
|
+
*/
|
|
283
|
+
export interface FreshnessScope {
|
|
284
|
+
kind: string | null;
|
|
285
|
+
direction: string | null;
|
|
286
|
+
id: string | null;
|
|
287
|
+
network: string | null;
|
|
288
|
+
declaredType: string | null;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* WHEN this subject was last described. Two dates, because two questions.
|
|
293
|
+
*
|
|
294
|
+
* - `lastReceivedFeedbackAt` — the last real NewFeedback in scope, whether or
|
|
295
|
+
* not it feeds the score.
|
|
296
|
+
* - `lastEligibleRatingAt` — the last rating that holds up the number shown.
|
|
297
|
+
*
|
|
298
|
+
* When the most recent rating was revoked the two differ, and **that difference
|
|
299
|
+
* is the information**: there was recent activity and the score does not
|
|
300
|
+
* reflect it.
|
|
301
|
+
*
|
|
302
|
+
* NEITHER is `refreshedAt`, which is when the index recomputed its own view and
|
|
303
|
+
* says nothing about the subject.
|
|
304
|
+
*
|
|
305
|
+
* `timestampCoverage` is `none` | `unknown` | `partial` | `complete` over
|
|
306
|
+
* `dated + undated`. **`none` and `unknown` are different facts**: nothing to
|
|
307
|
+
* date versus dates we do not have yet.
|
|
308
|
+
*
|
|
309
|
+
* NO RELATIVE TEXT, deliberately. The API publishes UTC and nothing else, so
|
|
310
|
+
* "3 days ago" is derived at the edge with the reader's clock — a serialised
|
|
311
|
+
* relative string freezes in the first cache.
|
|
312
|
+
*/
|
|
313
|
+
export interface Freshness {
|
|
314
|
+
scope: FreshnessScope;
|
|
315
|
+
lastReceivedFeedbackAt: Timestamp;
|
|
316
|
+
lastEligibleRatingAt: Timestamp;
|
|
317
|
+
datedFeedbackCount: number;
|
|
318
|
+
undatedFeedbackCount: number;
|
|
319
|
+
timestampCoverage: string | null;
|
|
320
|
+
eligibleDatedCount: number;
|
|
321
|
+
eligibleUndatedCount: number;
|
|
322
|
+
eligibleTimestampCoverage: string | null;
|
|
323
|
+
refreshedAt: Timestamp;
|
|
324
|
+
indexerCheckedAt: Timestamp;
|
|
325
|
+
freshnessVersion: string | null;
|
|
326
|
+
}
|
|
327
|
+
|
|
237
328
|
/** One facet (`tag1`), as declared on-chain. */
|
|
238
329
|
export interface Facet {
|
|
239
330
|
score: number | null;
|
|
@@ -292,6 +383,12 @@ export interface WalletBreakdown extends Sealed {
|
|
|
292
383
|
concentration: Concentration | null;
|
|
293
384
|
confidence: Confidence | null;
|
|
294
385
|
activity: Activity | null;
|
|
386
|
+
/**
|
|
387
|
+
* WHEN, with its scope. Additive: `activity` above keeps its exact meaning.
|
|
388
|
+
* `null` when the server does not publish the block yet — never an empty
|
|
389
|
+
* object, so "not published" and "no dates" stay distinguishable.
|
|
390
|
+
*/
|
|
391
|
+
freshness: Freshness | null;
|
|
295
392
|
snapshot: Snapshot | null;
|
|
296
393
|
/** What was actually paid, if anything was. */
|
|
297
394
|
payment: PaymentEvidence | null;
|
|
@@ -312,6 +409,27 @@ export interface WalletBreakdown extends Sealed {
|
|
|
312
409
|
*/
|
|
313
410
|
export interface Rating {
|
|
314
411
|
client: string;
|
|
412
|
+
/**
|
|
413
|
+
* Who SIGNED this row, as a class — served since describe.net 2026-09-14
|
|
414
|
+
* (`describenet/api.py:962`, `rating_roles.author_class_of`).
|
|
415
|
+
*
|
|
416
|
+
* - `facilitator-authored` — `client` is a known relayer (today the x402
|
|
417
|
+
* facilitator's EVM wallet) that wrote the rating on behalf of the real
|
|
418
|
+
* rater. **`client` is NOT the counterparty**: every such row shares one
|
|
419
|
+
* `client`, so any per-rater count — `concentration.distinctRaters`,
|
|
420
|
+
* `topClientShare` — merges all of them into one voice. Filter on this
|
|
421
|
+
* before reading `client` as "who rated".
|
|
422
|
+
* - `rater-authored` — `client` is not a relayer the index knows about. 🔴 It
|
|
423
|
+
* does NOT prove who signed; it is the absence of a known relayer.
|
|
424
|
+
* - `null` — no class was served (a server older than 2026-09-14, or a stored
|
|
425
|
+
* payload). Unknown, and deliberately NOT defaulted to `rater-authored`:
|
|
426
|
+
* that would assert the one thing the index says it cannot.
|
|
427
|
+
*
|
|
428
|
+
* An unknown string arrives VERBATIM — the union is open, like `CaveatCode`,
|
|
429
|
+
* and `isKnownAuthorClass()` says whether this SDK has heard of it. Per row
|
|
430
|
+
* only: neither the index nor this SDK computes any score or count by class.
|
|
431
|
+
*/
|
|
432
|
+
authorClass: AuthorClass | null;
|
|
315
433
|
feedbackIndex: number;
|
|
316
434
|
value: number;
|
|
317
435
|
valueDecimals: number;
|
|
@@ -459,6 +577,25 @@ export interface IndexHealth {
|
|
|
459
577
|
orderingPolicy: string;
|
|
460
578
|
raterWeightPolicy: string;
|
|
461
579
|
confidencePolicy: string;
|
|
580
|
+
/**
|
|
581
|
+
* The frozen `M` of the per-chain credibility weight, `Z_k = R_k/(R_k+M)`.
|
|
582
|
+
*
|
|
583
|
+
* REQUIRED in the server schema since `credibility-weight-per-chain@1`
|
|
584
|
+
* (2026-09-04) and untyped here until now — `types.schema.test.ts` caught it
|
|
585
|
+
* the moment the snapshot was refreshed. It ships live because the number is
|
|
586
|
+
* frozen and versioned: recomputing a `finalScore` by hand needs THIS M, not
|
|
587
|
+
* a copy of it that went stale.
|
|
588
|
+
*/
|
|
589
|
+
credibilityM: number | null;
|
|
590
|
+
/**
|
|
591
|
+
* WHEN the index as a whole last received a description. The only free,
|
|
592
|
+
* account-less, parameter-less place to read whether describe.net is still
|
|
593
|
+
* taking in descriptions or merely still refreshing its views — the two look
|
|
594
|
+
* identical from the outside, which is the confusion `Freshness` closes.
|
|
595
|
+
*
|
|
596
|
+
* `null` against a server that does not publish it yet.
|
|
597
|
+
*/
|
|
598
|
+
freshness: Freshness | null;
|
|
462
599
|
/** e.g. `{no_ratings: 0, low: 1, medium: 3, high: 6}` — live, never re-typed. */
|
|
463
600
|
confidenceThresholds: Record<string, number>;
|
|
464
601
|
/** e.g. `{min_raters: 3, campaign_per_rater: 20, top_share: 0.5, ...}`. */
|