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 +56 -2
- package/dist/{client-s3KrgrCt.d.mts → client-BMfgl1zP.d.mts} +154 -14
- package/dist/{client-s3KrgrCt.d.ts → client-BMfgl1zP.d.ts} +154 -14
- package/dist/{config-Y2VK_neB.d.mts → config-DzzhWFYr.d.mts} +1 -1
- package/dist/{config-Y2VK_neB.d.ts → config-DzzhWFYr.d.ts} +1 -1
- package/dist/index.d.mts +46 -3
- package/dist/index.d.ts +46 -3
- package/dist/index.js +154 -22
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +154 -22
- 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 +1 -1
- package/src/client.ts +153 -15
- package/src/config.ts +1 -1
- package/src/errors.ts +58 -17
- package/src/format.ts +17 -0
- package/src/index.ts +2 -0
- package/src/parse.ts +113 -0
- package/src/types.ts +110 -6
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' ->
|
|
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: '
|
|
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 *
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
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
|
|
228
|
+
/** `'settled'` only with the seller's statement in hand — a hash, or `pending`. */
|
|
220
229
|
settlement: 'settled' | 'unknown';
|
|
221
|
-
/**
|
|
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
|
-
|
|
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
|
|
624
|
-
* was not one
|
|
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
|
|
628
|
-
* OpenAPI declares the header as the settlement transaction hash
|
|
629
|
-
* `pending` if settlement has not reported one"*. Treating
|
|
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
|
|
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 *
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
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
|
|
228
|
+
/** `'settled'` only with the seller's statement in hand — a hash, or `pending`. */
|
|
220
229
|
settlement: 'settled' | 'unknown';
|
|
221
|
-
/**
|
|
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
|
-
|
|
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
|
|
624
|
-
* was not one
|
|
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
|
|
628
|
-
* OpenAPI declares the header as the settlement transaction hash
|
|
629
|
-
* `pending` if settlement has not reported one"*. Treating
|
|
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
|
|
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.
|
|
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.
|
|
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-
|
|
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,
|
|
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-
|
|
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. */
|