uvd-describe-sdk 0.2.0 → 0.4.1
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/CHANGELOG.md +116 -0
- package/README.md +80 -4
- package/dist/{client-RAhXcpdY.d.mts → client-0sg4J53x.d.mts} +342 -23
- package/dist/{client-RAhXcpdY.d.ts → client-0sg4J53x.d.ts} +342 -23
- package/dist/{config-uvI_GS-x.d.mts → config-gjJ08BUJ.d.mts} +1 -1
- package/dist/{config-uvI_GS-x.d.ts → config-gjJ08BUJ.d.ts} +1 -1
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +122 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +119 -3
- package/dist/index.mjs.map +1 -1
- package/dist/partner/index.d.mts +2 -2
- package/dist/partner/index.d.ts +2 -2
- package/dist/partner/index.js.map +1 -1
- package/dist/partner/index.mjs.map +1 -1
- package/dist/x402/index.d.mts +1 -1
- package/dist/x402/index.d.ts +1 -1
- package/package.json +2 -1
- package/src/caveats.ts +297 -21
- package/src/config.ts +1 -1
- package/src/index.ts +18 -1
- package/src/parse.ts +83 -0
- package/src/types.ts +138 -1
package/src/caveats.ts
CHANGED
|
@@ -15,34 +15,55 @@
|
|
|
15
15
|
* string comparison kept returning false and nobody was told.
|
|
16
16
|
*
|
|
17
17
|
* Exporting the set is one of the four "día 0" requirements the platform team
|
|
18
|
-
* put on any SDK of the house
|
|
19
|
-
* contrato exportado*. Typing them here means a consumer never re-types them,
|
|
18
|
+
* put on any SDK of the house: *los caveat `code`s como contrato exportado*. Typing them here means a consumer never re-types them,
|
|
20
19
|
* and a typo is a compile error rather than a branch that is never taken.
|
|
21
20
|
*
|
|
22
21
|
* ## Why the type is not a closed union
|
|
23
22
|
*
|
|
24
|
-
* `CaveatCode | (string & {})` gives autocomplete on the
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
23
|
+
* `CaveatCode | (string & {})` gives autocomplete on the codes that exist today
|
|
24
|
+
* AND still accepts one more the server adds tomorrow. A closed union would turn
|
|
25
|
+
* every new server-side code into a type error in code that is already deployed
|
|
26
|
+
* and working — the passthrough rule (tipar lo conocido, CONSERVAR lo que no)
|
|
27
|
+
* applied to the type system. The measured precedent is `Facet.direction`:
|
|
28
|
+
* FastAPI silently dropped a field nobody had declared, and the response looked
|
|
29
|
+
* correct with the data missing.
|
|
31
30
|
*
|
|
32
31
|
* The codes carry no version and never bump `POLICY_VERSION`: a caveat is
|
|
33
32
|
* advisory by construction and identifies a CUT, it never moves a score.
|
|
34
33
|
*/
|
|
35
34
|
|
|
35
|
+
import type { WalletReputation } from './types';
|
|
36
|
+
|
|
36
37
|
/**
|
|
37
|
-
* The
|
|
38
|
-
* `describenet/caveats.py:
|
|
39
|
-
* `tests/test_caveat_codes.py` pins literally, so adding or
|
|
40
|
-
* there goes red on purpose
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
38
|
+
* The ten cuts describe.net serves on 2026-09-15, copied from the frozen set in
|
|
39
|
+
* `describenet/caveats.py:177-192` (describe-net `origin/main` at `4fd11c0`),
|
|
40
|
+
* which its own `tests/test_caveat_codes.py` pins literally, so adding or
|
|
41
|
+
* renaming one over there goes red on purpose. Same order as upstream.
|
|
42
|
+
*
|
|
43
|
+
* What the FREE route evaluates, per the server itself (`caveats.py:513`,
|
|
44
|
+
* `_publicos_evaluados`): `burn-address` always, and `thin-chain` when it has the
|
|
45
|
+
* per-chain rows — which `GET /wallets/{wallet}/chains` always has. Every other
|
|
46
|
+
* wallet-scope code is DECLARED as not evaluated, by name, in
|
|
47
|
+
* `WalletReputation.caveatsNotComputed`. `facilitator-authored` is agent scope
|
|
48
|
+
* and is in neither: a wallet profile lists no rows. An empty `caveats: []` on a
|
|
49
|
+
* free response therefore still means "no public-data caveat", NOT "clean" — and
|
|
50
|
+
* `requireFullCaveats()` is the gate that knows it. See `CAVEAT_SCOPE_FREE`.
|
|
51
|
+
*
|
|
52
|
+
* `thin-chain` (upstream since 2026-09-04, `cf8f806`; on the free route since
|
|
53
|
+
* 2026-09-05) is mirrored since 0.4.1, added to both twins together so the set
|
|
54
|
+
* both SDKs publish never differs. 0.4.0 shipped nine and knew it: until then
|
|
55
|
+
* `isKnownCaveatCode('thin-chain')` answered `false`, and the caveat still
|
|
56
|
+
* arrived whole — the tolerant answer this module was built to give.
|
|
57
|
+
*
|
|
58
|
+
* ⚠️ CORRECTED 2026-09-15, and the old text is left because somebody will look
|
|
59
|
+
* for it. It read: *"The eight cuts served on 2026-08-30, copied from the frozen
|
|
60
|
+
* set in `describenet/caveats.py:172-183` … Only `no-score` and `burn-address`
|
|
61
|
+
* are computable from public data, so the free routes serve a documented SUBSET
|
|
62
|
+
* … The other six need the grain and ride the metered routes."* Two codes had
|
|
63
|
+
* landed upstream since and this mirror carried neither; `facilitator-authored`
|
|
64
|
+
* (`6e25d71`, 2026-09-14) was mirrored in 0.4.0, `thin-chain` in 0.4.1. And
|
|
65
|
+
* `no-score` is not evaluated on the free route at all: the server declares it
|
|
66
|
+
* in the list.
|
|
46
67
|
*/
|
|
47
68
|
export const CAVEAT_CODES = [
|
|
48
69
|
/** No score to qualify: there is no eligible rating at all. */
|
|
@@ -65,14 +86,32 @@ export const CAVEAT_CODES = [
|
|
|
65
86
|
* — which is why they are still served — but the subject is not an identity.
|
|
66
87
|
*/
|
|
67
88
|
'burn-address',
|
|
89
|
+
/**
|
|
90
|
+
* At least one of two or more scored chains rests on fewer than
|
|
91
|
+
* `reading_policy.min_raters` distinct raters. Its weight in the global score
|
|
92
|
+
* is small but never zero, so it still moves the number: read the per-chain
|
|
93
|
+
* composition before the global. Never fires on a single chain — there the
|
|
94
|
+
* weight cancels and `single-rater` / `few-raters` already say it. Wallet
|
|
95
|
+
* scope, and evaluated on the FREE route too (from `chains[]`). Since
|
|
96
|
+
* 2026-09-04; mirrored since 0.4.1.
|
|
97
|
+
*/
|
|
98
|
+
'thin-chain',
|
|
99
|
+
/**
|
|
100
|
+
* Some rows of `ratings[]` carry `authorClass: 'facilitator-authored'`: a
|
|
101
|
+
* relayer signed them, so their `client` is not the counterparty and every
|
|
102
|
+
* per-rater count merges them into one voice. AGENT scope only — the one
|
|
103
|
+
* metered answer that lists rows — and it carries no numbers, on purpose: the
|
|
104
|
+
* aggregate by author was cancelled upstream on 2026-08-29. Since 2026-09-14.
|
|
105
|
+
*/
|
|
106
|
+
'facilitator-authored',
|
|
68
107
|
] as const;
|
|
69
108
|
|
|
70
|
-
/** The
|
|
109
|
+
/** The known codes as a union — for `switch`, not for validation. */
|
|
71
110
|
export type KnownCaveatCode = (typeof CAVEAT_CODES)[number];
|
|
72
111
|
|
|
73
112
|
/**
|
|
74
|
-
* What a caveat's `code` may be:
|
|
75
|
-
*
|
|
113
|
+
* What a caveat's `code` may be: a known one, or any string the server starts
|
|
114
|
+
* sending. The `(string & {})` half is what keeps autocomplete alive
|
|
76
115
|
* while leaving the union open.
|
|
77
116
|
*/
|
|
78
117
|
export type CaveatCode = KnownCaveatCode | (string & {});
|
|
@@ -122,3 +161,240 @@ export function hasCaveat(
|
|
|
122
161
|
): boolean {
|
|
123
162
|
return (subject?.caveats ?? []).some((c) => c.code === code);
|
|
124
163
|
}
|
|
164
|
+
|
|
165
|
+
// ---------------------------------------------------------------------------
|
|
166
|
+
// The gate — added 2026-09-15 (0.4.0)
|
|
167
|
+
// ---------------------------------------------------------------------------
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* `requireFullCaveats()` refused: this answer does not vouch for every cut.
|
|
171
|
+
*
|
|
172
|
+
* ## 🔴 NOT a `DescribeError`, and that is the decision
|
|
173
|
+
*
|
|
174
|
+
* `DescribeError` is the failure taxonomy — transport and protocol, "we could
|
|
175
|
+
* not read" — and consumers wrap it in their own fail-open:
|
|
176
|
+
* `catch (e) { if (e instanceof DescribeError) return null; }`. A refusal caught
|
|
177
|
+
* there degrades into "describe.net is down", and a gate built to tolerate
|
|
178
|
+
* outages lets the subject THROUGH: the same silent green the 2026-08-31 row
|
|
179
|
+
* exists to stop. This is not a failure to read; it is a successful read that
|
|
180
|
+
* does not support the decision being asked of it. So it extends `Error`, carries
|
|
181
|
+
* no `kind`, `transient` or `serviceFault`, and `failOpenCovers()` and
|
|
182
|
+
* `failedAfterPaying()` both answer `false` for it.
|
|
183
|
+
*
|
|
184
|
+
* Decided by the Python twin the same night (`CaveatsNotComputedError`,
|
|
185
|
+
* `uvd_describe_sdk/caveats.py`) and adopted here for parity. The first draft of
|
|
186
|
+
* this package made it a `DescribeError` with a new `kind`; the argument above is
|
|
187
|
+
* why that was the wrong door — and it would also have broken, at compile time,
|
|
188
|
+
* every exhaustive `switch` over `DescribeErrorKind`.
|
|
189
|
+
*
|
|
190
|
+
* ## `notComputed` — branch on it, never on the message
|
|
191
|
+
*
|
|
192
|
+
* ```
|
|
193
|
+
* ['few-raters', …] the answer DECLARED these unevaluated: unverified, not passed
|
|
194
|
+
* null the answer declared NOTHING — a server older than
|
|
195
|
+
* 2026-09-14, or a payload stored before then. Not `[]`.
|
|
196
|
+
* ```
|
|
197
|
+
*
|
|
198
|
+
* A declared `[]` never reaches this class: it passes the gate.
|
|
199
|
+
*/
|
|
200
|
+
export class CaveatsNotComputedError extends Error {
|
|
201
|
+
/**
|
|
202
|
+
* What to do INSTEAD, as a frozen literal that interpolates nothing — the
|
|
203
|
+
* redaction rule of `recovery.ts` (invariant 11), without being an entry of
|
|
204
|
+
* that table, because this is not a `kind`. Same text on the class and on
|
|
205
|
+
* every instance.
|
|
206
|
+
*
|
|
207
|
+
* ⚠️ Not byte-identical to the Python twin's, and that is declared rather than
|
|
208
|
+
* hidden: theirs names `wallet_breakdown()`, `payer=`, `partner=` and
|
|
209
|
+
* `fallback_reader`, which are Python spellings. This one names what both SDKs
|
|
210
|
+
* share — the route, and the two ways through it.
|
|
211
|
+
*/
|
|
212
|
+
static readonly recovery: string =
|
|
213
|
+
'What this free answer did not evaluate is what the metered decomposition sells: ' +
|
|
214
|
+
'`GET /reputation/wallet/{wallet}` evaluates the wallet-scope cuts this error lists — paid ' +
|
|
215
|
+
"per call with x402, or free for a wallet on describe.net's partner allowlist. If the error " +
|
|
216
|
+
'lists nothing, the answer declared nothing (a server older than 2026-09-14, or a payload ' +
|
|
217
|
+
'stored before then), and that is not a pass either: the decomposition is still the route ' +
|
|
218
|
+
'that evaluates them.';
|
|
219
|
+
|
|
220
|
+
/** Same literal as {@link CaveatsNotComputedError.recovery}, on the instance. */
|
|
221
|
+
readonly recovery: string = CaveatsNotComputedError.recovery;
|
|
222
|
+
/** The wallet whose answer was refused, as served. */
|
|
223
|
+
readonly wallet: string;
|
|
224
|
+
/** A COPY of what the answer declared, or `null` if it declared nothing. */
|
|
225
|
+
readonly notComputed: string[] | null;
|
|
226
|
+
|
|
227
|
+
constructor(message: string, opts: { wallet: string; notComputed: readonly string[] | null }) {
|
|
228
|
+
super(message);
|
|
229
|
+
this.name = 'CaveatsNotComputedError';
|
|
230
|
+
this.wallet = opts.wallet;
|
|
231
|
+
this.notComputed = opts.notComputed === null ? null : [...opts.notComputed];
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* Is this the object `wallet()` / `parseWalletReputation()` returns?
|
|
237
|
+
*
|
|
238
|
+
* By KEYS, the way `parse.ts` tells the doors apart (rule 5): `globalScore` is
|
|
239
|
+
* only ever in a parsed free answer, `finalScore` only in a parsed breakdown,
|
|
240
|
+
* `agentId` only in a parsed agent. `caveatsNotComputed` is deliberately NOT
|
|
241
|
+
* required — a result parsed by 0.3.0 and stored has no such key, and that is an
|
|
242
|
+
* undeclared answer (refused as such), not a wrong argument.
|
|
243
|
+
*/
|
|
244
|
+
function isWalletReputation(v: unknown): v is WalletReputation {
|
|
245
|
+
if (typeof v !== 'object' || v === null || Array.isArray(v)) return false;
|
|
246
|
+
return (
|
|
247
|
+
typeof (v as { wallet?: unknown }).wallet === 'string' &&
|
|
248
|
+
'globalScore' in v &&
|
|
249
|
+
!('finalScore' in v) &&
|
|
250
|
+
!('agentId' in v)
|
|
251
|
+
);
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* Return `result` only if its answer DECLARED it left no caveat code out.
|
|
256
|
+
*
|
|
257
|
+
* ```ts
|
|
258
|
+
* const rep = await describe.wallet(address);
|
|
259
|
+
* if (rep === null) { … } // no answer at all: decide THAT first
|
|
260
|
+
* requireFullCaveats(rep); // throws CaveatsNotComputedError
|
|
261
|
+
* ```
|
|
262
|
+
*
|
|
263
|
+
* ## The bug it closes, found by karma-hello
|
|
264
|
+
*
|
|
265
|
+
* A quality gate built on the FREE route passes everybody (karma-hello, channel,
|
|
266
|
+
* 2026-08-31; `describe-net/docs/BACKLOG.md:221`). The evidence-quality cuts —
|
|
267
|
+
* `single-rater`, `few-raters`, `campaign-per-rater`, … — are computed only by
|
|
268
|
+
* the paid decomposition, so on `GET /wallets/{wallet}/chains`
|
|
269
|
+
* `hasCaveat(rep, 'single-rater')` is `false` for every wallet, the one with a
|
|
270
|
+
* single rater included. Honest code, and a gate that cannot fail anyone.
|
|
271
|
+
*
|
|
272
|
+
* Since 2026-09-14 the free answer DECLARES the names it did not evaluate
|
|
273
|
+
* (`WalletReputation.caveatsNotComputed`), and the server names this very helper
|
|
274
|
+
* as the reason the declaration is a list and not a count
|
|
275
|
+
* (`describenet/caveats.py:493-494`: *"el SDK puede ofrecer
|
|
276
|
+
* `require_full_caveats()` sin tabla propia"*). No table of our own here either:
|
|
277
|
+
* the verdict is read off the answer, never off a list typed in this package.
|
|
278
|
+
*
|
|
279
|
+
* ## Three states, and only one passes
|
|
280
|
+
*
|
|
281
|
+
* ```
|
|
282
|
+
* caveatsNotComputed = [] → returns `result`, the same object
|
|
283
|
+
* caveatsNotComputed = ['…', …] → throws; `error.notComputed` is the list
|
|
284
|
+
* caveatsNotComputed = null → throws; `error.notComputed` is null
|
|
285
|
+
* ```
|
|
286
|
+
*
|
|
287
|
+
* 🔴 **Against the live index this throws for every `wallet()` today** —
|
|
288
|
+
* measured 2026-09-15: the same seven codes for a wallet with 471 distinct raters
|
|
289
|
+
* and for one with no identity at all. That is the gate working: the free route
|
|
290
|
+
* does not evaluate the evidence-quality cuts, and a decision that needs them has
|
|
291
|
+
* to buy `walletBreakdown()` (or read it over the partner rail). What changes is
|
|
292
|
+
* that the gate can no longer find that out by passing.
|
|
293
|
+
*
|
|
294
|
+
* ## 🔴 Why `null` THROWS — the decision, and its sources
|
|
295
|
+
*
|
|
296
|
+
* - The position of 2026-08-31, written in `describe-net/docs/BACKLOG.md:221`:
|
|
297
|
+
* *"la línea gratis/pago es regla de costo y **el scope es la señal**; el SDK
|
|
298
|
+
* puede ganar `require_full_caveats()`"*. That row is about a gate that goes
|
|
299
|
+
* green without knowing what was not computed. A `null` that passes is that
|
|
300
|
+
* gate, back — silently, on every old deployment and every stored payload.
|
|
301
|
+
* - The service refuses the same collapse on its own side: its MCP tool carries
|
|
302
|
+
* `None` *"cuando la API no lo trae: una API vieja no declaró nada, y `[]`
|
|
303
|
+
* afirmaría que lo calculó todo"* (`describenet/mcp_server.py:896-901`).
|
|
304
|
+
* - Before 2026-09-14 the free route did not evaluate those cuts either; it only
|
|
305
|
+
* did not SAY so (`caveatScope: 'public-data-subset'` was the whole signal). An
|
|
306
|
+
* old answer's silence is the old gap, not a clean bill.
|
|
307
|
+
*
|
|
308
|
+
* ## It takes a `WalletReputation`, and nothing else
|
|
309
|
+
*
|
|
310
|
+
* The one result that declares what it did not compute. Anything else is a
|
|
311
|
+
* `TypeError` naming the mistake — never a pass, and never the refusal above:
|
|
312
|
+
*
|
|
313
|
+
* - `null` is "describe.net did not answer", the third absence (invariant 3).
|
|
314
|
+
* Handle it before asking about caveats.
|
|
315
|
+
* - A `WalletBreakdown` or an `AgentReputation` comes from a metered route, which
|
|
316
|
+
* evaluates its own caveat scope and declares no omissions: there is nothing
|
|
317
|
+
* here for this gate to read.
|
|
318
|
+
* - A raw wire payload (snake_case) was never parsed: `parseWalletReputation()`.
|
|
319
|
+
*
|
|
320
|
+
* Never called by the client and never swallowed by `failOpen`. And passing
|
|
321
|
+
* means the caveats are COMPLETE, not that they are empty — `hasCaveat()` is
|
|
322
|
+
* still the question after the gate.
|
|
323
|
+
*/
|
|
324
|
+
export function requireFullCaveats(result: WalletReputation): WalletReputation {
|
|
325
|
+
if (!isWalletReputation(result)) {
|
|
326
|
+
throw new TypeError(
|
|
327
|
+
'requireFullCaveats() takes the WalletReputation that wallet() returns. A null means ' +
|
|
328
|
+
'describe.net did NOT answer — handle that before asking about caveats. A WalletBreakdown ' +
|
|
329
|
+
'or an AgentReputation comes from a metered route, which evaluates its own caveat scope ' +
|
|
330
|
+
'and declares no omissions. A raw payload goes through parseWalletReputation() first.',
|
|
331
|
+
);
|
|
332
|
+
}
|
|
333
|
+
// `Array.isArray`, not a null check: anything that is not a list is not a
|
|
334
|
+
// declaration (the parser already maps it to `null`), and a stored 0.3.0
|
|
335
|
+
// result has no key at all — both are undeclared, both refused as such.
|
|
336
|
+
const declared: unknown = result.caveatsNotComputed;
|
|
337
|
+
if (!Array.isArray(declared)) {
|
|
338
|
+
throw new CaveatsNotComputedError(
|
|
339
|
+
`the answer for ${result.wallet} did not declare which caveat codes it left out (no ` +
|
|
340
|
+
'`caveats_not_computed`): a server older than 2026-09-14, or a payload stored before ' +
|
|
341
|
+
'then. Undeclared is not `[]`, so this gate does not pass.',
|
|
342
|
+
{ wallet: result.wallet, notComputed: null },
|
|
343
|
+
);
|
|
344
|
+
}
|
|
345
|
+
if (declared.length === 0) return result;
|
|
346
|
+
const codes = declared.map(String);
|
|
347
|
+
throw new CaveatsNotComputedError(
|
|
348
|
+
`the answer for ${result.wallet} declares ${codes.length} caveat code(s) it did not ` +
|
|
349
|
+
`compute: ${codes.join(', ')}. Unverified, not passed.`,
|
|
350
|
+
{ wallet: result.wallet, notComputed: codes },
|
|
351
|
+
);
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
// ---------------------------------------------------------------------------
|
|
355
|
+
// Author classes — who SIGNED a rating row. Added 2026-09-15 (0.4.0)
|
|
356
|
+
// ---------------------------------------------------------------------------
|
|
357
|
+
|
|
358
|
+
/**
|
|
359
|
+
* The two classes served in `ratings[].author_class` since describe.net
|
|
360
|
+
* 2026-09-14 — the schema's own enum (`describenet/api.py:962`,
|
|
361
|
+
* `Literal["facilitator-authored", "rater-authored"]`), and
|
|
362
|
+
* `types.schema.test.ts` pins this tuple against the snapshot's `enum`. The
|
|
363
|
+
* Python twin calls the same set `KNOWN_AUTHOR_CLASSES`, the way it calls
|
|
364
|
+
* `CAVEAT_CODES` `KNOWN_CAVEAT_CODES`.
|
|
365
|
+
*
|
|
366
|
+
* They live next to the caveat codes because one of them IS one: the agent-scope
|
|
367
|
+
* caveat `facilitator-authored` fires exactly when some row carries that class
|
|
368
|
+
* (`describenet/caveats.py:614`, which reads the field instead of recomputing it,
|
|
369
|
+
* so the two cannot disagree inside one answer).
|
|
370
|
+
*/
|
|
371
|
+
export const AUTHOR_CLASSES = ['facilitator-authored', 'rater-authored'] as const;
|
|
372
|
+
|
|
373
|
+
/** The known classes as a union — for `switch`, not for validation. */
|
|
374
|
+
export type KnownAuthorClass = (typeof AUTHOR_CLASSES)[number];
|
|
375
|
+
|
|
376
|
+
/**
|
|
377
|
+
* What `Rating.authorClass` may be: a known class, or any string the server
|
|
378
|
+
* starts sending.
|
|
379
|
+
*
|
|
380
|
+
* Open, not closed, and recording that decision is why this type exists. The
|
|
381
|
+
* server's enum is closed TODAY; a third class there is a new contract on their
|
|
382
|
+
* side and must not become a type error — or worse, a thrown parse — on ours. A
|
|
383
|
+
* parser that rejected it would destroy a PAID read over one advisory field; one
|
|
384
|
+
* that nulled it would read as "no class served". So it arrives verbatim and
|
|
385
|
+
* `isKnownAuthorClass()` says whether this SDK has heard of it: the `CaveatCode`
|
|
386
|
+
* rule, applied one field over.
|
|
387
|
+
*/
|
|
388
|
+
export type AuthorClass = KnownAuthorClass | (string & {});
|
|
389
|
+
|
|
390
|
+
/**
|
|
391
|
+
* Is this one of the author classes this SDK knows?
|
|
392
|
+
*
|
|
393
|
+
* NOT a validator, same as `isKnownCaveatCode`: `false` means "newer than this
|
|
394
|
+
* SDK" — or, for `null`, a row served before 2026-09-14 that carries no class at
|
|
395
|
+
* all. Neither is invalid. Before filtering rows on it, decide what an unknown
|
|
396
|
+
* class means for YOUR count; this SDK will not decide that for you.
|
|
397
|
+
*/
|
|
398
|
+
export function isKnownAuthorClass(value: string | null | undefined): value is KnownAuthorClass {
|
|
399
|
+
return (AUTHOR_CLASSES as readonly unknown[]).includes(value);
|
|
400
|
+
}
|
package/src/config.ts
CHANGED
|
@@ -146,7 +146,7 @@ export const PARTNER_KEY_ENV = 'DESCRIBE_PARTNER_PRIVATE_KEY';
|
|
|
146
146
|
* time instead of at runtime. Bumping the version without the constant is a
|
|
147
147
|
* red test, not a silent lie in someone's access log.
|
|
148
148
|
*/
|
|
149
|
-
export const SDK_VERSION = '0.
|
|
149
|
+
export const SDK_VERSION = '0.4.1';
|
|
150
150
|
|
|
151
151
|
/** `uvd-describe-sdk-ts/0.1.0`, plus `(+<product>)` when the caller names itself. */
|
|
152
152
|
export const SDK_NAME = 'uvd-describe-sdk-ts';
|
package/src/index.ts
CHANGED
|
@@ -107,14 +107,29 @@ export type { DescribeErrorKind, PaymentAttempt, X402Challenge } from './errors'
|
|
|
107
107
|
export { RECOVERY, recoveryFor } from './recovery';
|
|
108
108
|
export type { RecoveryKey } from './recovery';
|
|
109
109
|
|
|
110
|
+
/**
|
|
111
|
+
* The caveat contract. Since 0.4.0 it also carries the two halves describe.net
|
|
112
|
+
* shipped on 2026-09-14: `requireFullCaveats()` — the gate that can fail a free
|
|
113
|
+
* answer which did not evaluate the evidence-quality cuts — and the author
|
|
114
|
+
* classes of `Rating.authorClass`.
|
|
115
|
+
*
|
|
116
|
+
* 🔴 `CaveatsNotComputedError` is exported HERE and not with the errors above,
|
|
117
|
+
* on purpose: it is not a `DescribeError`. A refusal of the gate is a successful
|
|
118
|
+
* read that does not support the decision, and a `catch` that fails open on
|
|
119
|
+
* `DescribeError` must not be able to swallow it.
|
|
120
|
+
*/
|
|
110
121
|
export {
|
|
122
|
+
AUTHOR_CLASSES,
|
|
111
123
|
CAVEAT_CODES,
|
|
112
124
|
CAVEAT_SCOPE_FREE,
|
|
113
125
|
CAVEAT_SCOPE_METERED,
|
|
126
|
+
CaveatsNotComputedError,
|
|
114
127
|
hasCaveat,
|
|
128
|
+
isKnownAuthorClass,
|
|
115
129
|
isKnownCaveatCode,
|
|
130
|
+
requireFullCaveats,
|
|
116
131
|
} from './caveats';
|
|
117
|
-
export type { Caveat, CaveatCode, KnownCaveatCode } from './caveats';
|
|
132
|
+
export type { AuthorClass, Caveat, CaveatCode, KnownAuthorClass, KnownCaveatCode } from './caveats';
|
|
118
133
|
|
|
119
134
|
export { formatScore, roundScore } from './format';
|
|
120
135
|
|
|
@@ -154,6 +169,8 @@ export {
|
|
|
154
169
|
|
|
155
170
|
export type {
|
|
156
171
|
Activity,
|
|
172
|
+
Freshness,
|
|
173
|
+
FreshnessScope,
|
|
157
174
|
AgentReputation,
|
|
158
175
|
Concentration,
|
|
159
176
|
Confidence,
|
package/src/parse.ts
CHANGED
|
@@ -54,6 +54,7 @@ import { hashField } from './hashes';
|
|
|
54
54
|
import type {
|
|
55
55
|
Activity,
|
|
56
56
|
AgentReputation,
|
|
57
|
+
Freshness,
|
|
57
58
|
Concentration,
|
|
58
59
|
Confidence,
|
|
59
60
|
Facet,
|
|
@@ -130,6 +131,39 @@ function parseCaveats(v: unknown): Caveat[] {
|
|
|
130
131
|
return out;
|
|
131
132
|
}
|
|
132
133
|
|
|
134
|
+
/**
|
|
135
|
+
* `caveats_not_computed` → the declared list, or `null` when nothing readable
|
|
136
|
+
* was declared. Added 2026-09-15 (0.4.0).
|
|
137
|
+
*
|
|
138
|
+
* `null` and `[]` are different facts and this function exists to keep them
|
|
139
|
+
* apart: `[]` is a DECLARATION ("evaluated everything") and the one value that
|
|
140
|
+
* makes `requireFullCaveats()` pass; `null` is a server that did not declare
|
|
141
|
+
* (older than 2026-09-14) or a stored payload from before then. A `?? []` here
|
|
142
|
+
* would turn every undeclared answer into a pass.
|
|
143
|
+
*
|
|
144
|
+
* 🔴 **A declaration that cannot be read WHOLE is not a declaration**, so every
|
|
145
|
+
* shape that is not a list of non-empty strings is `null` — never a filtered
|
|
146
|
+
* list. The asymmetry with `parseCaveats`, which drops a bad entry and keeps the
|
|
147
|
+
* rest, is deliberate: there a dropped entry loses one warning; here it can turn
|
|
148
|
+
* `[null]` into `[]`, the value that opens the gate. Failing closed means reading
|
|
149
|
+
* garbage as "undeclared", which the gate refuses. That covers the bare count
|
|
150
|
+
* floated on 2026-08-31 and rejected upstream for a list, too.
|
|
151
|
+
*
|
|
152
|
+
* It never throws: the field is a footnote to a read that otherwise arrived
|
|
153
|
+
* fine, and on a free route a throw becomes the fail-open `null` — the whole
|
|
154
|
+
* reputation lost over its footnote. Same rule, same shapes, as the Python twin's
|
|
155
|
+
* `models.py::_parse_not_computed`.
|
|
156
|
+
*/
|
|
157
|
+
function parseNotComputed(v: unknown): string[] | null {
|
|
158
|
+
if (!Array.isArray(v)) return null;
|
|
159
|
+
const codes: string[] = [];
|
|
160
|
+
for (const item of v) {
|
|
161
|
+
if (typeof item !== 'string' || item === '') return null;
|
|
162
|
+
codes.push(item);
|
|
163
|
+
}
|
|
164
|
+
return codes;
|
|
165
|
+
}
|
|
166
|
+
|
|
133
167
|
function parseFacets(v: unknown): Record<string, Facet> {
|
|
134
168
|
if (!isObj(v)) return {};
|
|
135
169
|
const out: Record<string, Facet> = {};
|
|
@@ -182,6 +216,43 @@ function parseActivity(v: unknown): Activity | null {
|
|
|
182
216
|
return { firstRatingAt: optString(v.first_rating_at), lastRatingAt: optString(v.last_rating_at) };
|
|
183
217
|
}
|
|
184
218
|
|
|
219
|
+
/**
|
|
220
|
+
* `null` when the block is absent OR unparseable — never an empty `Freshness`.
|
|
221
|
+
*
|
|
222
|
+
* Same rule as every other parser here: a default that looks like data is how a
|
|
223
|
+
* client stops being able to tell "the server does not publish this" from "the
|
|
224
|
+
* server has no dates for this subject". The second one is information; the
|
|
225
|
+
* first one is not.
|
|
226
|
+
*
|
|
227
|
+
* The counts go through `num()` so a string count from a stricter serialiser
|
|
228
|
+
* still lands as a number: freshness is advisory and must not be the reason a
|
|
229
|
+
* paid response fails to parse.
|
|
230
|
+
*/
|
|
231
|
+
function parseFreshness(v: unknown): Freshness | null {
|
|
232
|
+
if (!isObj(v)) return null;
|
|
233
|
+
const scope = isObj(v.scope) ? v.scope : {};
|
|
234
|
+
return {
|
|
235
|
+
scope: {
|
|
236
|
+
kind: optString(scope.kind),
|
|
237
|
+
direction: optString(scope.direction),
|
|
238
|
+
id: optString(scope.id),
|
|
239
|
+
network: optString(scope.network),
|
|
240
|
+
declaredType: optString(scope.declared_type),
|
|
241
|
+
},
|
|
242
|
+
lastReceivedFeedbackAt: optString(v.last_received_feedback_at),
|
|
243
|
+
lastEligibleRatingAt: optString(v.last_eligible_rating_at),
|
|
244
|
+
datedFeedbackCount: num(v.dated_feedback_count),
|
|
245
|
+
undatedFeedbackCount: num(v.undated_feedback_count),
|
|
246
|
+
timestampCoverage: optString(v.timestamp_coverage),
|
|
247
|
+
eligibleDatedCount: num(v.eligible_dated_count),
|
|
248
|
+
eligibleUndatedCount: num(v.eligible_undated_count),
|
|
249
|
+
eligibleTimestampCoverage: optString(v.eligible_timestamp_coverage),
|
|
250
|
+
refreshedAt: optString(v.refreshed_at),
|
|
251
|
+
indexerCheckedAt: optString(v.indexer_checked_at),
|
|
252
|
+
freshnessVersion: optString(v.freshness_version),
|
|
253
|
+
};
|
|
254
|
+
}
|
|
255
|
+
|
|
185
256
|
function parseSnapshot(v: unknown): Snapshot | null {
|
|
186
257
|
if (!isObj(v)) return null;
|
|
187
258
|
const malformed: string[] = [];
|
|
@@ -229,6 +300,13 @@ function parseRatings(v: unknown): Rating[] {
|
|
|
229
300
|
const malformed: string[] = [];
|
|
230
301
|
return {
|
|
231
302
|
client: String(r.client ?? ''),
|
|
303
|
+
// Tolerant on purpose, the `isKnownCaveatCode` pattern: a class this SDK
|
|
304
|
+
// has not heard of arrives verbatim, never thrown (one advisory field
|
|
305
|
+
// must not destroy a paid read) and never nulled (dropping it would read
|
|
306
|
+
// as "no class served"). Only a non-string or an empty string is `null`:
|
|
307
|
+
// there is nothing to keep (the Python twin's `_author_class`, same rule).
|
|
308
|
+
authorClass:
|
|
309
|
+
typeof r.author_class === 'string' && r.author_class !== '' ? r.author_class : null,
|
|
232
310
|
feedbackIndex: num(r.feedback_index),
|
|
233
311
|
value: num(r.value),
|
|
234
312
|
valueDecimals: num(r.value_decimals),
|
|
@@ -306,6 +384,8 @@ export function parseWalletReputation(payload: unknown): WalletReputation {
|
|
|
306
384
|
chainsWithIdentity: num(payload.chains_with_identity),
|
|
307
385
|
chainsWithReputation: num(payload.chains_with_reputation),
|
|
308
386
|
totalReviews: num(payload.total_reviews),
|
|
387
|
+
// `null` when absent or unreadable — NEVER `[]`. See `parseNotComputed`.
|
|
388
|
+
caveatsNotComputed: parseNotComputed(payload.caveats_not_computed),
|
|
309
389
|
policyVersion: optString(payload.policy_version),
|
|
310
390
|
caveats: parseCaveats(payload.caveats),
|
|
311
391
|
caveatScope: CAVEAT_SCOPE_FREE,
|
|
@@ -353,6 +433,7 @@ export function parseWalletBreakdown(
|
|
|
353
433
|
concentration: parseConcentration(payload.concentration),
|
|
354
434
|
confidence: parseConfidence(payload.confidence),
|
|
355
435
|
activity: parseActivity(payload.activity),
|
|
436
|
+
freshness: parseFreshness(payload.freshness),
|
|
356
437
|
snapshot: parseSnapshot(payload.snapshot),
|
|
357
438
|
payment,
|
|
358
439
|
policyVersion: optString(payload.policy_version),
|
|
@@ -446,6 +527,8 @@ export function parseHealth(payload: unknown): IndexHealth {
|
|
|
446
527
|
orderingPolicy: String(payload.ordering_policy ?? ''),
|
|
447
528
|
raterWeightPolicy: String(payload.rater_weight_policy ?? ''),
|
|
448
529
|
confidencePolicy: String(payload.confidence_policy ?? ''),
|
|
530
|
+
credibilityM: optNumber(payload.credibility_m),
|
|
531
|
+
freshness: parseFreshness(payload.freshness),
|
|
449
532
|
confidenceThresholds: isObj(payload.confidence_thresholds)
|
|
450
533
|
? (payload.confidence_thresholds as Record<string, number>)
|
|
451
534
|
: {},
|