uvd-describe-sdk 0.1.0 → 0.2.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-RAhXcpdY.d.mts} +67 -13
- package/dist/{client-s3KrgrCt.d.ts → client-RAhXcpdY.d.ts} +67 -13
- package/dist/{config-Y2VK_neB.d.mts → config-uvI_GS-x.d.mts} +1 -1
- package/dist/{config-Y2VK_neB.d.ts → config-uvI_GS-x.d.ts} +1 -1
- package/dist/index.d.mts +46 -3
- package/dist/index.d.ts +46 -3
- package/dist/index.js +127 -22
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +127 -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/parse.ts +72 -0
- package/src/types.ts +22 -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
|
|
@@ -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
|
|
@@ -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.2.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.2.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, 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-
|
|
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-RAhXcpdY.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-RAhXcpdY.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-uvI_GS-x.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. */
|
package/dist/index.d.ts
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, 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-
|
|
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-RAhXcpdY.js';
|
|
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-RAhXcpdY.js';
|
|
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-uvI_GS-x.js';
|
|
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. */
|