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.
@@ -0,0 +1,488 @@
1
+ import { D as DescribeErrorKind, P as PaymentEvidence, A as AgentReputation, I as IndexHealth, L as LeaderboardRow, W as WalletBreakdown, a as WalletReputation } from './client-s3KrgrCt.js';
2
+ export { b as Activity, C as CAVEAT_CODES, c as CAVEAT_SCOPE_FREE, d as CAVEAT_SCOPE_METERED, e as Caveat, f as CaveatCode, g as Concentration, h as Confidence, i as DescribeClient, j as DescribeClientConfig, k as DescribeError, l as DescribeFailure, m as DescribeHTTPError, n as DescribeMalformedHash, o as DescribeNotFound, p as DescribePartnerRejected, q as DescribePartnerUnsigned, r as DescribePaymentRefused, s as DescribePaymentRequired, t as DescribeTimeout, u as DescribeUnparseable, v as DescribeUnreachable, F as Facet, H as HealthChain, K as KnownCaveatCode, N as Network, O as Ownership, w as PartnerSigner, x as PaymentAttempt, R as Rating, S as Sealed, y as SelfRated, z as Snapshot, T as Timestamp, B as WalletChainRow, X as X402Challenge, E as X402Payer, G as failOpenCovers, J as failedAfterPaying, M as hasCaveat, Q as isKnownCaveatCode } from './client-s3KrgrCt.js';
3
+ export { D as DEFAULT_BASE_URL, a as DEFAULT_JITTER_MS, b as DEFAULT_SITE_URL, c as DEFAULT_TIMEOUT_MS, P as PARTNER_CHAIN_ID, d as PARTNER_KEY_ENV, S as SDK_NAME, e as SDK_VERSION, T as TREASURY_EVM, u as userAgent } from './config-Y2VK_neB.js';
4
+
5
+ /**
6
+ * What to do INSTEAD โ€” the sentence `transient` cannot say.
7
+ *
8
+ * ## Where this came from, and it is not ours
9
+ *
10
+ * Contributed by **Execution Market** in `#agents` on **2026-08-30**, out of
11
+ * their own 502 body gaining `detail.code`, `detail.retryable` and
12
+ * `detail.recovery` with ten typed codes โ€” *"para que lo codifiquen de su
13
+ * lado"*. Their argument is the measurement that justifies this whole file:
14
+ *
15
+ * > *"SIETE de los diez son TERMINALES (`retryable: false`). Eso es lo que mรกs
16
+ * > les sirve: hoy su flota no puede distinguir 'reintenta' de 'no insistas', y
17
+ * > contra `AUTHORIZATION_EXPIRED` reintentar es quemar llamadas contra una
18
+ * > ventana cerrada hace **317 HORAS**."*
19
+ *
20
+ * 317 hours of retries against a door that closed is the cost of having only
21
+ * the boolean. Measured on our side the same day, before this file existed:
22
+ * `grep -rc recovery src/` was **0** in both SDKs, while `transient` and
23
+ * `serviceFault` were already on every error. So we had exactly half of it โ€” we
24
+ * could say whether retrying helps, and had no way at all to say what to do
25
+ * when it does not. A boolean that says "no" leaves the caller stuck; a
26
+ * sentence that names another door lets them keep going.
27
+ *
28
+ * ๐Ÿ”ด **What was deliberately NOT absorbed: their ten codes.**
29
+ * `AUTHORIZATION_EXPIRED`, escrow, release-to-worker, payout wallets โ€” that is
30
+ * Execution Market's API, and this SDK does not wrap it. It wraps describe.net,
31
+ * which holds no escrow and expires no authorization of its own. A consumer
32
+ * branching on `AUTHORIZATION_EXPIRED` against this index would be writing dead
33
+ * code against a domain we do not touch. The **pattern** is the contribution;
34
+ * the table below is ours and had to be re-derived failure by failure.
35
+ *
36
+ * ## Why a sentence, and not a second enum
37
+ *
38
+ * The machine-readable axis already exists and is `kind` โ€” plus `transient`
39
+ * ("would retrying help?") and `serviceFault` ("is this describe.net's
40
+ * fault?"). A `recoveryCode` enum would be a SECOND taxonomy over the same
41
+ * failures, kept in sync by hand, and consumers would start branching on it
42
+ * instead of on `kind`; the day the two disagree, the branch that fires is the
43
+ * wrong one. What was missing is not another thing to switch on, it is the
44
+ * paragraph a human (or an agent reading its own exception) needs in order to
45
+ * do something else.
46
+ *
47
+ * ๐Ÿ”ด So: **branch on `kind`, read `recovery`.** Never parse it, never match on
48
+ * it โ€” same contract the caveats carry, where `code` is frozen and the text is
49
+ * free to be re-written (`caveats.ts`, and describe.net's own rule: *"EL TEXTO
50
+ * puede cambiar sin aviso; EL CODE jamรกs"*). The stability a test needs comes
51
+ * from the strings living HERE, once, exported: pin `RECOVERY.payment_required`
52
+ * and the assertion cannot rot into a prose match.
53
+ *
54
+ * ## ๐Ÿ”ด The rule that keeps an empty one honest
55
+ *
56
+ * **A recovery that does not work is worse than no recovery**, because it sends
57
+ * the caller to do something useless with confidence โ€” which is the same shape
58
+ * as the 317 hours, one level up. So a `null` here is a decision that was made,
59
+ * not a field somebody forgot: `timeout` has one and its reasoning is written
60
+ * at the entry.
61
+ *
62
+ * And a recovery is never "retry" in other words โ€” `transient` already says
63
+ * that, and repeating it would be the second copy of a fact this package keeps
64
+ * in one place. Every entry names something ELSE: another route, another field,
65
+ * another mode, or the condition on the caller's side that has to be fixed.
66
+ *
67
+ * ## ๐Ÿ”ด Every string in this file is a literal, and that IS the redaction guard
68
+ *
69
+ * Execution Market's other warning of the same day: an unclassified error *"can
70
+ * carry an RPC URL with its API key inside"*, and they added a test with a fake
71
+ * secret that fails if it leaks. The service side of the house has had that
72
+ * guard for a while โ€” `describe-net/describenet/chain/rpc.py::_redact` replaces
73
+ * the endpoint with `<rpc-url>` in anything about to be logged or raised,
74
+ * because the key lives in the URL path.
75
+ *
76
+ * The SDK equivalent is structural rather than a filter: **this module holds
77
+ * nothing but frozen literals and interpolates nothing.** `recoveryFor()` picks
78
+ * one by key; no call site builds a recovery out of a message, a URL, a cause,
79
+ * or any other string that came from outside this file. A filter can be
80
+ * forgotten at one call site; a table has no call site to forget.
81
+ *
82
+ * That boundary is drawn where it is on purpose, and the neighbouring field is
83
+ * the contrast: `DescribeUnreachable`'s `message` DOES quote `String(error)`,
84
+ * because a transport failure with the cause stripped out is undebuggable. The
85
+ * message is forensic and belongs to whoever is reading the exception; the
86
+ * recovery is advice this package WROTE and is the string most likely to be
87
+ * copied into a log line, a ticket or a Slack message. `recovery.test.ts`
88
+ * mounts a fetch that throws a URL carrying a fake key and asserts the recovery
89
+ * comes back byte-identical to the table.
90
+ *
91
+ * ## ๐Ÿ”ด Parity: what a recovery text is allowed to name
92
+ *
93
+ * The Python SDK ships the same field with the same name and the SAME text, so
94
+ * a consumer who moves stacks does not read two different pieces of advice for
95
+ * one failure. That is only possible if a text names things BOTH SDKs share:
96
+ * HTTP routes, headers, wire fields, env vars, chain ids, and the numbers the
97
+ * service publishes. It may NOT name a language-specific spelling โ€” this
98
+ * package's `jitterMs` is the Python package's `jitter` and it is in SECONDS
99
+ * (see the README's parity note), so a text naming it would have to be either
100
+ * different or wrong. Options are therefore described by what they do, and the
101
+ * caller finds the spelling in their own SDK, one line away.
102
+ */
103
+
104
+ /**
105
+ * The keys of the table.
106
+ *
107
+ * Every `kind`, plus `rate_limited` โ€” the one place where a kind is not fine
108
+ * enough. A 429 and a 422 are both `http_4xx`, and their recoveries are
109
+ * opposites: one says *this is your input, fix it*, the other says *this is not
110
+ * your request at all, spread your fleet*. Merging them would produce a
111
+ * paragraph that is wrong for both, which is exactly the mush this file exists
112
+ * to avoid. The split lives in `recoveryFor()`, on the same `status === 429`
113
+ * condition that already decides `transient` in `DescribeHTTPError`.
114
+ */
115
+ type RecoveryKey = DescribeErrorKind | 'rate_limited';
116
+ /**
117
+ * The frozen table. One entry per {@link RecoveryKey}, `null` where there is
118
+ * honestly no other door.
119
+ *
120
+ * The `Record` annotation is half the guard: a `kind` added to the union
121
+ * without an entry here does not compile. The other half is
122
+ * `recovery.test.ts`, which walks every kind at runtime.
123
+ */
124
+ declare const RECOVERY: Readonly<Record<RecoveryKey, string | null>>;
125
+ /**
126
+ * The recovery for one failure, or `null` when there honestly is none.
127
+ *
128
+ * Called from exactly one place โ€” the `DescribeError` constructor โ€” so every
129
+ * error in this package gets its recovery from the same table by construction,
130
+ * and a subclass cannot forget to pass one or invent one of its own.
131
+ *
132
+ * `status` is read for one case only: 429 is the single 4xx that is not the
133
+ * caller's bug, and it takes the `rate_limited` entry. Same condition that
134
+ * already decides `transient` one file over.
135
+ */
136
+ declare function recoveryFor(kind: DescribeErrorKind, status?: number): string | null;
137
+
138
+ /**
139
+ * How a score is written down. One rule, ecosystem-wide.
140
+ *
141
+ * **Two decimals, trailing zeros trimmed.** `86.65`, `84.7`, `87` โ€” never `82.0`.
142
+ *
143
+ * Fixed on 2026-08-29 after the three consumers each rendered the SAME number
144
+ * differently (`86.653045`, `86.7`, `86` โ€” one field, three strings), and
145
+ * decided by measurement rather than taste: over 47 real distinct scores,
146
+ * rounding to 0 decimals merges 23 pairs of *different* agents into identical
147
+ * strings, 1 decimal merges 4, and 2 decimals merges 1. Trimming matters as
148
+ * much as the count โ€” two surfaces both "agreeing on 1 decimal" still printed
149
+ * `82.0` and `82` for the same agent.
150
+ *
151
+ * The canonical one-liner, byte-identical across the two languages
152
+ * (`docs.describe.net`, ยง"Displaying a score"):
153
+ *
154
+ * ```js
155
+ * String(parseFloat(x.toFixed(2))) // JavaScript
156
+ * ```
157
+ * ```python
158
+ * f"{round(x, 2):g}" # Python
159
+ * ```
160
+ *
161
+ * **Live witness case**: the agent scored `83.0` renders as `83` on all three
162
+ * surfaces โ€” where `toFixed(2)` alone prints `83.00` and `toFixed(1)` prints
163
+ * `83.0`. It is the one value that tells the three candidate rules apart, which
164
+ * is why `format.test.ts` tests it first.
165
+ *
166
+ * This is a DISPLAY convention. The API keeps serving the full-precision number
167
+ * (six decimals) and what you compute with is the number, never the string โ€”
168
+ * which is why the two functions below are separate and why `formatScore`
169
+ * returns a `string`. A helper that rounded the number in place would push a
170
+ * lossy value back into arithmetic, and averaging rounded members is how an
171
+ * aggregate ends up disagreeing with the members it aggregates.
172
+ */
173
+ /**
174
+ * The canonical display string, or `null` when there is nothing to display.
175
+ *
176
+ * `null` in, `null` out โ€” never `"0"`, never `"โ€”"`. Choosing the placeholder
177
+ * for absence is the surface's job and it is a different decision per surface;
178
+ * inventing one here would put this package's taste into every consumer, and
179
+ * `"0"` in particular would publish "worst possible reputation" for "nobody has
180
+ * rated this yet" (invariante 7 of the index, and R1 of this SDK).
181
+ *
182
+ * A non-finite input (a `NaN` from a malformed payload) is also `null`: a
183
+ * number we cannot name is not a number we may put describe.net's name on.
184
+ */
185
+ declare function formatScore(value: number | null | undefined): string | null;
186
+ /**
187
+ * The same rounding, kept as a `number`.
188
+ *
189
+ * For the one case where a number is what you need: MeshRelay rounds at the
190
+ * boundary where the value ENTERS the system rather than at each surface,
191
+ * because "the bug this closes is one number rendering differently in two
192
+ * places" (`describenet.js:204-208`). If you do that, use this โ€” and be aware
193
+ * you have made the value lossy on purpose. Everything else should carry the
194
+ * full-precision number and call `formatScore` at the pixel.
195
+ */
196
+ declare function roundScore(value: number | null | undefined): number | null;
197
+
198
+ /**
199
+ * How many distinct counterparties are behind a wallet's reputation โ€” and the
200
+ * two ways of reconstructing that number that are both WRONG.
201
+ *
202
+ * Contributed by **MeshRelay**, `#agents` on MeshRelay, **2026-08-30**. The
203
+ * seven lines of the helper are not the contribution; the two measurements are,
204
+ * and they are the reason this file has a docstring longer than its code.
205
+ */
206
+ /**
207
+ * The distinct-rater count of a wallet, or `null` when there is none to give.
208
+ *
209
+ * ## ๐Ÿ”ด Read this before you use the number
210
+ *
211
+ * `distinct_raters` at the top level of `GET /wallets/{wallet}/chains` is
212
+ * `COUNT(DISTINCT client)` across every chain AND every identity: one rater who
213
+ * reviewed on two chains counts **once**. There is no way to rebuild that from
214
+ * the per-chain rows, and MeshRelay measured both attempts on 2026-08-30:
215
+ *
216
+ * * **Summing the chains DOUBLE-COUNTS** whoever rated on more than one of
217
+ * them. Measured case: the karma-hello wallet reads **9** distinct raters
218
+ * globally while its per-chain figures add up to **11**.
219
+ * * **Taking the maximum UNDERESTIMATES.** Measured case: 3 raters on base and
220
+ * 4 *different* ones on avalanche is **7** real counterparties, and the
221
+ * maximum answers **4**.
222
+ *
223
+ * So the per-chain maximum is a **LOWER BOUND โ€” never the answer**, and summing
224
+ * is not a second-best either: it is wrong in the opposite direction. That pair
225
+ * of sentences is the contribution; without them this helper reads like a
226
+ * one-liner and gets used as the truth.
227
+ *
228
+ * **One live vector proves all three branches at once.** Verified against
229
+ * `api.describe.net` on 2026-08-30 (free route), wallet
230
+ * `0xcc28โ€ฆ4821`: global `distinct_raters` **129**, per chain base **113** and
231
+ * ethereum **21**. The maximum answers 113 (**16 short**), the sum answers 134
232
+ * (**5 over**), and only the global figure is right. It is the fixture this
233
+ * file's test pins, because a vector where two wrong answers land on opposite
234
+ * sides of the true one cannot be passed by accident.
235
+ *
236
+ * ## ๐Ÿ”ด The fallback is a COMPATIBILITY path, not a normal one
237
+ *
238
+ * โš ๏ธ Corrected while writing this, and the correction matters more than the
239
+ * line it replaces: an earlier draft called the per-chain maximum a "fallback
240
+ * for when the global figure is not there", which invites a reader to treat the
241
+ * global field as optional. It is not. describe.net has served wallet-level
242
+ * `distinct_raters` since `b753c9c` โ€” *"el dato ya estaba y no lo leรญamos"*,
243
+ * committed **2026-08-28**, which MeshRelay's own note dates 08-29 (the day they
244
+ * read it; both are written here because a reader will find the other one and
245
+ * think one of us is wrong) โ€” and their comment says the maximum is kept *"only
246
+ * as a fallback for a cached response predating that deploy"*
247
+ * (`meshrelay/meshrelayserv/describenet.js:228-230`,
248
+ * read 2026-08-30). Confirmed live the same day: the free route serves
249
+ * `distinct_raters` at the top level on every wallet.
250
+ *
251
+ * So in a client written after that date the fallback branch is unreachable
252
+ * unless you cache responses and outlive one of their deploys โ€” which MeshRelay
253
+ * does, and is why the branch exists at all. It is kept for them and for anyone
254
+ * replaying a stored payload, not because the field might be missing today.
255
+ *
256
+ * ## What this function therefore does
257
+ *
258
+ * Prefers the global count whenever the object carries one; falls back to the
259
+ * per-chain maximum only when it does not. What comes back is exact in the first
260
+ * case and a lower bound in the second, and there is no third answer it could
261
+ * give. **It never sums, and neither should you.**
262
+ *
263
+ * ## ๐Ÿ”ด Why this is not called `maxDistinctRaters`
264
+ *
265
+ * Because MeshRelay, who wrote it under that name, asked for the rename when
266
+ * they handed it over (2026-08-30): *"ese nombre invita a creer que el mรกximo es
267
+ * la respuesta correcta, cuando es el รบltimo recurso. El mรญo estรก mal nombrado y
268
+ * lo arrastro de cuando el nivel wallet no existรญa."*
269
+ *
270
+ * That is worth keeping written down, because the old name is what a reader will
271
+ * search for and because it is the failure this whole file guards against
272
+ * arriving through the API surface: a function named after its fallback
273
+ * advertises the fallback, and the fallback is the wrong answer. Their name
274
+ * survives here, in the provenance, which is where it belongs.
275
+ *
276
+ * ## Two `null`s that are not zero
277
+ *
278
+ * * A wallet with no eligible rating anywhere serves `distinct_raters: null`
279
+ * with `chains: []` โ€” verified live 2026-08-30 against `0xdEaDโ€ฆBEEF`. The
280
+ * answer is `null`, **never `0`**: "nobody has rated this" and "zero people
281
+ * rated this after we counted" are the same sentence, but `0` is a number a
282
+ * caller will divide by, average, or render as a bar of length zero next to
283
+ * wallets whose bar means something. `Math.max(...[])` is `-Infinity`, which
284
+ * is the concrete bug this branch exists to not have.
285
+ * * A `null` INPUT (the fail-open value of `wallet()`, i.e. "we could not ask
286
+ * describe.net") also gives `null`. Accepting it is deliberate: it lets a
287
+ * caller write `resolveDistinctRaters(await describe.wallet(w))` without a
288
+ * null-check that would only exist to satisfy the compiler, and it keeps the
289
+ * three absences of this package from collapsing โ€” an unreachable index and
290
+ * an unrated wallet both mean "no number", and neither means zero.
291
+ *
292
+ * Structurally typed rather than tied to `WalletReputation` so it also works on
293
+ * a payload you parsed yourself or pulled out of your own cache.
294
+ */
295
+ declare function resolveDistinctRaters(wallet: {
296
+ distinctRaters: number | null;
297
+ chains: readonly {
298
+ distinctRaters: number;
299
+ }[];
300
+ } | null | undefined): number | null;
301
+
302
+ /**
303
+ * Shape validation for the hash fields โ€” *"el 200 sin tx"*, from KarmaKadabra.
304
+ *
305
+ * Pure: no network, no clock, no state. Strings in, booleans out.
306
+ *
307
+ * ## Where this comes from
308
+ *
309
+ * Contributed by **KarmaKadabra**, `#agents` on MeshRelay, **2026-08-30**. Their
310
+ * words:
311
+ *
312
+ * > *"Un 200 que no hizo la cosa es peor que un 503, porque el cliente lo toma
313
+ * > por bueno: si nosotros no chequeรกramos el tx, habrรญamos contado 14 ratings
314
+ * > que no existen. Nosotros lo cazamos con un sello que exige forma de hash โ€”
315
+ * > pero el contrato deberรญa decirlo, no cada cliente descubrirlo."*
316
+ *
317
+ * The second half is why this lives in the SDK: the check is a property of the
318
+ * CONTRACT, and three consumers each discovering it separately is three chances
319
+ * to get it wrong. Verified before writing a line: neither this SDK nor its
320
+ * Python twin validated the shape of any hash field on 2026-08-30.
321
+ *
322
+ * ## ๐Ÿ”ด Why `^0x[0-9a-f]{64}$` alone would have been a disaster
323
+ *
324
+ * The obvious version of this file โ€” one EVM regex โ€” would have flagged **every
325
+ * Solana rating in the index** as malformed. Two independent confirmations, both
326
+ * read 2026-08-30:
327
+ *
328
+ * * from the writer: `describe-net/describenet/solana_indexer.py:436` puts
329
+ * `firma["signature"]` โ€” a base58 signature โ€” into the `tx_hash` column of
330
+ * the INSERT at `indexer.py:153-157`, the same column the EVM indexer fills
331
+ * with `0xโ€ฆ`. Solana writes to the same tables on purpose, so this is by
332
+ * construction and not an accident of one sample;
333
+ * * from the wire (measured by the Python twin against `GET /feed`): avalanche
334
+ * and celo serve 66-char `0x` + 64 hex, solana serves 87- and 88-char base58
335
+ * with no prefix.
336
+ *
337
+ * An alarm that screams about good data is worse than no alarm: people learn to
338
+ * ignore it, and then it is silent on the day it is right. So this validates the
339
+ * **union** of the legitimate shapes, never the intersection.
340
+ *
341
+ * The shapes the index emits today, each with its source:
342
+ *
343
+ * 1. **EVM hash** โ€” `0x` + 64 hex. `chain/decode.py:253` does `"0x" + โ€ฆhex()`
344
+ * over a `bytes32` (`_NEW_FEEDBACK_TYPES:85`). This is `tx_hash`,
345
+ * `revoked_tx` and `feedback_hash` on the ten EVM chains.
346
+ * 2. **Solana signature** โ€” base58 (Bitcoin alphabet: no `0`, `O`, `I`, `l`),
347
+ * 86โ€“88 characters. 64 bytes in base58 is 87โ€“88; 86 is reachable with leading
348
+ * zero bytes. On Solana `feedback_hash` is **NULL on purpose**, so a hole
349
+ * there is correct and not a fault.
350
+ * 3. **Bare digest** โ€” 64 hex with **no** `0x`. That is `Snapshot.inputs_digest`,
351
+ * which comes out of `hashlib.sha256(...).hexdigest()` in `aggregate.py:1920`.
352
+ * Demanding the `0x` prefix would have marked every citable snapshot as
353
+ * malformed.
354
+ * 4. **The `pending` sentinel** โ€” only on the `X-Payment-Receipt` header, whose
355
+ * own OpenAPI declares it: the settlement hash *"or `pending` if settlement
356
+ * has not reported one"*. It is a LEGITIMATE value, which is why
357
+ * {@link looksLikeSettlementReceipt} exists separately: treating it as
358
+ * garbage would fire an alarm on the happy path of every fresh payment.
359
+ *
360
+ * ## ๐Ÿ”ด What is deliberately NOT validated: `build_sha`
361
+ *
362
+ * `IndexHealth.buildSha` looks like a hash and is not one, and the measurement
363
+ * that settles it is `describe-net/scripts/build_lambda_zip.py:64` (read
364
+ * 2026-08-30): `estampa = sha + ("-dirty" if sucio else "")`. A legitimate
365
+ * deploy can therefore publish `"<40 hex>-dirty"`, and a validator would scream
366
+ * about a perfectly good build โ€” forever, on every `/health` call. The general
367
+ * rule that falls out of it, and it is the one to apply to the next field:
368
+ * **validate the identifiers a caller will carry somewhere to verify (an
369
+ * explorer, a digest comparison); leave alone the strings that only describe a
370
+ * build.** Nobody looks up a `build_sha`; the service already refuses to publish
371
+ * its `unknown` default as if it were a SHA (`api.py:2439-2456`).
372
+ *
373
+ * ## The question this module answers โ€” and the one it does not
374
+ *
375
+ * It answers **"does this have the shape of an on-chain identifier?"**. It does
376
+ * NOT answer "does this transaction exist?" or "does it say what the index says
377
+ * it says": that is verified in an explorer, which is the entire point of the
378
+ * field (the service's own schema: *"go verify it in an explorer, which is the
379
+ * point"*). A shape check cannot prove existence and does not pretend to.
380
+ *
381
+ * What it does catch is what bit KarmaKadabra: the empty string, `"null"`,
382
+ * `"undefined"`, `"0x"`, `"0x0"`, a truncated hash, an error message parked in
383
+ * the field. Every one of those sails through an `if (rating.txHash)` today with
384
+ * nothing making a sound.
385
+ *
386
+ * ๐Ÿ”ด **And it deliberately does not validate per chain.** A `feedback_hash`
387
+ * shaped like a Solana signature is accepted even though Solana emits none
388
+ * today. Being strict per field would trade a cheap false negative (letting an
389
+ * odd-but-valid shape through) for an expensive false positive (screaming about
390
+ * good data the day the service extends a field), and that contradicts the
391
+ * passthrough rule this package is built on: type what is known, PRESERVE what
392
+ * is not.
393
+ */
394
+ /**
395
+ * The one non-hash value the `X-Payment-Receipt` header declares legitimate.
396
+ *
397
+ * The live OpenAPI says it, not us: the settlement transaction hash *"or
398
+ * `pending` if settlement has not reported one"*.
399
+ */
400
+ declare const SETTLEMENT_PENDING = "pending";
401
+ /**
402
+ * Does `value` have the shape of an on-chain identifier this index emits?
403
+ *
404
+ * The UNION of the three measured shapes (EVM hash, Solana signature, bare
405
+ * digest) โ€” never the intersection. See the module header for why an EVM-only
406
+ * regex would have marked every Solana rating as malformed.
407
+ *
408
+ * It does not prove the transaction exists. That is the explorer's job.
409
+ */
410
+ declare function looksLikeOnchainId(value: string): boolean;
411
+ /**
412
+ * The same, plus the `pending` sentinel. For `X-Payment-Receipt` and nothing
413
+ * else.
414
+ *
415
+ * `pending` is not garbage: it is the seller saying *"I charged you and
416
+ * settlement has not reported the hash yet"*, and it is in their OpenAPI.
417
+ * Marking it malformed would turn the happy path of every freshly settled
418
+ * payment into an alarm.
419
+ */
420
+ declare function looksLikeSettlementReceipt(value: string): boolean;
421
+ /** Anything that carries the marks of its own malformed hash fields. */
422
+ interface MalformedCarrier {
423
+ malformedHashes?: readonly string[];
424
+ }
425
+ /**
426
+ * Every malformed hash field of a result, located.
427
+ *
428
+ * Walks the places a hash can hide in a parsed result and returns qualified
429
+ * paths, in the order they appear:
430
+ *
431
+ * ```ts
432
+ * ['ratings[3].tx_hash', 'snapshot.inputs_digest', 'payment.receipt']
433
+ * ```
434
+ *
435
+ * Wire names (`tx_hash`), not ours (`txHash`), on purpose: this string is what
436
+ * ends up in a log line or a ticket to whoever runs the index, and it has to
437
+ * name the field the way the API does.
438
+ *
439
+ * An empty array is the normal case and means "no field arrived malformed" โ€” it
440
+ * says nothing about which fields arrived at all. An absent hash is legitimate
441
+ * and is not reported here.
442
+ */
443
+ declare function malformedHashReport(result: {
444
+ ratings?: readonly MalformedCarrier[];
445
+ snapshot?: MalformedCarrier | null;
446
+ payment?: MalformedCarrier | null;
447
+ } | null | undefined): string[];
448
+
449
+ /**
450
+ * Wire JSON โ†’ typed shape.
451
+ *
452
+ * Three rules, and each one is a bug that already happened somewhere:
453
+ *
454
+ * 1. **`null` survives.** `optNumber` returns `null` for `null` and NEVER `0`.
455
+ * Every `|| 0` in a parser is an invariant-7 violation waiting for its first
456
+ * unrated wallet.
457
+ * 2. **Unknown fields survive.** Every result keeps `raw`. The server may add a
458
+ * field tomorrow and a consumer must not wait for our release to read it.
459
+ * 3. **A body that is not the shape we asked for is `unparseable`, not
460
+ * garbage-in-silence.** The failure that has to be impossible here is a
461
+ * response that parses "successfully" into an object full of zeros.
462
+ * 4. **A hash field that is not a hash is dropped and MARKED, never passed
463
+ * through.** Added 2026-08-30 from KarmaKadabra's *"el 200 sin tx"*. The
464
+ * typed field goes `null` โ€” nobody builds an explorer link out of garbage โ€”
465
+ * and its wire name goes into the `malformedHashes` of the object that owns
466
+ * it, so that **absent** (`null`, list empty) stays distinguishable from
467
+ * **malformed** (`null`, name in the list). It is rule 1 one level down: the
468
+ * absence of a value and a value that is nonsense are different facts, and
469
+ * collapsing them is the failure this file exists to prevent. See
470
+ * `hashes.ts`, and `client.ts` for how the fact reaches the caller.
471
+ */
472
+
473
+ /** `GET /wallets/{wallet}/chains`. Requires `wallet` โ€” everything else may be absent. */
474
+ declare function parseWalletReputation(payload: unknown): WalletReputation;
475
+ /** `GET /reputation/wallet/{wallet}` โ€” metered. */
476
+ declare function parseWalletBreakdown(payload: unknown, payment: PaymentEvidence | null): WalletBreakdown;
477
+ /** `GET /reputation/agent/{network}/{agent_id}` โ€” metered. */
478
+ declare function parseAgentReputation(payload: unknown, payment: PaymentEvidence | null): AgentReputation;
479
+ /**
480
+ * `GET /leaderboard` โ€” a bare JSON array (verified live 2026-08-30: 100 rows,
481
+ * no envelope). NOT `{rows: [...]}`, which is what a reader expecting a
482
+ * paginated shape would assume.
483
+ */
484
+ declare function parseLeaderboard(payload: unknown): LeaderboardRow[];
485
+ /** `GET /health`. */
486
+ declare function parseHealth(payload: unknown): IndexHealth;
487
+
488
+ export { AgentReputation, DescribeErrorKind, IndexHealth, LeaderboardRow, PaymentEvidence, RECOVERY, type RecoveryKey, SETTLEMENT_PENDING, WalletBreakdown, WalletReputation, formatScore, looksLikeOnchainId, looksLikeSettlementReceipt, malformedHashReport, parseAgentReputation, parseHealth, parseLeaderboard, parseWalletBreakdown, parseWalletReputation, recoveryFor, resolveDistinctRaters, roundScore };