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/LICENSE +21 -0
- package/README.md +612 -0
- package/dist/client-s3KrgrCt.d.mts +1537 -0
- package/dist/client-s3KrgrCt.d.ts +1537 -0
- package/dist/config-Y2VK_neB.d.mts +169 -0
- package/dist/config-Y2VK_neB.d.ts +169 -0
- package/dist/index.d.mts +488 -0
- package/dist/index.d.ts +488 -0
- package/dist/index.js +1082 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +1038 -0
- package/dist/index.mjs.map +1 -0
- package/dist/partner/index.d.mts +194 -0
- package/dist/partner/index.d.ts +194 -0
- package/dist/partner/index.js +77 -0
- package/dist/partner/index.js.map +1 -0
- package/dist/partner/index.mjs +71 -0
- package/dist/partner/index.mjs.map +1 -0
- package/dist/x402/index.d.mts +91 -0
- package/dist/x402/index.d.ts +91 -0
- package/dist/x402/index.js +29 -0
- package/dist/x402/index.js.map +1 -0
- package/dist/x402/index.mjs +26 -0
- package/dist/x402/index.mjs.map +1 -0
- package/package.json +97 -0
- package/src/caveats.ts +124 -0
- package/src/client.ts +953 -0
- package/src/config.ts +181 -0
- package/src/errors.ts +596 -0
- package/src/format.ts +67 -0
- package/src/hashes.ts +229 -0
- package/src/index.ts +192 -0
- package/src/jitter.ts +112 -0
- package/src/parse.ts +388 -0
- package/src/partner/index.ts +295 -0
- package/src/raters.ts +118 -0
- package/src/recovery.ts +254 -0
- package/src/types.ts +457 -0
- package/src/x402/index.ts +123 -0
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
|
+
}
|