uvd-describe-sdk 0.1.0 → 0.3.0

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/README.md CHANGED
@@ -149,6 +149,51 @@ pixel.
149
149
 
150
150
  ---
151
151
 
152
+ ## Trampas de migración (medidas por los equipos)
153
+
154
+ Four ways a working pre-SDK integration breaks while every test stays green.
155
+ None is hypothetical: each was measured by a team migrating real code — mesh's
156
+ spec review of `meshrelayserv/describenet.js@04f2ecf` found the first three,
157
+ and each one now has a guard in this package.
158
+
159
+ ### 1. `formatScore` returns a **string**; `roundScore` returns a **number**
160
+
161
+ mesh's pre-SDK helper was *called* `formatScore` and returned a number.
162
+ Importing this package's homonym compiles clean, every call site keeps working —
163
+ and every score flowing into a JSON payload silently turns from `83` into
164
+ `"83"`, one serialization away from whoever consumes it. If your old helper fed
165
+ numbers onward, the drop-in is `roundScore`; `formatScore` is for the pixel.
166
+
167
+ ### 2. `product`, not `userAgent`
168
+
169
+ The config key that names your product is `product`. mesh passed `userAgent`,
170
+ the unknown key was ignored in silence, and their attribution vanished from the
171
+ CDN with no symptom on their side — every call kept succeeding, so nobody
172
+ looked. Since then an unknown config key **throws a `TypeError`** listing the
173
+ valid keys, and `userAgent` specifically points you at `product`. The Python
174
+ twin already dies the same way on an unknown key (keyword-only, no `**kwargs`)
175
+ — but the parity is in the **throw**, not in the keys accepted: that twin
176
+ takes both `product` and `user_agent`, this package only `product`.
177
+
178
+ ### 3. Do not re-parse — `client.wallet()` already parses, and `.raw` holds the wire payload
179
+
180
+ A parsed result fed back into a parser used to "succeed" into an object of
181
+ nulls: every snake_case lookup missed on the camelCase object, in silence,
182
+ manufacturing the unrated-vs-failure confusion out of good data. Both wallet
183
+ parsers now throw `DescribeUnparseable` on already-parsed input. Stored a
184
+ result and need to re-read it? Parse `result.raw` — the payload as served is
185
+ kept there for exactly this.
186
+
187
+ ### 4. The wrong parser now FAILS LOUD
188
+
189
+ The free route's body (`GET /wallets/{w}/chains`) fed to
190
+ `parseWalletBreakdown()` used to answer `finalScore: null`, `weightedScore:
191
+ null`, `perChain: {}` — an object full of nothing about a wallet the free route
192
+ just scored. It now throws, naming the route it recognised and the parser that
193
+ owns it (`parseWalletReputation`).
194
+
195
+ ---
196
+
152
197
  ## Failures
153
198
 
154
199
  ```ts
@@ -267,7 +312,9 @@ try {
267
312
  } catch (err) {
268
313
  if (failedAfterPaying(err)) {
269
314
  // A signed envelope had already left. err.payment tells you how bad:
270
- // settlement: 'settled' -> proof: err.payment.receipt is the tx hash
315
+ // settlement: 'settled' -> the seller stated it: err.payment.receipt is
316
+ // the tx hash — or settlementPending is true
317
+ // and the hash has not been reported yet
271
318
  // settlement: 'unknown' -> the SDK cannot tell. Reconcile, do not assume
272
319
  reconcile(err.payment.receipt, err.payment.amount, err.payment.token);
273
320
  } else {
@@ -283,6 +330,13 @@ even though the money moved, and `fetch` rejects identically whether the request
283
330
  bytes were written or not. `'unknown'` means *ask the chain*, not *nothing
284
331
  happened*.
285
332
 
333
+ And `receipt` never carries the literal `pending`. The header legitimately does
334
+ — the seller charged and settlement has not reported the hash yet — but since
335
+ 2026-08-31 that state travels in `settlementPending: true` with `receipt: null`.
336
+ The reason is Execution Market's INC-2026-08-26: a placeholder stored in the
337
+ column meant for the hash gets archived as proof. The field carries the hash,
338
+ the flag carries the state, and nobody string-compares against a sentinel.
339
+
286
340
  ---
287
341
 
288
342
  ## Paying
@@ -301,7 +355,7 @@ const describe = new DescribeClient({
301
355
  });
302
356
 
303
357
  const detail = await describe.walletBreakdown(wallet); // never null — it throws
304
- detail.payment; // { receipt: 'rcpt_…', reused: false }
358
+ detail.payment; // { receipt: '0x…', settlementPending: false, reused: false, malformedHashes: [] }
305
359
  ```
306
360
 
307
361
  🔴 **The key comes from the environment.** Never a literal, not even "just for a
@@ -210,16 +210,35 @@ type DescribeErrorKind =
210
210
  * the connection died before the request bytes were written or while the
211
211
  * response was coming back.
212
212
  *
