uvd-describe-sdk 0.1.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 ADDED
@@ -0,0 +1,596 @@
1
+ /**
2
+ * The failure taxonomy — and, more importantly, WHICH failures are allowed to
3
+ * disappear.
4
+ *
5
+ * ## Why the names are not new
6
+ *
7
+ * The three live consumers of describe.net each invented their own. Measured
8
+ * on 2026-08-30, they agree on the POLICY (absence is not zero; degrade
9
+ * without taking the caller down) and share not one MECHANISM:
10
+ *
11
+ * * Execution Market raises typed exceptions
12
+ * (`timeout | http_5xx | unreachable | unparseable | partial_index`).
13
+ * * MeshRelay returns null and CACHES the failure, splitting `http_4xx` out
14
+ * of EM's catch-all bucket (`describenet.js:52-58`).
15
+ * * KarmaKadabra falls through to a second source (the facilitator).
16
+ *
17
+ * So there was no de-facto contract to copy — there were three answers to one
18
+ * question, and this SDK had to pick one and defend it. It keeps EM's five
19
+ * `kind` strings verbatim (they are the reference implementation, and the
20
+ * Python SDK mirrors them) and adopts MeshRelay's `http_4xx` split, because an
21
+ * SDK — unlike a reconciler job — has to tell its caller apart from the
22
+ * network. Then it adds the two neither of them has, because neither pays.
23
+ *
24
+ * ## The two axes, and why one boolean was not enough
25
+ *
26
+ * `transient` answers "would retrying help?".
27
+ * `serviceFault` answers "is this describe.net's fault?" — i.e. is this the
28
+ * "describe está caído" that `failOpen` exists for (Saul, 2026-08-28).
29
+ *
30
+ * They are not the same question and collapsing them breaks in both
31
+ * directions. A 422 `not_an_address` is neither: swallowing it under
32
+ * `failOpen` would hide a caller's bug forever behind "this wallet has no
33
+ * reputation" — the exact confusion `null`-never-`0` exists to prevent. A
34
+ * garbled body from a 502-ing proxy IS describe's fault (so `failOpen` covers
35
+ * it) but retrying it immediately is pointless, and MeshRelay measured that:
36
+ * its retry set is `TIMEOUT | HTTP_5XX | UNREACHABLE` and deliberately excludes
37
+ * `UNPARSEABLE` (`describenet.js:161-164`).
38
+ *
39
+ * ## The third axis, added 2026-08-30: was there money in flight?
40
+ *
41
+ * `serviceFault` decides what `failOpen` may swallow — but only on the FREE
42
+ * routes. On a metered route the question never gets asked, because the answer
43
+ * would be irrelevant: a swallowed failure after settlement is a spent
44
+ * credential with no receipt (see `client.ts`, "the paid routes never fail
45
+ * open"). So `DescribeError` gained an optional `payment`, and its mere
46
+ * presence is the statement *"a signed envelope had already left this process
47
+ * when this failed"*. Read it with `failedAfterPaying()`.
48
+ *
49
+ * ## The half the booleans never had, added 2026-08-30: what to do INSTEAD
50
+ *
51
+ * `transient` answers *would retrying help?* and stops there. A `false` leaves
52
+ * the caller holding a failure and no next move, which is how a fleet ends up
53
+ * hammering a door that closed — **Execution Market**, `#agents`, 2026-08-30,
54
+ * measuring their own: *"contra `AUTHORIZATION_EXPIRED` reintentar es quemar
55
+ * llamadas contra una ventana cerrada hace 317 HORAS"*. They typed a `recovery`
56
+ * into their 502 and asked the ecosystem to do the same.
57
+ *
58
+ * So every error carries `recovery`: one sentence naming ANOTHER thing to do —
59
+ * another route (usually a free one), another field, or the condition on the
60
+ * caller's side that has to be fixed. It is `null` when there honestly is none,
61
+ * which is a decision and not an omission. The texts live in `recovery.ts`,
62
+ * frozen, one per kind, and this constructor is the only thing that reads them.
63
+ *
64
+ * 🔴 What was NOT copied is their ten codes — escrow, payout wallets,
65
+ * `AUTHORIZATION_EXPIRED` — because that is their API's vocabulary and this SDK
66
+ * wraps describe.net. The pattern crossed over; the table was re-derived here.
67
+ */
68
+
69
+ import { recoveryFor } from './recovery';
70
+
71
+ /** The closed set. Consumers switch on `kind`, never on `message`. */
72
+ export type DescribeErrorKind =
73
+ /** The request outlived the client timeout — includes provider cold starts. */
74
+ | 'timeout'
75
+ /** describe.net answered 5xx. Its fault, and retryable. */
76
+ | 'http_5xx'
77
+ /**
78
+ * describe.net answered 4xx. Ours, not theirs: 422 `not_an_address` is the
79
+ * common member. 429 (the shared 20 rps) also lands here and is the one 4xx
80
+ * that IS transient — see `transient` on the instance, not on the kind.
81
+ */
82
+ | 'http_4xx'
83
+ /**
84
+ * The route answered 404. **This is data, not a failure** — and it is the
85
+ * one entry of this union that never reaches a caller as a thrown error.
86
+ *
87
+ * R4 is absolute: no exception for "there is no data". A 404 says exactly
88
+ * that, so the method returns its absence value (`null`) whether `failOpen`
89
+ * is on or off — `failOpen` is about outages and this is about absence, two
90
+ * different axes.
91
+ *
92
+ * It is still reported through `onFailure`, and that is deliberate: a
93
+ * mistyped `baseUrl` makes every route 404, and a silent `null` forever
94
+ * would be indistinguishable from "nobody in this index has any reputation".
95
+ * `transient` is false and the kind names itself, so a caller who expects
96
+ * misses can filter it in one line.
97
+ *
98
+ * As of 2026-08-30 no route this SDK wraps returns 404 for a valid input:
99
+ * an unregistered wallet is a **200** with nulls, and a malformed one is a
100
+ * **422**. It is here for the agent route and for whatever the API adds.
101
+ */
102
+ | 'not_found'
103
+ /** Transport died before any status: DNS, connect, reset, CORS, offline. */
104
+ | 'unreachable'
105
+ /** A body arrived and could not be read into the typed shape. */
106
+ | 'unparseable'
107
+ /**
108
+ * The index answered, but its coverage is partial for what was asked.
109
+ *
110
+ * This SDK never raises it — a partial index is served as a 200 whose
111
+ * `chains[]` simply lacks rows, which is data. It exists so a caller that
112
+ * DETECTS partial coverage (a chain it writes to that the index does not
113
+ * scan) can classify it inside the same taxonomy instead of inventing a
114
+ * sixth one. Kept for parity with EM's reference (`types.py:82-92`).
115
+ */
116
+ | 'partial_index'
117
+ /**
118
+ * A metered route answered 402 and this client has no `payer` configured.
119
+ *
120
+ * Protocol, not absence: the index is up and told us its price. Never
121
+ * swallowed by `failOpen` — a caller who forgot to wire a payer must find
122
+ * out, and the challenge is attached so they can read the price without
123
+ * paying (asking is free, and is the intended first move).
124
+ */
125
+ | 'payment_required'
126
+ /**
127
+ * A 402 challenge named a `payTo` that is not the pinned treasury.
128
+ *
129
+ * `DO_NOT_PAY`. Never a retry, never `failOpen`-able: the one failure where
130
+ * continuing quietly costs real USDC to a stranger.
131
+ */
132
+ | 'payment_refused'
133
+ /**
134
+ * A hash field arrived carrying something that is not a hash.
135
+ *
136
+ * 🔴 **Never thrown.** It travels only through `onFailure`, and the class that
137
+ * carries it says so in its own first line — see {@link DescribeMalformedHash}.
138
+ * Branch on this `kind`, never on a `catch` that will not fire.
139
+ */
140
+ | 'malformed_hash'
141
+ /**
142
+ * Partner mode is configured and the signature could not be produced AT ALL.
143
+ *
144
+ * The CALLER's configuration, not describe.net's: an unset env var, a signer
145
+ * that refuses, a wallet that is locked. `serviceFault: false`, so `failOpen`
146
+ * never swallows it — on a free route either. A partner client that silently
147
+ * loses its signature is a partner client that silently starts paying, and
148
+ * that is the whole failure this rail exists to make impossible.
149
+ */
150
+ | 'partner_unsigned'
151
+ /**
152
+ * We signed, and describe.net charged anyway.
153
+ *
154
+ * The signature was produced and sent, and the metered route still answered
155
+ * 402 — so the gate did not exempt us. Measured causes, in the order they
156
+ * happen in real life (`describe-net/describenet/partner.py`):
157
+ *
158
+ * * the wallet is not in the allowlist (`partner.py:242`), i.e. nobody has
159
+ * added this partner yet — Execution Market is registered, KarmaKadabra
160
+ * and MeshRelay are NOT, as of 2026-08-30;
161
+ * * the signed `@authority` is not `api.describe.net` (`partner.py:84`) —
162
+ * which is what a custom `baseUrl` produces, including the raw
163
+ * execute-api host behind CloudFront, deliberately;
164
+ * * the keyid's chain is not 8453 (`partner.py:90`);
165
+ * * the clock is off by more than 30 s ahead or the signature is older than
166
+ * 300 s (`partner.py:95-96`).
167
+ *
168
+ * `payment` is ABSENT and that is load-bearing: nothing was signed, nothing
169
+ * was sent, nothing was spent. This error is the moment BEFORE the money.
170
+ */
171
+ | 'partner_rejected';
172
+
173
+ /**
174
+ * What this SDK can honestly say about the USDC when a metered call fails.
175
+ *
176
+ * ## Why an object and not a boolean
177
+ *
178
+ * A bare `DescribeTimeout` cannot tell "it died before we paid" (you spent
179
+ * nothing) from "it died after" (you may have spent and got nothing back).
180
+ * Those are different conversations — the first is a retry, the second is a
181
+ * reconciliation — and the exception has to carry which one it is.
182
+ *
183
+ * ## The rule, and it is the whole point of this type
184
+ *
185
+ * **`error.payment` exists ⇔ a signed `X-PAYMENT` envelope had already left
186
+ * this process.** Its ABSENCE on a metered failure is therefore itself an
187
+ * answer: nothing was transmitted, so nothing could have settled. That covers
188
+ * the 402 with no payer, the `DO_NOT_PAY` refusal, the 404 (which arrives
189
+ * before any challenge is even read), and a payer that threw while signing —
190
+ * an EIP-3009 authorization that never leaves the payer moves no money, because
191
+ * money moves when the SELLER submits it, not when the buyer signs it.
192
+ *
193
+ * ## `settlement`, and the one thing it will not do is guess
194
+ *
195
+ * `'settled'` is asserted only against proof in hand: `X-Payment-Receipt`, whose
196
+ * value is the settlement transaction hash (or the literal `"pending"`). Read on
197
+ * 2026-08-30 in the service's own middleware —
198
+ * `describe-net/describenet/paywall.py:1031-1065` — the paywall settles inside
199
+ * `authorize()` **before** `call_next(request)` runs the handler, and then
200
+ * attaches the receipt headers to whatever response comes back. A non-2xx
201
+ * response with a receipt is therefore a settlement that happened, stated by the
202
+ * seller.
203
+ *
204
+ * `'unknown'` is everything else, and it is honest rather than pessimistic. Two
205
+ * measured holes forbid upgrading it to a verdict:
206
+ *
207
+ * 1. **A 500 can be settled and carry no receipt.** If the handler raises,
208
+ * Starlette's `ServerErrorMiddleware` — which sits OUTSIDE the paywall
209
+ * middleware, verified 2026-08-30: `api.py:2110` is the only
210
+ * `add_middleware` for it and `api.py` registers no exception handler —
211
+ * answers 500 without the header line ever running. The money moved in
212
+ * `authorize()` regardless.
213
+ * 2. **A dead socket proves nothing.** `fetch` rejects the same way whether
214
+ * the connection died before the request bytes were written or while the
215
+ * response was coming back.
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.
221
+ */
222
+ export interface PaymentAttempt {
223
+ /** `'settled'` only with a receipt in hand. See the header of this type. */
224
+ settlement: 'settled' | 'unknown';
225
+ /** `X-Payment-Receipt` — the settlement tx hash, or `"pending"`. */
226
+ receipt: string | null;
227
+ /** `X-Payment-Reused: true` means an earlier receipt was replayed, no new charge. */
228
+ reused: boolean | null;
229
+ /** The status of the answer that failed, when an answer arrived at all. */
230
+ status?: number;
231
+ /** What the challenge asked for. Copied, never re-priced. */
232
+ amount?: string;
233
+ token?: string;
234
+ /** The recipient we verified against the pinned treasury before signing. */
235
+ payTo?: string;
236
+ }
237
+
238
+ export class DescribeError extends Error {
239
+ readonly kind: DescribeErrorKind;
240
+ /** Would retrying help? Drives backoff, never `failOpen`. */
241
+ readonly transient: boolean;
242
+ /** Is this describe.net's fault? Drives `failOpen`, never retry. */
243
+ readonly serviceFault: boolean;
244
+ /** Present when a status was actually received. */
245
+ readonly status?: number;
246
+ /**
247
+ * What to do INSTEAD, in one sentence — or `null` when there honestly is
248
+ * nothing beyond the retry `transient` already announces (`timeout` is the
249
+ * one, and `recovery.ts` says why at the entry).
250
+ *
251
+ * 🔴 **Branch on `kind`, read this.** It is prose meant for a human or an
252
+ * agent, it is free to be re-worded, and matching on it is the mistake the
253
+ * caveat codes exist to prevent one level up.
254
+ *
255
+ * 🔴 It is always one of the frozen literals in `recovery.ts` — never built
256
+ * from a message, a URL or a `cause`. That is the redaction guard: a
257
+ * transport exception can carry an endpoint with an API key in it, and this
258
+ * is the string most likely to end up pasted into a ticket.
259
+ */
260
+ readonly recovery: string | null;
261
+ /**
262
+ * Set **only** when a signed envelope was already in flight. Not readonly for
263
+ * one reason: the failure is built deep in the transport, which knows nothing
264
+ * about payment, and `attachPayment()` stamps it on the way out. Treat it as
265
+ * readonly — nothing in this package writes it twice.
266
+ */
267
+ payment?: PaymentAttempt;
268
+
269
+ constructor(
270
+ kind: DescribeErrorKind,
271
+ message: string,
272
+ opts: { transient: boolean; serviceFault: boolean; status?: number; cause?: unknown } = {
273
+ transient: false,
274
+ serviceFault: false,
275
+ },
276
+ ) {
277
+ super(message, { cause: opts.cause });
278
+ this.name = 'DescribeError';
279
+ this.kind = kind;
280
+ this.transient = opts.transient;
281
+ this.serviceFault = opts.serviceFault;
282
+ this.status = opts.status;
283
+ // Derived here and NOWHERE else: every subclass gets its recovery from the
284
+ // same table by construction, so none can forget one, invent one, or build
285
+ // one out of a string that came from outside this package. The status is
286
+ // passed for the single case where a kind is not fine enough — 429, the one
287
+ // 4xx that is not the caller's bug.
288
+ this.recovery = recoveryFor(kind, opts.status);
289
+ }
290
+ }
291
+
292
+ export class DescribeTimeout extends DescribeError {
293
+ constructor(message: string, cause?: unknown) {
294
+ super('timeout', message, { transient: true, serviceFault: true, cause });
295
+ this.name = 'DescribeTimeout';
296
+ }
297
+ }
298
+
299
+ export class DescribeUnreachable extends DescribeError {
300
+ constructor(message: string, cause?: unknown) {
301
+ super('unreachable', message, { transient: true, serviceFault: true, cause });
302
+ this.name = 'DescribeUnreachable';
303
+ }
304
+ }
305
+
306
+ export class DescribeUnparseable extends DescribeError {
307
+ constructor(message: string, cause?: unknown) {
308
+ // serviceFault: they answered and the answer was unreadable — that is on
309
+ // them, so failOpen covers it. NOT transient: MeshRelay measured that
310
+ // retrying an unparseable body buys nothing (`describenet.js:161-164`).
311
+ super('unparseable', message, { transient: false, serviceFault: true, cause });
312
+ this.name = 'DescribeUnparseable';
313
+ }
314
+ }
315
+
316
+ /**
317
+ * A hash field arrived with something that is not a hash.
318
+ *
319
+ * Contributed by **KarmaKadabra** (`#agents`, 2026-08-30), out of the finding
320
+ * they call *"el 200 sin tx"*: *"si nosotros no chequeáramos el tx, habríamos
321
+ * contado 14 ratings que no existen"*. A 200 that did not do the thing is worse
322
+ * than a 503, because the client takes it for good.
323
+ *
324
+ * 🔴 **THIS IS NEVER THROWN. Do not write a `catch` for it.** It travels only as
325
+ * the `error` of a {@link DescribeFailure} handed to `onFailure`, and it exists
326
+ * as a class for one mechanical reason: that channel is typed
327
+ * `DescribeError`, so reusing the channel the consumer is ALREADY watching —
328
+ * which is what KarmaKadabra asked for — requires the fact to BE a
329
+ * `DescribeError`. Branch on `kind === 'malformed_hash'` or on `instanceof`,
330
+ * never on a `try/catch` that will not fire.
331
+ *
332
+ * ⚠️ There is a tension with this taxonomy and it is declared rather than
333
+ * papered over: `partial_index` is also documented as never raised, and it is
334
+ * kept only for parity with Execution Market's reference. Publishing exceptions
335
+ * nobody throws invites dead `catch` blocks. What separates the two is what the
336
+ * class is FOR: `partial_index` exists so someone can catch it and nobody will,
337
+ * this one exists to ride a channel that is already typed, and its first line
338
+ * shouts as much. If `onFailure` ever accepts something wider than a
339
+ * `DescribeError`, this class stops being necessary.
340
+ *
341
+ * Why the failure does NOT take the read down: the rest of the response is very
342
+ * likely useful, and killing a whole reputation breakdown over an accessory
343
+ * field would be worse than the bug being hunted — especially on a metered
344
+ * route, where the read has already been paid for. The typed field is left
345
+ * `null` so nobody builds an explorer link out of garbage, and the raw value
346
+ * survives in the result's `raw`, which is where it gets investigated.
347
+ *
348
+ * 🔴 **Absent and malformed are NOT the same thing, and the result keeps them
349
+ * apart** (R1, one level below where it usually lives):
350
+ *
351
+ * ```
352
+ * rating.txHash === null, malformedHashes empty → IT DID NOT COME
353
+ * rating.txHash === null, 'tx_hash' in malformedHashes → GARBAGE CAME
354
+ * ```
355
+ *
356
+ * `fields` carries the location of each one, with an index when it is inside a
357
+ * list: `['ratings[3].tx_hash', 'snapshot.inputs_digest']`. Wire names, not
358
+ * ours, because this string ends up in a ticket to whoever runs the index.
359
+ *
360
+ * `serviceFault` is **false** even though the bad data is describe.net's: this
361
+ * flag drives `failOpen`, and a read that succeeded has nothing to fail open
362
+ * INTO. `transient` is false for the same kind of reason — the same request will
363
+ * bring the same bad field back.
364
+ */
365
+ export class DescribeMalformedHash extends DescribeError {
366
+ /** Qualified paths of the fields that arrived malformed, in order. */
367
+ readonly fields: string[];
368
+ constructor(message: string, fields: string[]) {
369
+ super('malformed_hash', message, { transient: false, serviceFault: false });
370
+ this.name = 'DescribeMalformedHash';
371
+ this.fields = [...fields];
372
+ }
373
+ }
374
+
375
+ /**
376
+ * 404 — absence.
377
+ *
378
+ * ⚠️ **CORRECTED 2026-08-30, and the old text is left below because somebody
379
+ * will come looking for it.** It used to say: *"`DescribeClient.guard` converts
380
+ * it to `null` before any caller sees it, which is why this class is not
381
+ * exported from the package index: 'a 404 never reaches the caller as an error'
382
+ * is structural here"*. That stopped being true when the metered methods lost
383
+ * their `| null` return: `walletBreakdown()` and `agent()` have no absence value
384
+ * left to degrade INTO, so on those two routes a 404 arrives as this exception,
385
+ * and the class is now exported so `instanceof` works.
386
+ *
387
+ * On the free routes nothing changed — still `null`, still announced through
388
+ * `onFailure`, still regardless of `failOpen`.
389
+ *
390
+ * Absence did not become a failure; it changed clothes. It keeps
391
+ * `transient: false`, `serviceFault: false`, and — the load-bearing part — **no
392
+ * `payment`**: a metered 404 is checked before the challenge is even read, so
393
+ * nothing was signed and nothing was spent to learn that there is nothing there.
394
+ */
395
+ export class DescribeNotFound extends DescribeError {
396
+ constructor(message: string) {
397
+ super('not_found', message, { transient: false, serviceFault: false, status: 404 });
398
+ this.name = 'DescribeNotFound';
399
+ }
400
+ }
401
+
402
+ export class DescribeHTTPError extends DescribeError {
403
+ constructor(status: number, message: string) {
404
+ 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
+ });
415
+ this.name = 'DescribeHTTPError';
416
+ }
417
+ }
418
+
419
+ /** The parsed 402, as served. Kept raw: we read it, we never re-price it. */
420
+ export interface X402Challenge {
421
+ /** Human price, e.g. `"0.01"`. From the challenge — never typed by us. */
422
+ amount?: string;
423
+ /** Default recipient. Checked against the pinned treasury before paying. */
424
+ recipient?: string;
425
+ recipients?: Record<string, string | undefined>;
426
+ token?: string;
427
+ supportedChains?: number[];
428
+ accepts?: Array<Record<string, unknown>>;
429
+ /** Everything else the challenge carried, untouched (passthrough rule). */
430
+ [key: string]: unknown;
431
+ }
432
+
433
+ export class DescribePaymentRequired extends DescribeError {
434
+ readonly challenge: X402Challenge;
435
+ constructor(message: string, challenge: X402Challenge) {
436
+ super('payment_required', message, { transient: false, serviceFault: false, status: 402 });
437
+ this.name = 'DescribePaymentRequired';
438
+ this.challenge = challenge;
439
+ }
440
+ }
441
+
442
+ export class DescribePaymentRefused extends DescribeError {
443
+ readonly challenge: X402Challenge;
444
+ readonly expected: string;
445
+ readonly offered: string | undefined;
446
+ constructor(expected: string, offered: string | undefined, challenge: X402Challenge) {
447
+ super(
448
+ 'payment_refused',
449
+ `DO_NOT_PAY: the 402 challenge asks to pay ${offered ?? '(no recipient)'}, ` +
450
+ `not the pinned treasury ${expected}. Nothing was signed.`,
451
+ { transient: false, serviceFault: false, status: 402 },
452
+ );
453
+ this.name = 'DescribePaymentRefused';
454
+ this.challenge = challenge;
455
+ this.expected = expected;
456
+ this.offered = offered;
457
+ }
458
+ }
459
+
460
+ /**
461
+ * Partner mode is on and the signature could not be produced.
462
+ *
463
+ * ## Why this THROWS instead of quietly paying, on every route
464
+ *
465
+ * The alternative is the one thing a partner rail must never do. Without a
466
+ * signature the request is an ordinary anonymous request: describe.net answers
467
+ * 402 on a metered route and the configured payer settles it, in USDC, silently
468
+ * — the consumer keeps getting answers and only finds out at the invoice. Saul
469
+ * asked for a rail where our own products read for free; a rail that degrades
470
+ * into paying is not that rail, it is a bill.
471
+ *
472
+ * So this is a CALLER-fault error (`serviceFault: false`), which means
473
+ * `failOpenCovers()` is `false` for it and `failOpen: true` does not swallow it
474
+ * — not even on the free routes, where the signature costs nothing and buys
475
+ * nothing. That is deliberate and not an oversight: a partner whose signer is
476
+ * broken on `/health` has the same broken signer on
477
+ * `/reputation/wallet/{w}` thirty seconds later, and the free call is the
478
+ * cheapest possible place to find out.
479
+ *
480
+ * It carries no `payment` — nothing was sent, so nothing could have settled.
481
+ *
482
+ * 🔴 `cause` is the signer's own error and this class never reads it, never
483
+ * reformats it and never puts it in `message`. A signer that fails on a
484
+ * malformed key can have key material inside its exception (measured: see
485
+ * `partner/index.ts`, the ethers `invalid BytesLike value` finding), and this
486
+ * SDK will not be the thing that copies it into a log line.
487
+ */
488
+ export class DescribePartnerUnsigned extends DescribeError {
489
+ /** The signing address, when the signer published one. Public by design. */
490
+ readonly address: string | undefined;
491
+ constructor(path: string, address: string | undefined, cause: unknown) {
492
+ super(
493
+ 'partner_unsigned',
494
+ `Partner mode is configured but signing GET ${path} failed` +
495
+ `${address ? ` for ${address}` : ''}. This is a CALLER configuration ` +
496
+ 'failure, and it is raised rather than downgraded on purpose: without a ' +
497
+ 'signature this client is an anonymous client, and an anonymous client ' +
498
+ 'PAYS. Read `error.cause` for the signer\'s own error.',
499
+ { transient: false, serviceFault: false, cause },
500
+ );
501
+ this.name = 'DescribePartnerUnsigned';
502
+ this.address = address;
503
+ }
504
+ }
505
+
506
+ /**
507
+ * We signed as a partner and describe.net asked for money anyway.
508
+ *
509
+ * ## The case this class exists for, and it is the important one
510
+ *
511
+ * A partner client that gets a 402 has lost its free rail. If it falls through
512
+ * to the payer, the fall is invisible: same answers, same latency, same shape —
513
+ * and USDC leaving a wallet that budgeted none. The alternative failure (a loud
514
+ * throw) costs one broken read and a fixable configuration; the silent one costs
515
+ * money for as long as nobody looks.
516
+ *
517
+ * So partner mode does NOT pay by default. `partnerFallsBackToPaying: true`
518
+ * turns it back on as an explicit, typed decision by the caller — the flag
519
+ * exists so that "pay anyway" is something someone WROTE, never something that
520
+ * happened.
521
+ *
522
+ * The challenge is attached unpaid, so a caller who decides to pay after all can
523
+ * read exactly what it would have cost. And `payment` is absent: this is thrown
524
+ * before `payer.pay()` is ever reached, so nothing was signed and nothing moved.
525
+ */
526
+ export class DescribePartnerRejected extends DescribeError {
527
+ readonly challenge: X402Challenge;
528
+ /** The address we signed with. Public by design — the allowlist is public. */
529
+ readonly address: string | undefined;
530
+ constructor(path: string, address: string | undefined, challenge: X402Challenge) {
531
+ super(
532
+ 'partner_rejected',
533
+ `GET ${path} answered 402 even though this client signed it as a partner` +
534
+ `${address ? ` with ${address}` : ''}. The free rail is NOT active: the ` +
535
+ 'address may not be in describe.net\'s allowlist, the signed @authority ' +
536
+ 'may not be api.describe.net (a custom baseUrl does that), the keyid ' +
537
+ 'chain may not be 8453, or the clock may be off. NOTHING WAS PAID — ' +
538
+ 'this throw is what stops a partner from silently spending USDC. Read ' +
539
+ '`error.challenge` for the price, or set `partnerFallsBackToPaying: true` ' +
540
+ 'to pay on purpose.',
541
+ { transient: false, serviceFault: false, status: 402 },
542
+ );
543
+ this.name = 'DescribePartnerRejected';
544
+ this.challenge = challenge;
545
+ this.address = address;
546
+ }
547
+ }
548
+
549
+ /**
550
+ * Does `failOpen` cover this failure?
551
+ *
552
+ * The single predicate, so the rule lives in one place instead of being
553
+ * re-derived at each call site. Saul's words were "pon un fallback si es que
554
+ * describe está caído" — `serviceFault` is the typed form of "está caído", and
555
+ * nothing else qualifies.
556
+ *
557
+ * ⚠️ **Corrected 2026-08-30 — this predicate answers a smaller question than it
558
+ * used to.** It was the ONLY gate: every method ran its failure through it, so
559
+ * `walletBreakdown()` and `agent()` returned `null` on any `serviceFault`,
560
+ * including a timeout that arrived AFTER settlement. That is a spent credential
561
+ * with no receipt, and the caller never learned they had paid. The rule now has
562
+ * a term this predicate cannot see — *was there money in flight* — so the
563
+ * metered methods never call it at all. It is still exported, and calling it
564
+ * yourself on a paid failure answers a question you should not be asking: use
565
+ * `failedAfterPaying()` instead.
566
+ */
567
+ export function failOpenCovers(error: unknown): error is DescribeError {
568
+ return error instanceof DescribeError && error.serviceFault;
569
+ }
570
+
571
+ /**
572
+ * Did this failure happen with a signed envelope already in flight?
573
+ *
574
+ * `true` means the money MAY have moved and you should reconcile; read
575
+ * `error.payment` for the receipt (proof) or the `'unknown'` that says the SDK
576
+ * cannot tell. `false` means nothing was transmitted — a 402 with no payer, a
577
+ * `DO_NOT_PAY`, a 404, a payer that declined, or any failure on a free route.
578
+ */
579
+ export function failedAfterPaying(
580
+ error: unknown,
581
+ ): error is DescribeError & { payment: PaymentAttempt } {
582
+ return error instanceof DescribeError && error.payment !== undefined;
583
+ }
584
+
585
+ /**
586
+ * Stamp a failure with what we know about the payment, on its way out.
587
+ *
588
+ * Internal: `client.ts` is the only caller, because it is the only place that
589
+ * knows where the envelope was when things broke. Non-`DescribeError` throws
590
+ * pass through untouched — a payer that throws its own `Error` is not ours to
591
+ * annotate, and it never got as far as sending anything anyway.
592
+ */
593
+ export function attachPayment(error: unknown, attempt: PaymentAttempt): unknown {
594
+ if (error instanceof DescribeError) error.payment = attempt;
595
+ return error;
596
+ }
package/src/format.ts ADDED
@@ -0,0 +1,67 @@
1
+ /**
2
+ * How a score is written down. One rule, ecosystem-wide.
3
+ *
4
+ * **Two decimals, trailing zeros trimmed.** `86.65`, `84.7`, `87` — never `82.0`.
5
+ *
6
+ * Fixed on 2026-08-29 after the three consumers each rendered the SAME number
7
+ * differently (`86.653045`, `86.7`, `86` — one field, three strings), and
8
+ * decided by measurement rather than taste: over 47 real distinct scores,
9
+ * rounding to 0 decimals merges 23 pairs of *different* agents into identical
10
+ * strings, 1 decimal merges 4, and 2 decimals merges 1. Trimming matters as
11
+ * much as the count — two surfaces both "agreeing on 1 decimal" still printed
12
+ * `82.0` and `82` for the same agent.
13
+ *
14
+ * The canonical one-liner, byte-identical across the two languages
15
+ * (`docs.describe.net`, §"Displaying a score"):
16
+ *
17
+ * ```js
18
+ * String(parseFloat(x.toFixed(2))) // JavaScript
19
+ * ```
20
+ * ```python
21
+ * f"{round(x, 2):g}" # Python
22
+ * ```
23
+ *
24
+ * **Live witness case**: the agent scored `83.0` renders as `83` on all three
25
+ * surfaces — where `toFixed(2)` alone prints `83.00` and `toFixed(1)` prints
26
+ * `83.0`. It is the one value that tells the three candidate rules apart, which
27
+ * is why `format.test.ts` tests it first.
28
+ *
29
+ * This is a DISPLAY convention. The API keeps serving the full-precision number
30
+ * (six decimals) and what you compute with is the number, never the string —
31
+ * which is why the two functions below are separate and why `formatScore`
32
+ * returns a `string`. A helper that rounded the number in place would push a
33
+ * lossy value back into arithmetic, and averaging rounded members is how an
34
+ * aggregate ends up disagreeing with the members it aggregates.
35
+ */
36
+
37
+ /**
38
+ * The canonical display string, or `null` when there is nothing to display.
39
+ *
40
+ * `null` in, `null` out — never `"0"`, never `"—"`. Choosing the placeholder
41
+ * for absence is the surface's job and it is a different decision per surface;
42
+ * inventing one here would put this package's taste into every consumer, and
43
+ * `"0"` in particular would publish "worst possible reputation" for "nobody has
44
+ * rated this yet" (invariante 7 of the index, and R1 of this SDK).
45
+ *
46
+ * A non-finite input (a `NaN` from a malformed payload) is also `null`: a
47
+ * number we cannot name is not a number we may put describe.net's name on.
48
+ */
49
+ export function formatScore(value: number | null | undefined): string | null {
50
+ if (typeof value !== 'number' || !Number.isFinite(value)) return null;
51
+ return String(parseFloat(value.toFixed(2)));
52
+ }
53
+
54
+ /**
55
+ * The same rounding, kept as a `number`.
56
+ *
57
+ * For the one case where a number is what you need: MeshRelay rounds at the
58
+ * boundary where the value ENTERS the system rather than at each surface,
59
+ * because "the bug this closes is one number rendering differently in two
60
+ * places" (`describenet.js:204-208`). If you do that, use this — and be aware
61
+ * you have made the value lossy on purpose. Everything else should carry the
62
+ * full-precision number and call `formatScore` at the pixel.
63
+ */
64
+ export function roundScore(value: number | null | undefined): number | null {
65
+ if (typeof value !== 'number' || !Number.isFinite(value)) return null;
66
+ return parseFloat(value.toFixed(2));
67
+ }