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/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, ...}`. */