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/src/errors.ts
CHANGED
|
@@ -214,16 +214,35 @@ export type DescribeErrorKind =
|
|
|
214
214
|
* the connection died before the request bytes were written or while the
|
|
215
215
|
* response was coming back.
|
|
216
216
|
*
|
|
217
|
-
* So: `'settled'` means *
|
|
218
|
-
*
|
|
219
|
-
*
|
|
220
|
-
*
|
|
217
|
+
* So: `'settled'` means *the seller stated settlement* — we hold the hash in
|
|
218
|
+
* `receipt`, or the seller declared it `pending` and `settlementPending` says
|
|
219
|
+
* so. `'unknown'` means *ask the chain* — never *"nothing happened"*. If you
|
|
220
|
+
* need the stronger answer, the receipt of a later successful call and the
|
|
221
|
+
* on-chain transfer to the treasury are where it lives; this SDK will not
|
|
222
|
+
* infer it for you.
|
|
223
|
+
*
|
|
224
|
+
* ⚠️ Until 2026-08-31 the `pending` sentinel rode in `receipt` itself, and
|
|
225
|
+
* Execution Market's INC-2026-08-26 is why it no longer does: a placeholder
|
|
226
|
+
* stored in the column meant for the hash gets archived as proof, and the only
|
|
227
|
+
* way to read the state back is comparing strings against a sentinel. The
|
|
228
|
+
* field that carries the hash never carries the placeholder — read the state
|
|
229
|
+
* from `settlementPending`, never from `receipt === 'pending'`.
|
|
221
230
|
*/
|
|
222
231
|
export interface PaymentAttempt {
|
|
223
|
-
/** `'settled'` only with
|
|
232
|
+
/** `'settled'` only with the seller's statement in hand — a hash, or `pending`. */
|
|
224
233
|
settlement: 'settled' | 'unknown';
|
|
225
|
-
/**
|
|
234
|
+
/**
|
|
235
|
+
* `X-Payment-Receipt` when it can be proof: the settlement tx hash, or —
|
|
236
|
+
* only on this failure path — the served string kept verbatim as forensic
|
|
237
|
+
* evidence when it is garbage. NEVER the `pending` sentinel: that state
|
|
238
|
+
* lives in `settlementPending` (EM, INC-2026-08-26).
|
|
239
|
+
*/
|
|
226
240
|
receipt: string | null;
|
|
241
|
+
/**
|
|
242
|
+
* `true` only when the seller answered the literal `pending` — charged,
|
|
243
|
+
* settlement not yet reported. The flag is the state; `receipt` is the hash.
|
|
244
|
+
*/
|
|
245
|
+
settlementPending: boolean;
|
|
227
246
|
/** `X-Payment-Reused: true` means an earlier receipt was replayed, no new charge. */
|
|
228
247
|
reused: boolean | null;
|
|
229
248
|
/** The status of the answer that failed, when an answer arrived at all. */
|
|
@@ -400,19 +419,41 @@ export class DescribeNotFound extends DescribeError {
|
|
|
400
419
|
}
|
|
401
420
|
|
|
402
421
|
export class DescribeHTTPError extends DescribeError {
|
|
403
|
-
|
|
422
|
+
/**
|
|
423
|
+
* What the body SAID, not just the number it said it with — Execution
|
|
424
|
+
* Market's contribution, ported 2026-08-31 from the Python twin
|
|
425
|
+
* (`errors.py::DescribeHTTPError.server_reason` — same field, same
|
|
426
|
+
* `' — the server says: '` text): this class's recovery has promised since
|
|
427
|
+
* day one that *"the body names the field"*, and until today the exception
|
|
428
|
+
* threw that body away and carried the bare status. Whoever caught a 422
|
|
429
|
+
* had to re-request to learn which field was wrong.
|
|
430
|
+
*
|
|
431
|
+
* It arrives ALREADY redacted and truncated by `client.ts::serverReason` —
|
|
432
|
+
* the body is server-written text and a 5xx can echo an upstream URL with
|
|
433
|
+
* an API key in its path — and it is appended to the MESSAGE, never to
|
|
434
|
+
* `recovery`, which stays the frozen literal `recovery.test.ts` pins. The
|
|
435
|
+
* parameter is third and optional so every existing call keeps meaning what
|
|
436
|
+
* it meant — additive, like the twin's keyword-only argument.
|
|
437
|
+
*/
|
|
438
|
+
readonly serverReason?: string;
|
|
439
|
+
constructor(status: number, message: string, opts: { serverReason?: string } = {}) {
|
|
404
440
|
const server = status >= 500;
|
|
405
|
-
super(
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
441
|
+
super(
|
|
442
|
+
server ? 'http_5xx' : 'http_4xx',
|
|
443
|
+
opts.serverReason ? `${message} — the server says: ${opts.serverReason}` : message,
|
|
444
|
+
{
|
|
445
|
+
// 429 is the one 4xx worth retrying: the 20 rps ceiling is shared with
|
|
446
|
+
// every other UVD consumer, so it says "someone else is loud right now",
|
|
447
|
+
// not "your request is wrong".
|
|
448
|
+
transient: server || status === 429,
|
|
449
|
+
// A 4xx is the caller's fault and must NOT vanish into failOpen — except
|
|
450
|
+
// 429, which is the shared limit and reads exactly like a brief outage.
|
|
451
|
+
serviceFault: server || status === 429,
|
|
452
|
+
status,
|
|
453
|
+
},
|
|
454
|
+
);
|
|
415
455
|
this.name = 'DescribeHTTPError';
|
|
456
|
+
this.serverReason = opts.serverReason;
|
|
416
457
|
}
|
|
417
458
|
}
|
|
418
459
|
|
package/src/format.ts
CHANGED
|
@@ -45,6 +45,15 @@
|
|
|
45
45
|
*
|
|
46
46
|
* A non-finite input (a `NaN` from a malformed payload) is also `null`: a
|
|
47
47
|
* number we cannot name is not a number we may put describe.net's name on.
|
|
48
|
+
*
|
|
49
|
+
* 🔴 **This returns a STRING, and the homonym trap is measured** (mesh,
|
|
50
|
+
* meshrelay migration review 2026-08-31; spec in
|
|
51
|
+
* `meshrelayserv/describenet.js@04f2ecf`): their pre-SDK code had a local
|
|
52
|
+
* `formatScore` that returned a NUMBER, so swapping the import compiles clean,
|
|
53
|
+
* every call site keeps working — and every score that flows into a JSON
|
|
54
|
+
* payload silently turns from `83` into `"83"`, one serialization away from
|
|
55
|
+
* whoever consumes it. If a number is what you need, {@link roundScore} is the
|
|
56
|
+
* drop-in; this one is for the pixel.
|
|
48
57
|
*/
|
|
49
58
|
export function formatScore(value: number | null | undefined): string | null {
|
|
50
59
|
if (typeof value !== 'number' || !Number.isFinite(value)) return null;
|
|
@@ -60,6 +69,14 @@ export function formatScore(value: number | null | undefined): string | null {
|
|
|
60
69
|
* places" (`describenet.js:204-208`). If you do that, use this — and be aware
|
|
61
70
|
* you have made the value lossy on purpose. Everything else should carry the
|
|
62
71
|
* full-precision number and call `formatScore` at the pixel.
|
|
72
|
+
*
|
|
73
|
+
* 🔴 **This returns a NUMBER; {@link formatScore} returns a STRING** — and a
|
|
74
|
+
* migrating consumer whose old helper was called `formatScore` but returned a
|
|
75
|
+
* number wants THIS one, not the name-alike. mesh measured the collision
|
|
76
|
+
* (2026-08-31, spec in `meshrelayserv/describenet.js@04f2ecf`): importing the
|
|
77
|
+
* homonym type-checks wherever the value only ever meets `JSON.stringify` or a
|
|
78
|
+
* template literal, and the symptom is numbers arriving as strings downstream,
|
|
79
|
+
* with nothing red anywhere near the cause.
|
|
63
80
|
*/
|
|
64
81
|
export function roundScore(value: number | null | undefined): number | null {
|
|
65
82
|
if (typeof value !== 'number' || !Number.isFinite(value)) return null;
|
package/src/parse.ts
CHANGED
|
@@ -20,6 +20,32 @@
|
|
|
20
20
|
* absence of a value and a value that is nonsense are different facts, and
|
|
21
21
|
* collapsing them is the failure this file exists to prevent. See
|
|
22
22
|
* `hashes.ts`, and `client.ts` for how the fact reaches the caller.
|
|
23
|
+
* 5. **A payload from the wrong door fails LOUD — in BOTH directions.** Added
|
|
24
|
+
* 2026-08-31 from mesh's migration review (meshrelay; spec in
|
|
25
|
+
* `meshrelayserv/describenet.js@04f2ecf`), which found rule 3 broken by its
|
|
26
|
+
* own parsers: `wallet` is a string in every shape this API serves AND in
|
|
27
|
+
* every shape this SDK returns, so the essential-shape check alone let
|
|
28
|
+
* wrong inputs "succeed" into exactly the object-full-of-nulls rule 3
|
|
29
|
+
* declares impossible — the FREE route's body fed to `parseWalletBreakdown`
|
|
30
|
+
* (`finalScore: null`, `weightedScore: null`, `perChain: {}`, reading as
|
|
31
|
+
* "paid and got nothing"), and a result that was ALREADY parsed fed back in
|
|
32
|
+
* (every snake_case lookup misses, all nulls, in silence). The guards are
|
|
33
|
+
* key-based — a marker key by PRESENCE, never by value — and each one names
|
|
34
|
+
* the door the caller actually wanted: `global_score` without `final_score`
|
|
35
|
+
* is the free route's body and belongs to `parseWalletReputation`;
|
|
36
|
+
* `final_score` without `global_score` is the METERED route's body and
|
|
37
|
+
* belongs to `parseWalletBreakdown`; a camelCase key (`globalScore`,
|
|
38
|
+
* `finalScore`, `weightedScore`) is OUR output, and output does not go back
|
|
39
|
+
* in — `client.wallet()` already parses, and the wire payload survives in
|
|
40
|
+
* `.raw` for whoever needs to re-read it.
|
|
41
|
+
* ⚠️ CORRECTED 2026-08-31, same day, by the symmetry review against the
|
|
42
|
+
* Python twin: as first written this rule guarded only ONE wrong door
|
|
43
|
+
* (free body → `parseWalletBreakdown`) and the code matched the text — the
|
|
44
|
+
* metered body fed to `parseWalletReputation` still "succeeded" into
|
|
45
|
+
* `globalScore: null`, `chains: []`, in silence, while both trees claimed
|
|
46
|
+
* mirror. The twin guards both directions
|
|
47
|
+
* (`models.py::parse_wallet_reputation`); now so does this file, and
|
|
48
|
+
* `parse.test.ts` mounts the bad state for each.
|
|
23
49
|
*/
|
|
24
50
|
|
|
25
51
|
import { CAVEAT_SCOPE_FREE, CAVEAT_SCOPE_METERED, type Caveat } from './caveats';
|
|
@@ -232,6 +258,35 @@ export function parseWalletReputation(payload: unknown): WalletReputation {
|
|
|
232
258
|
if (!isObj(payload) || typeof payload.wallet !== 'string') {
|
|
233
259
|
throw new DescribeUnparseable('wallet-chains response is missing its essential shape (wallet)');
|
|
234
260
|
}
|
|
261
|
+
// Rule 5: our own output does not go back in. The wire carries `global_score`
|
|
262
|
+
// (snake_case); `globalScore` exists only in what THIS function returned, and
|
|
263
|
+
// re-parsing that used to "succeed" into all-nulls in silence (mesh, 2026-08-31).
|
|
264
|
+
// `finalScore`/`weightedScore` are the OTHER parser's output crossing the door
|
|
265
|
+
// (a parsed WalletBreakdown fed here slipped through until the symmetry
|
|
266
|
+
// re-check of 2026-08-31 caught it in BOTH twins).
|
|
267
|
+
if ('globalScore' in payload || 'finalScore' in payload || 'weightedScore' in payload) {
|
|
268
|
+
throw new DescribeUnparseable(
|
|
269
|
+
'this payload is already parsed (it carries a camelCase score key, which the wire ' +
|
|
270
|
+
'never does): do not parse twice. `client.wallet()` already parses, and the payload as ' +
|
|
271
|
+
'served is in `.raw`.',
|
|
272
|
+
);
|
|
273
|
+
}
|
|
274
|
+
// Rule 5, the inverse door — added 2026-08-31 by the symmetry review against
|
|
275
|
+
// the Python twin: `models.py::parse_wallet_reputation` guards this and this
|
|
276
|
+
// file claimed mirror while it did not. Fed the METERED route's body, this
|
|
277
|
+
// parser used to "succeed" into `globalScore: null`, `chains: []`, in
|
|
278
|
+
// silence — turning a score that exists and was PAID for into "not yet
|
|
279
|
+
// rated". The marker is the key pair by PRESENCE, never by value
|
|
280
|
+
// (`final_score: null` must still fire), so a future payload carrying both
|
|
281
|
+
// stays additive-tolerant and does not trip it.
|
|
282
|
+
if ('final_score' in payload && !('global_score' in payload)) {
|
|
283
|
+
throw new DescribeUnparseable(
|
|
284
|
+
"this is the METERED route's payload (`GET /reputation/wallet/{wallet}` — it carries " +
|
|
285
|
+
'a top-level `final_score` and no `global_score`): it goes to parseWalletBreakdown, not ' +
|
|
286
|
+
'parseWalletReputation. Parsing it here would answer nulls for a score the metered ' +
|
|
287
|
+
'route DID serve.',
|
|
288
|
+
);
|
|
289
|
+
}
|
|
235
290
|
const rows = Array.isArray(payload.chains) ? payload.chains : [];
|
|
236
291
|
const chains: WalletChainRow[] = rows.filter(isObj).map((row) => ({
|
|
237
292
|
network: String(row.network ?? ''),
|
|
@@ -268,6 +323,23 @@ export function parseWalletBreakdown(
|
|
|
268
323
|
if (!isObj(payload) || typeof payload.wallet !== 'string') {
|
|
269
324
|
throw new DescribeUnparseable('wallet-breakdown response is missing its essential shape (wallet)');
|
|
270
325
|
}
|
|
326
|
+
// Rule 5, twice — both guards close a hole mesh measured (2026-08-31): this
|
|
327
|
+
// function used to accept both of these and answer an object full of nulls.
|
|
328
|
+
if ('finalScore' in payload || 'weightedScore' in payload || 'globalScore' in payload) {
|
|
329
|
+
throw new DescribeUnparseable(
|
|
330
|
+
'this payload is already parsed (it carries a camelCase score key, which the wire never ' +
|
|
331
|
+
'does — `globalScore` means it is the OTHER parser\'s output): do not parse twice. The ' +
|
|
332
|
+
'payload as served is in `.raw`.',
|
|
333
|
+
);
|
|
334
|
+
}
|
|
335
|
+
if ('global_score' in payload && !('final_score' in payload)) {
|
|
336
|
+
throw new DescribeUnparseable(
|
|
337
|
+
'this is the FREE route\'s payload (`GET /wallets/{wallet}/chains` — it carries ' +
|
|
338
|
+
'`global_score` and no top-level `final_score`): it goes to parseWalletReputation, not ' +
|
|
339
|
+
'parseWalletBreakdown. Parsing it here would answer nulls for scores the free route ' +
|
|
340
|
+
'never served.',
|
|
341
|
+
);
|
|
342
|
+
}
|
|
271
343
|
return {
|
|
272
344
|
wallet: payload.wallet,
|
|
273
345
|
finalScore: optNumber(payload.final_score),
|
package/src/types.ts
CHANGED
|
@@ -62,16 +62,32 @@ export type Timestamp = string | null;
|
|
|
62
62
|
*/
|
|
63
63
|
export interface PaymentEvidence {
|
|
64
64
|
/**
|
|
65
|
-
* The settlement
|
|
66
|
-
* was not one
|
|
65
|
+
* The settlement transaction hash, or `null` — when none was served, when
|
|
66
|
+
* what was served was not one (`malformedHashes` tells those two apart), or
|
|
67
|
+
* when the seller answered the literal `pending` (`settlementPending` tells
|
|
68
|
+
* THAT one apart).
|
|
67
69
|
*
|
|
68
70
|
* Validated with its own rule (`hashes.looksLikeSettlementReceipt`) because
|
|
69
|
-
* this is the one field where `"pending"` is a legitimate value
|
|
70
|
-
* OpenAPI declares the header as the settlement transaction hash
|
|
71
|
-
* `pending` if settlement has not reported one"*. Treating
|
|
72
|
-
* would fire an alarm on the happy path of every fresh payment.
|
|
71
|
+
* this is the one field where `"pending"` is a legitimate value on the wire:
|
|
72
|
+
* the live OpenAPI declares the header as the settlement transaction hash
|
|
73
|
+
* *"or `pending` if settlement has not reported one"*. Treating it as
|
|
74
|
+
* garbage would fire an alarm on the happy path of every fresh payment.
|
|
75
|
+
*
|
|
76
|
+
* ⚠️ Legitimate on the WIRE, never in this field — corrected 2026-08-31,
|
|
77
|
+
* from Execution Market's INC-2026-08-26: until then `pending` passed
|
|
78
|
+
* through here, i.e. a placeholder riding in the field meant for the hash,
|
|
79
|
+
* which is exactly what gets archived as proof by anyone who stores this
|
|
80
|
+
* value. Now the sentinel is translated to `null` + `settlementPending:
|
|
81
|
+
* true` at the door, and no consumer ever has to string-compare against it.
|
|
73
82
|
*/
|
|
74
83
|
receipt: string | null;
|
|
84
|
+
/**
|
|
85
|
+
* `true` only when `X-Payment-Receipt` was the literal `pending`: the seller
|
|
86
|
+
* charged and settlement has not reported the hash yet. Not garbage (no
|
|
87
|
+
* mark in `malformedHashes`, no alarm) and not a receipt either. Read the
|
|
88
|
+
* state HERE — `receipt === 'pending'` can no longer be true, on purpose.
|
|
89
|
+
*/
|
|
90
|
+
settlementPending: boolean;
|
|
75
91
|
reused: boolean;
|
|
76
92
|
/**
|
|
77
93
|
* `['receipt']` when the header carried something that is neither a hash nor
|