213
- * So: `'settled'` means *we hold the hash*. `'unknown'` means *ask the chain* —
214
- * never *"nothing happened"*. If you need the stronger answer, the receipt of a
215
- * later successful call and the on-chain transfer to the treasury are where it
216
- * lives; this SDK will not infer it for you.
213
+ * So: `'settled'` means *the seller stated settlement* — we hold the hash in
214
+ * `receipt`, or the seller declared it `pending` and `settlementPending` says
215
+ * so. `'unknown'` means *ask the chain* — never *"nothing happened"*. If you
216
+ * need the stronger answer, the receipt of a later successful call and the
217
+ * on-chain transfer to the treasury are where it lives; this SDK will not
218
+ * infer it for you.
219
+ *
220
+ * ⚠️ Until 2026-08-31 the `pending` sentinel rode in `receipt` itself, and
221
+ * Execution Market's INC-2026-08-26 is why it no longer does: a placeholder
222
+ * stored in the column meant for the hash gets archived as proof, and the only
223
+ * way to read the state back is comparing strings against a sentinel. The
224
+ * field that carries the hash never carries the placeholder — read the state
225
+ * from `settlementPending`, never from `receipt === 'pending'`.
217
226
  */
218
227
  interface PaymentAttempt {
219
- /** `'settled'` only with a receipt in hand. See the header of this type. */
228
+ /** `'settled'` only with the seller's statement in hand — a hash, or `pending`. */
220
229
  settlement: 'settled' | 'unknown';
221
- /** `X-Payment-Receipt` — the settlement tx hash, or `"pending"`. */
230
+ /**
231
+ * `X-Payment-Receipt` when it can be proof: the settlement tx hash, or —
232
+ * only on this failure path — the served string kept verbatim as forensic
233
+ * evidence when it is garbage. NEVER the `pending` sentinel: that state
234
+ * lives in `settlementPending` (EM, INC-2026-08-26).
235
+ */
222
236
  receipt: string | null;
237
+ /**
238
+ * `true` only when the seller answered the literal `pending` — charged,
239
+ * settlement not yet reported. The flag is the state; `receipt` is the hash.
240
+ */
241
+ settlementPending: boolean;
223
242
  /** `X-Payment-Reused: true` means an earlier receipt was replayed, no new charge. */
224
243
  reused: boolean | null;
225
244
  /** The status of the answer that failed, when an answer arrived at all. */
@@ -354,7 +373,26 @@ declare class DescribeNotFound extends DescribeError {
354
373
  constructor(message: string);
355
374
  }
356
375
  declare class DescribeHTTPError extends DescribeError {
357
- constructor(status: number, message: string);
376
+ /**
377
+ * What the body SAID, not just the number it said it with — Execution
378
+ * Market's contribution, ported 2026-08-31 from the Python twin
379
+ * (`errors.py::DescribeHTTPError.server_reason` — same field, same
380
+ * `' — the server says: '` text): this class's recovery has promised since
381
+ * day one that *"the body names the field"*, and until today the exception
382
+ * threw that body away and carried the bare status. Whoever caught a 422
383
+ * had to re-request to learn which field was wrong.
384
+ *
385
+ * It arrives ALREADY redacted and truncated by `client.ts::serverReason` —
386
+ * the body is server-written text and a 5xx can echo an upstream URL with
387
+ * an API key in its path — and it is appended to the MESSAGE, never to
388
+ * `recovery`, which stays the frozen literal `recovery.test.ts` pins. The
389
+ * parameter is third and optional so every existing call keeps meaning what
390
+ * it meant — additive, like the twin's keyword-only argument.
391
+ */
392
+ readonly serverReason?: string;
393
+ constructor(status: number, message: string, opts?: {
394
+ serverReason?: string;
395
+ });
358
396
  }
359
397
  /** The parsed 402, as served. Kept raw: we read it, we never re-price it. */
360
398
  interface X402Challenge {
@@ -620,16 +658,32 @@ type Timestamp = string | null;
620
658
  */
621
659
  interface PaymentEvidence {
622
660
  /**
623
- * The settlement id, or `null` when none was served **or when what was served
624
- * was not one** — `malformedHashes` tells the two apart.
661
+ * The settlement transaction hash, or `null` — when none was served, when
662
+ * what was served was not one (`malformedHashes` tells those two apart), or
663
+ * when the seller answered the literal `pending` (`settlementPending` tells
664
+ * THAT one apart).
625
665
  *
626
666
  * Validated with its own rule (`hashes.looksLikeSettlementReceipt`) because
627
- * this is the one field where `"pending"` is a legitimate value: the live
628
- * OpenAPI declares the header as the settlement transaction hash *"or
629
- * `pending` if settlement has not reported one"*. Treating that as garbage
630
- * would fire an alarm on the happy path of every fresh payment.
667
+ * this is the one field where `"pending"` is a legitimate value on the wire:
668
+ * the live OpenAPI declares the header as the settlement transaction hash
669
+ * *"or `pending` if settlement has not reported one"*. Treating it as
670
+ * garbage would fire an alarm on the happy path of every fresh payment.
671
+ *
672
+ * ⚠️ Legitimate on the WIRE, never in this field — corrected 2026-08-31,
673
+ * from Execution Market's INC-2026-08-26: until then `pending` passed
674
+ * through here, i.e. a placeholder riding in the field meant for the hash,
675
+ * which is exactly what gets archived as proof by anyone who stores this
676
+ * value. Now the sentinel is translated to `null` + `settlementPending:
677
+ * true` at the door, and no consumer ever has to string-compare against it.
631
678
  */
632
679
  receipt: string | null;
680
+ /**
681
+ * `true` only when `X-Payment-Receipt` was the literal `pending`: the seller
682
+ * charged and settlement has not reported the hash yet. Not garbage (no
683
+ * mark in `malformedHashes`, no alarm) and not a receipt either. Read the
684
+ * state HERE — `receipt === 'pending'` can no longer be true, on purpose.
685
+ */
686
+ settlementPending: boolean;
633
687
  reused: boolean;
634
688
  /**
635
689
  * `['receipt']` when the header carried something that is neither a hash nor
@@ -758,10 +812,71 @@ interface SelfRated {
758
812
  /** Distance between the self-rating and everyone else's. */
759
813
  gap: number | null;
760
814
  }
815
+ /**
816
+ * First and last rating by ON-CHAIN time.
817
+ *
818
+ * `lastRatingAt` is the last **eligible** rating — the one that holds up the
819
+ * score being shown. Since describe.net 2026-09-10 it is documented as a
820
+ * compatibility alias of `Freshness.lastEligibleRatingAt` and keeps that exact
821
+ * meaning for the life of v1. Read `WalletBreakdown.freshness` for the question
822
+ * this pair never could answer: *was this subject described recently, whether
823
+ * or not it counts?*
824
+ */
761
825
  interface Activity {
762
826
  firstRatingAt: Timestamp;
763
827
  lastRatingAt: Timestamp;
764
828
  }
829
+ /**
830
+ * WHAT the dates are about. A date without a scope is a date that lies.
831
+ *
832
+ * `direction` is the field that matters most: `received` is reputation the
833
+ * subject GOT, `emitted` is the ratings a wallet WROTE
834
+ * (`GET /reputation/rater/{wallet}`). Reading the second as the first turns a
835
+ * busy rater into a much-described subject.
836
+ */
837
+ interface FreshnessScope {
838
+ kind: string | null;
839
+ direction: string | null;
840
+ id: string | null;
841
+ network: string | null;
842
+ declaredType: string | null;
843
+ }
844
+ /**
845
+ * WHEN this subject was last described. Two dates, because two questions.
846
+ *
847
+ * - `lastReceivedFeedbackAt` — the last real NewFeedback in scope, whether or
848
+ * not it feeds the score.
849
+ * - `lastEligibleRatingAt` — the last rating that holds up the number shown.
850
+ *
851
+ * When the most recent rating was revoked the two differ, and **that difference
852
+ * is the information**: there was recent activity and the score does not
853
+ * reflect it.
854
+ *
855
+ * NEITHER is `refreshedAt`, which is when the index recomputed its own view and
856
+ * says nothing about the subject.
857
+ *
858
+ * `timestampCoverage` is `none` | `unknown` | `partial` | `complete` over
859
+ * `dated + undated`. **`none` and `unknown` are different facts**: nothing to
860
+ * date versus dates we do not have yet.
861
+ *
862
+ * NO RELATIVE TEXT, deliberately. The API publishes UTC and nothing else, so
863
+ * "3 days ago" is derived at the edge with the reader's clock — a serialised
864
+ * relative string freezes in the first cache.
865
+ */
866
+ interface Freshness {
867
+ scope: FreshnessScope;
868
+ lastReceivedFeedbackAt: Timestamp;
869
+ lastEligibleRatingAt: Timestamp;
870
+ datedFeedbackCount: number;
871
+ undatedFeedbackCount: number;
872
+ timestampCoverage: string | null;
873
+ eligibleDatedCount: number;
874
+ eligibleUndatedCount: number;
875
+ eligibleTimestampCoverage: string | null;
876
+ refreshedAt: Timestamp;
877
+ indexerCheckedAt: Timestamp;
878
+ freshnessVersion: string | null;
879
+ }
765
880
  /** One facet (`tag1`), as declared on-chain. */
766
881
  interface Facet {
767
882
  score: number | null;
@@ -818,6 +933,12 @@ interface WalletBreakdown extends Sealed {
818
933
  concentration: Concentration | null;
819
934
  confidence: Confidence | null;
820
935
  activity: Activity | null;
936
+ /**
937
+ * WHEN, with its scope. Additive: `activity` above keeps its exact meaning.
938
+ * `null` when the server does not publish the block yet — never an empty
939
+ * object, so "not published" and "no dates" stay distinguishable.
940
+ */
941
+ freshness: Freshness | null;
821
942
  snapshot: Snapshot | null;
822
943
  /** What was actually paid, if anything was. */
823
944
  payment: PaymentEvidence | null;
@@ -967,6 +1088,25 @@ interface IndexHealth {
967
1088
  orderingPolicy: string;
968
1089
  raterWeightPolicy: string;
969
1090
  confidencePolicy: string;
1091
+ /**
1092
+ * The frozen `M` of the per-chain credibility weight, `Z_k = R_k/(R_k+M)`.
1093
+ *
1094
+ * REQUIRED in the server schema since `credibility-weight-per-chain@1`
1095
+ * (2026-09-04) and untyped here until now — `types.schema.test.ts` caught it
1096
+ * the moment the snapshot was refreshed. It ships live because the number is
1097
+ * frozen and versioned: recomputing a `finalScore` by hand needs THIS M, not
1098
+ * a copy of it that went stale.
1099
+ */
1100
+ credibilityM: number | null;
1101
+ /**
1102
+ * WHEN the index as a whole last received a description. The only free,
1103
+ * account-less, parameter-less place to read whether describe.net is still
1104
+ * taking in descriptions or merely still refreshing its views — the two look
1105
+ * identical from the outside, which is the confusion `Freshness` closes.
1106
+ *
1107
+ * `null` against a server that does not publish it yet.
1108
+ */
1109
+ freshness: Freshness | null;
970
1110
  /** e.g. `{no_ratings: 0, low: 1, medium: 3, high: 6}` — live, never re-typed. */
971
1111
  confidenceThresholds: Record<string, number>;
972
1112
  /** e.g. `{min_raters: 3, campaign_per_rater: 20, top_share: 0.5, ...}`. */
@@ -1534,4 +1674,4 @@ declare class DescribeClient {
1534
1674
  private assertPayableTo;
1535
1675
  }
1536
1676
 
1537
- export { type AgentReputation as A, type WalletChainRow as B, CAVEAT_CODES as C, type DescribeErrorKind as D, type X402Payer as E, type Facet as F, failOpenCovers as G, type HealthChain as H, type IndexHealth as I, failedAfterPaying as J, type KnownCaveatCode as K, type LeaderboardRow as L, hasCaveat as M, type Network as N, type Ownership as O, type PaymentEvidence as P, isKnownCaveatCode as Q, type Rating as R, type Sealed as S, type Timestamp as T, type WalletBreakdown as W, type X402Challenge as X, type WalletReputation as a, type Activity as b, CAVEAT_SCOPE_FREE as c, CAVEAT_SCOPE_METERED as d, type Caveat as e, type CaveatCode as f, type Concentration as g, type Confidence as h, DescribeClient as i, type DescribeClientConfig as j, DescribeError as k, type DescribeFailure as l, DescribeHTTPError as m, DescribeMalformedHash as n, DescribeNotFound as o, DescribePartnerRejected as p, DescribePartnerUnsigned as q, DescribePaymentRefused as r, DescribePaymentRequired as s, DescribeTimeout as t, DescribeUnparseable as u, DescribeUnreachable as v, type PartnerSigner as w, type PaymentAttempt as x, type SelfRated as y, type Snapshot as z };
1677
+ export { type AgentReputation as A, type SelfRated as B, CAVEAT_CODES as C, type DescribeErrorKind as D, type Snapshot as E, type Facet as F, type WalletChainRow as G, type HealthChain as H, type IndexHealth as I, type X402Payer as J, type KnownCaveatCode as K, type LeaderboardRow as L, failOpenCovers as M, type Network as N, type Ownership as O, type PaymentEvidence as P, failedAfterPaying as Q, type Rating as R, type Sealed as S, type Timestamp as T, hasCaveat as U, isKnownCaveatCode as V, type WalletBreakdown as W, type X402Challenge as X, type WalletReputation as a, type Activity as b, CAVEAT_SCOPE_FREE as c, CAVEAT_SCOPE_METERED as d, type Caveat as e, type CaveatCode as f, type Concentration as g, type Confidence as h, DescribeClient as i, type DescribeClientConfig as j, DescribeError as k, type DescribeFailure as l, DescribeHTTPError as m, DescribeMalformedHash as n, DescribeNotFound as o, DescribePartnerRejected as p, DescribePartnerUnsigned as q, DescribePaymentRefused as r, DescribePaymentRequired as s, DescribeTimeout as t, DescribeUnparseable as u, DescribeUnreachable as v, type Freshness as w, type FreshnessScope as x, type PartnerSigner as y, type PaymentAttempt as z };
@@ -210,16 +210,35 @@ type DescribeErrorKind =
210
210
  * the connection died before the request bytes were written or while the
211
211
  * response was coming back.
212
212
  *
213
- * So: `'settled'` means *we hold the hash*. `'unknown'` means *ask the chain* —
214
- * never *"nothing happened"*. If you need the stronger answer, the receipt of a
215
- * later successful call and the on-chain transfer to the treasury are where it
216
- * lives; this SDK will not infer it for you.
213
+ * So: `'settled'` means *the seller stated settlement* — we hold the hash in
214
+ * `receipt`, or the seller declared it `pending` and `settlementPending` says
215
+ * so. `'unknown'` means *ask the chain* — never *"nothing happened"*. If you
216
+ * need the stronger answer, the receipt of a later successful call and the
217
+ * on-chain transfer to the treasury are where it lives; this SDK will not
218
+ * infer it for you.
219
+ *
220
+ * ⚠️ Until 2026-08-31 the `pending` sentinel rode in `receipt` itself, and
221
+ * Execution Market's INC-2026-08-26 is why it no longer does: a placeholder
222
+ * stored in the column meant for the hash gets archived as proof, and the only
223
+ * way to read the state back is comparing strings against a sentinel. The
224
+ * field that carries the hash never carries the placeholder — read the state
225
+ * from `settlementPending`, never from `receipt === 'pending'`.
217
226
  */
218
227
  interface PaymentAttempt {
219
- /** `'settled'` only with a receipt in hand. See the header of this type. */
228
+ /** `'settled'` only with the seller's statement in hand — a hash, or `pending`. */
220
229
  settlement: 'settled' | 'unknown';
221
- /** `X-Payment-Receipt` — the settlement tx hash, or `"pending"`. */
230
+ /**
231
+ * `X-Payment-Receipt` when it can be proof: the settlement tx hash, or —
232
+ * only on this failure path — the served string kept verbatim as forensic
233
+ * evidence when it is garbage. NEVER the `pending` sentinel: that state
234
+ * lives in `settlementPending` (EM, INC-2026-08-26).
235
+ */
222
236
  receipt: string | null;
237
+ /**
238
+ * `true` only when the seller answered the literal `pending` — charged,
239
+ * settlement not yet reported. The flag is the state; `receipt` is the hash.
240
+ */
241
+ settlementPending: boolean;
223
242
  /** `X-Payment-Reused: true` means an earlier receipt was replayed, no new charge. */
224
243
  reused: boolean | null;
225
244
  /** The status of the answer that failed, when an answer arrived at all. */
@@ -354,7 +373,26 @@ declare class DescribeNotFound extends DescribeError {
354
373
  constructor(message: string);
355
374
  }
356
375
  declare class DescribeHTTPError extends DescribeError {
357
- constructor(status: number, message: string);
376
+ /**
377
+ * What the body SAID, not just the number it said it with — Execution
378
+ * Market's contribution, ported 2026-08-31 from the Python twin
379
+ * (`errors.py::DescribeHTTPError.server_reason` — same field, same
380
+ * `' — the server says: '` text): this class's recovery has promised since
381
+ * day one that *"the body names the field"*, and until today the exception
382
+ * threw that body away and carried the bare status. Whoever caught a 422
383
+ * had to re-request to learn which field was wrong.
384
+ *
385
+ * It arrives ALREADY redacted and truncated by `client.ts::serverReason` —
386
+ * the body is server-written text and a 5xx can echo an upstream URL with
387
+ * an API key in its path — and it is appended to the MESSAGE, never to
388
+ * `recovery`, which stays the frozen literal `recovery.test.ts` pins. The
389
+ * parameter is third and optional so every existing call keeps meaning what
390
+ * it meant — additive, like the twin's keyword-only argument.
391
+ */
392
+ readonly serverReason?: string;
393
+ constructor(status: number, message: string, opts?: {
394
+ serverReason?: string;
395
+ });
358
396
  }
359
397
  /** The parsed 402, as served. Kept raw: we read it, we never re-price it. */
360
398
  interface X402Challenge {
@@ -620,16 +658,32 @@ type Timestamp = string | null;
620
658
  */
621
659
  interface PaymentEvidence {
622
660
  /**
623
- * The settlement id, or `null` when none was served **or when what was served
624
- * was not one** — `malformedHashes` tells the two apart.
661
+ * The settlement transaction hash, or `null` — when none was served, when
662
+ * what was served was not one (`malformedHashes` tells those two apart), or
663
+ * when the seller answered the literal `pending` (`settlementPending` tells
664
+ * THAT one apart).
625
665
  *
626
666
  * Validated with its own rule (`hashes.looksLikeSettlementReceipt`) because
627
- * this is the one field where `"pending"` is a legitimate value: the live
628
- * OpenAPI declares the header as the settlement transaction hash *"or
629
- * `pending` if settlement has not reported one"*. Treating that as garbage
630
- * would fire an alarm on the happy path of every fresh payment.
667
+ * this is the one field where `"pending"` is a legitimate value on the wire:
668
+ * the live OpenAPI declares the header as the settlement transaction hash
669
+ * *"or `pending` if settlement has not reported one"*. Treating it as
670
+ * garbage would fire an alarm on the happy path of every fresh payment.
671
+ *
672
+ * ⚠️ Legitimate on the WIRE, never in this field — corrected 2026-08-31,
673
+ * from Execution Market's INC-2026-08-26: until then `pending` passed
674
+ * through here, i.e. a placeholder riding in the field meant for the hash,
675
+ * which is exactly what gets archived as proof by anyone who stores this
676
+ * value. Now the sentinel is translated to `null` + `settlementPending:
677
+ * true` at the door, and no consumer ever has to string-compare against it.
631
678
  */
632
679
  receipt: string | null;
680
+ /**
681
+ * `true` only when `X-Payment-Receipt` was the literal `pending`: the seller
682
+ * charged and settlement has not reported the hash yet. Not garbage (no
683
+ * mark in `malformedHashes`, no alarm) and not a receipt either. Read the
684
+ * state HERE — `receipt === 'pending'` can no longer be true, on purpose.
685
+ */
686
+ settlementPending: boolean;
633
687
  reused: boolean;
634
688
  /**
635
689
  * `['receipt']` when the header carried something that is neither a hash nor
@@ -758,10 +812,71 @@ interface SelfRated {
758
812
  /** Distance between the self-rating and everyone else's. */
759
813
  gap: number | null;
760
814
  }
815
+ /**
816
+ * First and last rating by ON-CHAIN time.
817
+ *
818
+ * `lastRatingAt` is the last **eligible** rating — the one that holds up the
819
+ * score being shown. Since describe.net 2026-09-10 it is documented as a
820
+ * compatibility alias of `Freshness.lastEligibleRatingAt` and keeps that exact
821
+ * meaning for the life of v1. Read `WalletBreakdown.freshness` for the question
822
+ * this pair never could answer: *was this subject described recently, whether
823
+ * or not it counts?*
824
+ */
761
825
  interface Activity {
762
826
  firstRatingAt: Timestamp;
763
827
  lastRatingAt: Timestamp;
764
828
  }
829
+ /**
830
+ * WHAT the dates are about. A date without a scope is a date that lies.
831
+ *
832
+ * `direction` is the field that matters most: `received` is reputation the
833
+ * subject GOT, `emitted` is the ratings a wallet WROTE
834
+ * (`GET /reputation/rater/{wallet}`). Reading the second as the first turns a
835
+ * busy rater into a much-described subject.
836
+ */
837
+ interface FreshnessScope {
838
+ kind: string | null;
839
+ direction: string | null;
840
+ id: string | null;
841
+ network: string | null;
842
+ declaredType: string | null;
843
+ }
844
+ /**
845
+ * WHEN this subject was last described. Two dates, because two questions.
846
+ *
847
+ * - `lastReceivedFeedbackAt` — the last real NewFeedback in scope, whether or
848
+ * not it feeds the score.
849
+ * - `lastEligibleRatingAt` — the last rating that holds up the number shown.
850
+ *
851
+ * When the most recent rating was revoked the two differ, and **that difference
852
+ * is the information**: there was recent activity and the score does not
853
+ * reflect it.
854
+ *
855
+ * NEITHER is `refreshedAt`, which is when the index recomputed its own view and
856
+ * says nothing about the subject.
857
+ *
858
+ * `timestampCoverage` is `none` | `unknown` | `partial` | `complete` over
859
+ * `dated + undated`. **`none` and `unknown` are different facts**: nothing to
860
+ * date versus dates we do not have yet.
861
+ *
862
+ * NO RELATIVE TEXT, deliberately. The API publishes UTC and nothing else, so
863
+ * "3 days ago" is derived at the edge with the reader's clock — a serialised
864
+ * relative string freezes in the first cache.
865
+ */
866
+ interface Freshness {
867
+ scope: FreshnessScope;
868
+ lastReceivedFeedbackAt: Timestamp;
869
+ lastEligibleRatingAt: Timestamp;
870
+ datedFeedbackCount: number;
871
+ undatedFeedbackCount: number;
872
+ timestampCoverage: string | null;
873
+ eligibleDatedCount: number;
874
+ eligibleUndatedCount: number;
875
+ eligibleTimestampCoverage: string | null;
876
+ refreshedAt: Timestamp;
877
+ indexerCheckedAt: Timestamp;
878
+ freshnessVersion: string | null;
879
+ }
765
880
  /** One facet (`tag1`), as declared on-chain. */
766
881
  interface Facet {
767
882
  score: number | null;
@@ -818,6 +933,12 @@ interface WalletBreakdown extends Sealed {
818
933
  concentration: Concentration | null;
819
934
  confidence: Confidence | null;
820
935
  activity: Activity | null;
936
+ /**
937
+ * WHEN, with its scope. Additive: `activity` above keeps its exact meaning.
938
+ * `null` when the server does not publish the block yet — never an empty
939
+ * object, so "not published" and "no dates" stay distinguishable.
940
+ */
941
+ freshness: Freshness | null;
821
942
  snapshot: Snapshot | null;
822
943
  /** What was actually paid, if anything was. */
823
944
  payment: PaymentEvidence | null;
@@ -967,6 +1088,25 @@ interface IndexHealth {
967
1088
  orderingPolicy: string;
968
1089
  raterWeightPolicy: string;
969
1090
  confidencePolicy: string;
1091
+ /**
1092
+ * The frozen `M` of the per-chain credibility weight, `Z_k = R_k/(R_k+M)`.
1093
+ *
1094
+ * REQUIRED in the server schema since `credibility-weight-per-chain@1`
1095
+ * (2026-09-04) and untyped here until now — `types.schema.test.ts` caught it
1096
+ * the moment the snapshot was refreshed. It ships live because the number is
1097
+ * frozen and versioned: recomputing a `finalScore` by hand needs THIS M, not
1098
+ * a copy of it that went stale.
1099
+ */
1100
+ credibilityM: number | null;
1101
+ /**
1102
+ * WHEN the index as a whole last received a description. The only free,
1103
+ * account-less, parameter-less place to read whether describe.net is still
1104
+ * taking in descriptions or merely still refreshing its views — the two look
1105
+ * identical from the outside, which is the confusion `Freshness` closes.
1106
+ *
1107
+ * `null` against a server that does not publish it yet.
1108
+ */
1109
+ freshness: Freshness | null;
970
1110
  /** e.g. `{no_ratings: 0, low: 1, medium: 3, high: 6}` — live, never re-typed. */
971
1111
  confidenceThresholds: Record<string, number>;
972
1112
  /** e.g. `{min_raters: 3, campaign_per_rater: 20, top_share: 0.5, ...}`. */
@@ -1534,4 +1674,4 @@ declare class DescribeClient {
1534
1674
  private assertPayableTo;
1535
1675
  }
1536
1676
 
1537
- export { type AgentReputation as A, type WalletChainRow as B, CAVEAT_CODES as C, type DescribeErrorKind as D, type X402Payer as E, type Facet as F, failOpenCovers as G, type HealthChain as H, type IndexHealth as I, failedAfterPaying as J, type KnownCaveatCode as K, type LeaderboardRow as L, hasCaveat as M, type Network as N, type Ownership as O, type PaymentEvidence as P, isKnownCaveatCode as Q, type Rating as R, type Sealed as S, type Timestamp as T, type WalletBreakdown as W, type X402Challenge as X, type WalletReputation as a, type Activity as b, CAVEAT_SCOPE_FREE as c, CAVEAT_SCOPE_METERED as d, type Caveat as e, type CaveatCode as f, type Concentration as g, type Confidence as h, DescribeClient as i, type DescribeClientConfig as j, DescribeError as k, type DescribeFailure as l, DescribeHTTPError as m, DescribeMalformedHash as n, DescribeNotFound as o, DescribePartnerRejected as p, DescribePartnerUnsigned as q, DescribePaymentRefused as r, DescribePaymentRequired as s, DescribeTimeout as t, DescribeUnparseable as u, DescribeUnreachable as v, type PartnerSigner as w, type PaymentAttempt as x, type SelfRated as y, type Snapshot as z };
1677
+ export { type AgentReputation as A, type SelfRated as B, CAVEAT_CODES as C, type DescribeErrorKind as D, type Snapshot as E, type Facet as F, type WalletChainRow as G, type HealthChain as H, type IndexHealth as I, type X402Payer as J, type KnownCaveatCode as K, type LeaderboardRow as L, failOpenCovers as M, type Network as N, type Ownership as O, type PaymentEvidence as P, failedAfterPaying as Q, type Rating as R, type Sealed as S, type Timestamp as T, hasCaveat as U, isKnownCaveatCode as V, type WalletBreakdown as W, type X402Challenge as X, type WalletReputation as a, type Activity as b, CAVEAT_SCOPE_FREE as c, CAVEAT_SCOPE_METERED as d, type Caveat as e, type CaveatCode as f, type Concentration as g, type Confidence as h, DescribeClient as i, type DescribeClientConfig as j, DescribeError as k, type DescribeFailure as l, DescribeHTTPError as m, DescribeMalformedHash as n, DescribeNotFound as o, DescribePartnerRejected as p, DescribePartnerUnsigned as q, DescribePaymentRefused as r, DescribePaymentRequired as s, DescribeTimeout as t, DescribeUnparseable as u, DescribeUnreachable as v, type Freshness as w, type FreshnessScope as x, type PartnerSigner as y, type PaymentAttempt as z };
@@ -138,7 +138,7 @@ declare const PARTNER_KEY_ENV = "DESCRIBE_PARTNER_PRIVATE_KEY";
138
138
  * time instead of at runtime. Bumping the version without the constant is a
139
139
  * red test, not a silent lie in someone's access log.
140
140
  */
141
- declare const SDK_VERSION = "0.1.0";
141
+ declare const SDK_VERSION = "0.3.0";
142
142
  /** `uvd-describe-sdk-ts/0.1.0`, plus `(+<product>)` when the caller names itself. */
143
143
  declare const SDK_NAME = "uvd-describe-sdk-ts";
144
144
  /**
@@ -138,7 +138,7 @@ declare const PARTNER_KEY_ENV = "DESCRIBE_PARTNER_PRIVATE_KEY";
138
138
  * time instead of at runtime. Bumping the version without the constant is a
139
139
  * red test, not a silent lie in someone's access log.
140
140
  */
141
- declare const SDK_VERSION = "0.1.0";
141
+ declare const SDK_VERSION = "0.3.0";
142
142
  /** `uvd-describe-sdk-ts/0.1.0`, plus `(+<product>)` when the caller names itself. */
143
143
  declare const SDK_NAME = "uvd-describe-sdk-ts";
144
144
  /**
package/dist/index.d.mts CHANGED
@@ -1,6 +1,6 @@
1
- import { D as DescribeErrorKind, P as PaymentEvidence, A as AgentReputation, I as IndexHealth, L as LeaderboardRow, W as WalletBreakdown, a as WalletReputation } from './client-s3KrgrCt.mjs';
2
- export { b as Activity, C as CAVEAT_CODES, c as CAVEAT_SCOPE_FREE, d as CAVEAT_SCOPE_METERED, e as Caveat, f as CaveatCode, g as Concentration, h as Confidence, i as DescribeClient, j as DescribeClientConfig, k as DescribeError, l as DescribeFailure, m as DescribeHTTPError, n as DescribeMalformedHash, o as DescribeNotFound, p as DescribePartnerRejected, q as DescribePartnerUnsigned, r as DescribePaymentRefused, s as DescribePaymentRequired, t as DescribeTimeout, u as DescribeUnparseable, v as DescribeUnreachable, F as Facet, H as HealthChain, K as KnownCaveatCode, N as Network, O as Ownership, w as PartnerSigner, x as PaymentAttempt, R as Rating, S as Sealed, y as SelfRated, z as Snapshot, T as Timestamp, B as WalletChainRow, X as X402Challenge, E as X402Payer, G as failOpenCovers, J as failedAfterPaying, M as hasCaveat, Q as isKnownCaveatCode } from './client-s3KrgrCt.mjs';
3
- export { D as DEFAULT_BASE_URL, a as DEFAULT_JITTER_MS, b as DEFAULT_SITE_URL, c as DEFAULT_TIMEOUT_MS, P as PARTNER_CHAIN_ID, d as PARTNER_KEY_ENV, S as SDK_NAME, e as SDK_VERSION, T as TREASURY_EVM, u as userAgent } from './config-Y2VK_neB.mjs';
1
+ import { D as DescribeErrorKind, P as PaymentEvidence, A as AgentReputation, I as IndexHealth, L as LeaderboardRow, W as WalletBreakdown, a as WalletReputation } from './client-BMfgl1zP.mjs';
2
+ export { b as Activity, C as CAVEAT_CODES, c as CAVEAT_SCOPE_FREE, d as CAVEAT_SCOPE_METERED, e as Caveat, f as CaveatCode, g as Concentration, h as Confidence, i as DescribeClient, j as DescribeClientConfig, k as DescribeError, l as DescribeFailure, m as DescribeHTTPError, n as DescribeMalformedHash, o as DescribeNotFound, p as DescribePartnerRejected, q as DescribePartnerUnsigned, r as DescribePaymentRefused, s as DescribePaymentRequired, t as DescribeTimeout, u as DescribeUnparseable, v as DescribeUnreachable, F as Facet, w as Freshness, x as FreshnessScope, H as HealthChain, K as KnownCaveatCode, N as Network, O as Ownership, y as PartnerSigner, z as PaymentAttempt, R as Rating, S as Sealed, B as SelfRated, E as Snapshot, T as Timestamp, G as WalletChainRow, X as X402Challenge, J as X402Payer, M as failOpenCovers, Q as failedAfterPaying, U as hasCaveat, V as isKnownCaveatCode } from './client-BMfgl1zP.mjs';
3
+ export { D as DEFAULT_BASE_URL, a as DEFAULT_JITTER_MS, b as DEFAULT_SITE_URL, c as DEFAULT_TIMEOUT_MS, P as PARTNER_CHAIN_ID, d as PARTNER_KEY_ENV, S as SDK_NAME, e as SDK_VERSION, T as TREASURY_EVM, u as userAgent } from './config-DzzhWFYr.mjs';
4
4
 
5
5
  /**
6
6
  * What to do INSTEAD — the sentence `transient` cannot say.
@@ -181,6 +181,15 @@ declare function recoveryFor(kind: DescribeErrorKind, status?: number): string |
181
181
  *
182
182
  * A non-finite input (a `NaN` from a malformed payload) is also `null`: a
183
183
  * number we cannot name is not a number we may put describe.net's name on.
184
+ *
185
+ * 🔴 **This returns a STRING, and the homonym trap is measured** (mesh,
186
+ * meshrelay migration review 2026-08-31; spec in
187
+ * `meshrelayserv/describenet.js@04f2ecf`): their pre-SDK code had a local
188
+ * `formatScore` that returned a NUMBER, so swapping the import compiles clean,
189
+ * every call site keeps working — and every score that flows into a JSON
190
+ * payload silently turns from `83` into `"83"`, one serialization away from
191
+ * whoever consumes it. If a number is what you need, {@link roundScore} is the
192
+ * drop-in; this one is for the pixel.
184
193
  */
185
194
  declare function formatScore(value: number | null | undefined): string | null;
186
195
  /**
@@ -192,6 +201,14 @@ declare function formatScore(value: number | null | undefined): string | null;
192
201
  * places" (`describenet.js:204-208`). If you do that, use this — and be aware
193
202
  * you have made the value lossy on purpose. Everything else should carry the
194
203
  * full-precision number and call `formatScore` at the pixel.
204
+ *
205
+ * 🔴 **This returns a NUMBER; {@link formatScore} returns a STRING** — and a
206
+ * migrating consumer whose old helper was called `formatScore` but returned a
207
+ * number wants THIS one, not the name-alike. mesh measured the collision
208
+ * (2026-08-31, spec in `meshrelayserv/describenet.js@04f2ecf`): importing the
209
+ * homonym type-checks wherever the value only ever meets `JSON.stringify` or a
210
+ * template literal, and the symptom is numbers arriving as strings downstream,
211
+ * with nothing red anywhere near the cause.
195
212
  */
196
213
  declare function roundScore(value: number | null | undefined): number | null;
197
214
 
@@ -468,6 +485,32 @@ declare function malformedHashReport(result: {
468
485
  * absence of a value and a value that is nonsense are different facts, and
469
486
  * collapsing them is the failure this file exists to prevent. See
470
487
  * `hashes.ts`, and `client.ts` for how the fact reaches the caller.
488
+ * 5. **A payload from the wrong door fails LOUD — in BOTH directions.** Added
489
+ * 2026-08-31 from mesh's migration review (meshrelay; spec in
490
+ * `meshrelayserv/describenet.js@04f2ecf`), which found rule 3 broken by its
491
+ * own parsers: `wallet` is a string in every shape this API serves AND in
492
+ * every shape this SDK returns, so the essential-shape check alone let
493
+ * wrong inputs "succeed" into exactly the object-full-of-nulls rule 3
494
+ * declares impossible — the FREE route's body fed to `parseWalletBreakdown`
495
+ * (`finalScore: null`, `weightedScore: null`, `perChain: {}`, reading as
496
+ * "paid and got nothing"), and a result that was ALREADY parsed fed back in
497
+ * (every snake_case lookup misses, all nulls, in silence). The guards are
498
+ * key-based — a marker key by PRESENCE, never by value — and each one names
499
+ * the door the caller actually wanted: `global_score` without `final_score`
500
+ * is the free route's body and belongs to `parseWalletReputation`;
501
+ * `final_score` without `global_score` is the METERED route's body and
502
+ * belongs to `parseWalletBreakdown`; a camelCase key (`globalScore`,
503
+ * `finalScore`, `weightedScore`) is OUR output, and output does not go back
504
+ * in — `client.wallet()` already parses, and the wire payload survives in
505
+ * `.raw` for whoever needs to re-read it.
506
+ * ⚠️ CORRECTED 2026-08-31, same day, by the symmetry review against the
507
+ * Python twin: as first written this rule guarded only ONE wrong door
508
+ * (free body → `parseWalletBreakdown`) and the code matched the text — the
509
+ * metered body fed to `parseWalletReputation` still "succeeded" into
510
+ * `globalScore: null`, `chains: []`, in silence, while both trees claimed
511
+ * mirror. The twin guards both directions
512
+ * (`models.py::parse_wallet_reputation`); now so does this file, and
513
+ * `parse.test.ts` mounts the bad state for each.
471
514
  */
472
515
 
473
516
  /** `GET /wallets/{wallet}/chains`. Requires `wallet` — everything else may be absent. */