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/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 *we hold the hash*. `'unknown'` means *ask the chain* —
218
- * never *"nothing happened"*. If you need the stronger answer, the receipt of a
219
- * later successful call and the on-chain transfer to the treasury are where it
220
- * lives; this SDK will not infer it for you.
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 a receipt in hand. See the header of this type. */
232
+ /** `'settled'` only with the seller's statement in hand — a hash, or `pending`. */
224
233
  settlement: 'settled' | 'unknown';
225
- /** `X-Payment-Receipt` — the settlement tx hash, or `"pending"`. */
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
- constructor(status: number, message: string) {
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(server ? 'http_5xx' : 'http_4xx', message, {
406
- // 429 is the one 4xx worth retrying: the 20 rps ceiling is shared with
407
- // every other UVD consumer, so it says "someone else is loud right now",
408
- // not "your request is wrong".
409
- transient: server || status === 429,
410
- // A 4xx is the caller's fault and must NOT vanish into failOpen — except
411
- // 429, which is the shared limit and reads exactly like a brief outage.
412
- serviceFault: server || status === 429,
413
- status,
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 id, or `null` when none was served **or when what was served
66
- * was not one** — `malformedHashes` tells the two apart.
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: the live
70
- * OpenAPI declares the header as the settlement transaction hash *"or
71
- * `pending` if settlement has not reported one"*. Treating that as garbage
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