uvd-describe-sdk 0.3.0 → 0.5.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/CHANGELOG.md +226 -0
- package/README.md +310 -6
- package/dist/{client-BMfgl1zP.d.mts → client-DOq3Kr0S.d.mts} +261 -26
- package/dist/{client-BMfgl1zP.d.ts → client-DOq3Kr0S.d.ts} +261 -26
- package/dist/{config-DzzhWFYr.d.mts → config-DPJgPNgs.d.mts} +1 -1
- package/dist/{config-DzzhWFYr.d.ts → config-DPJgPNgs.d.ts} +1 -1
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +95 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +92 -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/widget/index.d.mts +243 -0
- package/dist/widget/index.d.ts +243 -0
- package/dist/widget/index.js +450 -0
- package/dist/widget/index.js.map +1 -0
- package/dist/widget/index.mjs +446 -0
- package/dist/widget/index.mjs.map +1 -0
- package/dist/x402/index.d.mts +1 -1
- package/dist/x402/index.d.ts +1 -1
- package/package.json +11 -1
- package/src/caveats.ts +297 -21
- package/src/config.ts +1 -1
- package/src/index.ts +16 -1
- package/src/parse.ts +42 -0
- package/src/types.ts +55 -4
- package/src/widget/card.ts +302 -0
- package/src/widget/element.ts +379 -0
- package/src/widget/index.ts +66 -0
- package/src/widget/theme.ts +143 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Newest first. A version listed here is a version on `main`, **not** a version on
|
|
4
|
+
npm: publishing is a manual run of `publish.yml` on `main` with that version,
|
|
5
|
+
and never part of the change that bumps the number.
|
|
6
|
+
|
|
7
|
+
⚠️ Corrected 2026-09-30 (DN-PUB-01). This read *"publishing is a `vX.Y.Z` tag,
|
|
8
|
+
and the tag is pushed by whoever releases"*. That is how 0.1.0, 0.2.0, 0.3.0
|
|
9
|
+
and 0.4.1 went out. Since DN-PUB-01 a tag on a commit that carries this
|
|
10
|
+
`publish.yml` triggers nothing; older revisions of the file keep their old
|
|
11
|
+
triggers and the stored token until the owner completes steps 3 and 4 of its
|
|
12
|
+
header.
|
|
13
|
+
|
|
14
|
+
This file starts at 0.4.0. The versions before it are summarised from their
|
|
15
|
+
commits, so they are shorter than they deserve — `git log` has the measurements.
|
|
16
|
+
|
|
17
|
+
## Unreleased (DN-PUB-01, no version bump)
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
|
|
21
|
+
- **Publishing is trusted publishing (OIDC), by hand, from `main`** (DN-PUB-01).
|
|
22
|
+
`publish.yml` runs only on `workflow_dispatch` with a `version` input that must
|
|
23
|
+
equal `package.json`, and no longer on a `v*` tag. It holds no npm token: the
|
|
24
|
+
`publish` job, the only one with `id-token: write`, runs in the `npm`
|
|
25
|
+
environment, with no reviewer. `src/publish-workflow.test.ts` fails if
|
|
26
|
+
a token, a trigger other than the dispatch, the environment or the main-only
|
|
27
|
+
check comes back or goes away. CI on `push` now runs only when a file it reads
|
|
28
|
+
changes.
|
|
29
|
+
|
|
30
|
+
## 0.5.0 — 2026-09-30 (not published yet)
|
|
31
|
+
|
|
32
|
+
### Added — `uvd-describe-sdk/widget`
|
|
33
|
+
|
|
34
|
+
One component for "a describe.net score, with its credit", for every surface of
|
|
35
|
+
the stack (WDG-01). Execution Market and MeshRelay showed the credit as a native
|
|
36
|
+
`title=` tooltip; KarmaKadabra had built the one styled card. The subpath takes
|
|
37
|
+
the card from KarmaKadabra, the link rule and the untranslated credit from
|
|
38
|
+
Execution Market, and the custom face from MeshRelay.
|
|
39
|
+
|
|
40
|
+
- **`<describe-score>`**, a custom element with a shadow root, registered only by
|
|
41
|
+
`defineDescribeScore(tagName = 'describe-score')`. It returns `false` and does
|
|
42
|
+
nothing without `customElements` (Node, SSR) or when the tag is taken.
|
|
43
|
+
Importing the subpath registers nothing and touches no `document`.
|
|
44
|
+
- Attributes, each reflected as a property: `score`, `wallet`, `query`,
|
|
45
|
+
`reviews`, `identities`, `chains`, `policy`, `refreshed-at`, `retrieved-at`,
|
|
46
|
+
`lang` (`es` / `en` / `pt`), `theme` (`auto` / `light` / `dark`), `placement`
|
|
47
|
+
(`bottom-start` / `bottom-end`).
|
|
48
|
+
- **`buildDescribeScoreCard(data, lang)`**, the pure model the element paints,
|
|
49
|
+
for tests and for painting the card by hand. Types `DescribeScoreData`,
|
|
50
|
+
`DescribeScoreCard`, `DescribeScoreCardRow`, `DescribeScoreLang`,
|
|
51
|
+
`DescribeScoreElement`, and `DESCRIBE_ATTRIBUTION`.
|
|
52
|
+
- Theme through `--describe-score-*` custom properties, defaulting to
|
|
53
|
+
describe.net's own tokens in both themes; `::part(link)`, `::part(face)`,
|
|
54
|
+
`::part(card)`.
|
|
55
|
+
- `examples/widget.html`, a local demo with no network.
|
|
56
|
+
|
|
57
|
+
### Rules it keeps
|
|
58
|
+
|
|
59
|
+
- An absent, empty or non-decimal score paints "no data", never `0`
|
|
60
|
+
(`Number('')` is `0`, so the element does not use it).
|
|
61
|
+
- No network: no `fetch`, no remote image or font. It paints only what the host
|
|
62
|
+
holds, which is why it does not contradict describe.net publishing no widget
|
|
63
|
+
(`describenet/badge.py:13-24`).
|
|
64
|
+
- No `innerHTML`: every host string lands through `textContent` or an attribute.
|
|
65
|
+
- Zero runtime dependencies. `widget/index` joins the CI check with the empty
|
|
66
|
+
set.
|
|
67
|
+
- A date is formatted only when it is ISO 8601 with a time; anything else is
|
|
68
|
+
shown raw. `new Date()` alone turns `"Version 2"` into Feb 1, 2001 and a bare
|
|
69
|
+
`2026-09-30` into the previous day west of UTC.
|
|
70
|
+
- A `wallet` or `query` that cannot be URL-encoded (a lone surrogate) gets no
|
|
71
|
+
link. `encodeURIComponent` throws there, and uncaught it left the face empty.
|
|
72
|
+
- `Escape` always closes an open card, and is consumed only when the card is
|
|
73
|
+
open by keyboard focus on its trigger. Opened by hover alone, the key still
|
|
74
|
+
reaches the control that has focus.
|
|
75
|
+
|
|
76
|
+
### Measured while building it (details in the README)
|
|
77
|
+
|
|
78
|
+
- React 18.3.1 renders `className` on a custom element as a literal `classname`
|
|
79
|
+
attribute. React 19.2.0 translates it. The README's JSX declaration omits
|
|
80
|
+
`className` so the mistake does not compile.
|
|
81
|
+
- A `<slot>` fallback does not render when the only child is whitespace
|
|
82
|
+
(Chromium: one assigned text node, fallback 0 px wide).
|
|
83
|
+
- Python's `http.server` on Windows serves `.mjs` as `text/plain`, and the
|
|
84
|
+
browser refuses the module.
|
|
85
|
+
- The first viewport clamp measured the card during a `transform` transition
|
|
86
|
+
and let it overflow by 7 px from the second opening on; the shift now lives
|
|
87
|
+
in the untransitioned `translate` property.
|
|
88
|
+
|
|
89
|
+
### Dev only
|
|
90
|
+
|
|
91
|
+
- `happy-dom` (devDependency) for the DOM tests.
|
|
92
|
+
- `package-lock.json` said `0.1.0` in its own `version` field; it now matches.
|
|
93
|
+
|
|
94
|
+
### Also in this version: FG-DN-03, landed on `main` before this bump
|
|
95
|
+
|
|
96
|
+
Listed here as *Unreleased (FG-DN-03, no version bump)* until 0.5.0; it ships
|
|
97
|
+
in 0.5.0.
|
|
98
|
+
|
|
99
|
+
#### Changed
|
|
100
|
+
|
|
101
|
+
- **`schema/` is describe.net's committed spec, vendored.** `schema/openapi.json`
|
|
102
|
+
and `schema/sdk.overlay.yaml` (Overlay 1.0.0) are byte-for-byte copies from
|
|
103
|
+
describe-net, pinned by sha256 in `schema/SOURCE`. They replace the
|
|
104
|
+
hand-refreshed `schema/openapi.snapshot.json`. `npm run schema:refresh` now
|
|
105
|
+
re-vendors from a describe-net checkout instead of writing the live spec.
|
|
106
|
+
- **`schema/sdk-map.json`**: every operation the overlay does not hide is either
|
|
107
|
+
called by a public `DescribeClient` method (`mapeadas`) or listed in `fuera`
|
|
108
|
+
with its reason. `src/sdk-map.test.ts` runs each method against a recording
|
|
109
|
+
`fetch` and fails on an unclassified operation or a route outside the spec.
|
|
110
|
+
- **`schema:check` watches what the map says.** The schemas it compares are
|
|
111
|
+
derived from the responses of the mapped operations (21, transitively; the
|
|
112
|
+
hand-written list had 8), and the operations the overlay hides (web app,
|
|
113
|
+
`/mcp`, `/a2a`) no longer count.
|
|
114
|
+
|
|
115
|
+
#### Unchanged, on purpose
|
|
116
|
+
|
|
117
|
+
- The client, its types and its parsers. `/names/resolve` and `/names/reverse`
|
|
118
|
+
are in `fuera`, not implemented.
|
|
119
|
+
|
|
120
|
+
## 0.4.1 — 2026-09-15 (not published yet)
|
|
121
|
+
|
|
122
|
+
### Added
|
|
123
|
+
|
|
124
|
+
- **`CAVEAT_CODES` gains `thin-chain`** (ten codes, the same set describe.net
|
|
125
|
+
serves). Served since 2026-09-04 on the wallet scope, and evaluated on the free
|
|
126
|
+
route as well: `GET /wallets/{wallet}/chains` evaluates `burn-address` and
|
|
127
|
+
`thin-chain`, and declares the other seven wallet-scope codes in
|
|
128
|
+
`caveatsNotComputed`. `isKnownCaveatCode('thin-chain')` is now `true`. The
|
|
129
|
+
Python twin adds the same literal in its own release.
|
|
130
|
+
|
|
131
|
+
### Unchanged, on purpose
|
|
132
|
+
|
|
133
|
+
- Types, parsers, the client and `requireFullCaveats()` behave exactly as in
|
|
134
|
+
0.4.0. A `thin-chain` caveat already arrived whole; this release only makes it
|
|
135
|
+
a known code (autocomplete, `switch`, `isKnownCaveatCode`).
|
|
136
|
+
|
|
137
|
+
## 0.4.0 — 2026-09-15 (not published yet)
|
|
138
|
+
|
|
139
|
+
Types what describe.net has served since 2026-09-14 (`describe-net` PR #21,
|
|
140
|
+
deployed in `aa1bd75`). Upstream-first: this version exists so that Execution
|
|
141
|
+
Market, KarmaKadabra, MeshRelay and karma-hello adopt the fields through the SDK
|
|
142
|
+
instead of reading them by hand. The Python twin (`uvd-describe-sdk` 0.6.0) ships
|
|
143
|
+
the same contract in its own spelling — same states, same refusals, same class
|
|
144
|
+
name for the error. The one intended difference is the wording of that error's
|
|
145
|
+
`recovery`, which names each language's own API.
|
|
146
|
+
|
|
147
|
+
### Breaking — only for code that builds these objects by hand
|
|
148
|
+
|
|
149
|
+
- `WalletReputation.caveatsNotComputed` and `Rating.authorClass` are
|
|
150
|
+
**required** properties. An object literal typed as `WalletReputation`,
|
|
151
|
+
`Rating`, or `AgentReputation` (through `ratings`) that compiled against 0.3.0
|
|
152
|
+
no longer compiles against 0.4.0: `TS2741: Property 'caveatsNotComputed' is
|
|
153
|
+
missing` / `Property 'authorClass' is missing` (measured with `tsc --strict`).
|
|
154
|
+
Typically a test fixture or a mock. Fix: add the two fields, or build the
|
|
155
|
+
object from a payload with `parseWalletReputation()` / `parseAgentReputation()`,
|
|
156
|
+
which fill them.
|
|
157
|
+
- If you have nothing to put there, write `null` in both — never `[]`, which
|
|
158
|
+
claims every cut was evaluated, and never `'rater-authored'`, which claims a
|
|
159
|
+
signer the index cannot vouch for.
|
|
160
|
+
- They stay required on purpose, and what the parsers return is unchanged.
|
|
161
|
+
Making them optional would add a fourth state, `undefined`, to every result
|
|
162
|
+
of `wallet()` and `agent()`, next to the three (`[]`, a list, `null`) this
|
|
163
|
+
version exists to keep apart.
|
|
164
|
+
- Code that only reads what the client or the parsers return is not affected.
|
|
165
|
+
|
|
166
|
+
### Added
|
|
167
|
+
|
|
168
|
+
- **`WalletReputation.caveatsNotComputed: CaveatCode[] | null`** — the caveat
|
|
169
|
+
codes `GET /wallets/{wallet}/chains` did NOT evaluate (seven on 2026-09-15).
|
|
170
|
+
`null` means nothing readable was declared (a server older than 2026-09-14, a
|
|
171
|
+
stored payload, or a value that is not a list of non-empty strings) and is
|
|
172
|
+
deliberately **not** `[]`, which is a declaration.
|
|
173
|
+
- **`requireFullCaveats(rep)`** — returns `rep` only when it declared `[]`;
|
|
174
|
+
throws `CaveatsNotComputedError` for a declared list AND for `null`; throws a
|
|
175
|
+
`TypeError` for anything that is not the `WalletReputation` of `wallet()`
|
|
176
|
+
(a metered result, a `null` response, a raw payload).
|
|
177
|
+
- **`CaveatsNotComputedError`** (`wallet`, `notComputed`, `recovery`). Extends
|
|
178
|
+
`Error`, **not** `DescribeError`: a consumer's fail-open `catch` on
|
|
179
|
+
`DescribeError` must not be able to swallow a refusal as an outage.
|
|
180
|
+
- **`Rating.authorClass: AuthorClass | null`** — `facilitator-authored` or
|
|
181
|
+
`rater-authored`, per row. An unknown class arrives verbatim (never thrown,
|
|
182
|
+
never nulled); `null` means none was served.
|
|
183
|
+
- **`AUTHOR_CLASSES`, `isKnownAuthorClass()`, `AuthorClass`, `KnownAuthorClass`.**
|
|
184
|
+
- **`CAVEAT_CODES` gains `facilitator-authored`** (nine codes).
|
|
185
|
+
|
|
186
|
+
### Known gap
|
|
187
|
+
|
|
188
|
+
- describe.net serves ten caveat codes; **`thin-chain`** (upstream since
|
|
189
|
+
2026-09-04, on the free route since 2026-09-05) is still missing here and in
|
|
190
|
+
the Python twin. Left for one follow-up that adds it to both, so the set both
|
|
191
|
+
SDKs publish never differs. `isKnownCaveatCode('thin-chain')` is `false`; the
|
|
192
|
+
caveat itself still arrives whole.
|
|
193
|
+
|
|
194
|
+
### Changed
|
|
195
|
+
|
|
196
|
+
- `schema/openapi.snapshot.json` refreshed from the live API (2.0.0, 22 paths:
|
|
197
|
+
`GET /categories` and `GET /wallets/{wallet}/exists` are new and not wrapped).
|
|
198
|
+
- `npm run schema:check` now also watches `Rating`, and `types.schema.test.ts`
|
|
199
|
+
covers it. Neither did before, which is how `author_class` becoming a required
|
|
200
|
+
field upstream went unreported by the refresh.
|
|
201
|
+
|
|
202
|
+
### Unchanged, on purpose
|
|
203
|
+
|
|
204
|
+
- No method changed its return type (the types it returns gained two required
|
|
205
|
+
fields — see *Breaking*), nothing throws where it did not, and
|
|
206
|
+
`DescribeErrorKind` is untouched. The client never calls the gate; `failOpen`
|
|
207
|
+
and `onFailure` behave exactly as in 0.3.0.
|
|
208
|
+
|
|
209
|
+
## 0.3.0 — 2026-09-10
|
|
210
|
+
|
|
211
|
+
`freshness`: WHEN a subject was last described, with its scope
|
|
212
|
+
(`WalletBreakdown.freshness`, `IndexHealth.freshness`), plus
|
|
213
|
+
`IndexHealth.credibilityM`. (#1, `764cab1`)
|
|
214
|
+
|
|
215
|
+
## 0.2.0 — 2026-08-31
|
|
216
|
+
|
|
217
|
+
The SDK review round: the `pending` settlement sentinel moved out of `receipt`
|
|
218
|
+
into `settlementPending`, `DescribeHTTPError.serverReason`, and parsers that fail
|
|
219
|
+
loud when fed the wrong route's payload or their own output. (`923a9d6`)
|
|
220
|
+
|
|
221
|
+
## 0.1.0 — 2026-08-30
|
|
222
|
+
|
|
223
|
+
First version: the free routes with `failOpen`, the metered routes paid through
|
|
224
|
+
`uvd-describe-sdk/x402` (and, the same day, never failing open), the partner rail,
|
|
225
|
+
jitter, `resolveDistinctRaters`, hash-shape validation and `recovery`.
|
|
226
|
+
(`99a87b2` … `8deb0c9`)
|
package/README.md
CHANGED
|
@@ -17,6 +17,10 @@ subpaths so a free-only consumer installs neither:
|
|
|
17
17
|
each request instead and read the metered routes for free
|
|
18
18
|
(`uvd-describe-sdk/partner`, see [the partner rail](#not-paying-the-partner-rail)).
|
|
19
19
|
|
|
20
|
+
And to **draw** a score once you have it, `uvd-describe-sdk/widget` is
|
|
21
|
+
`<describe-score>`: the number, its credit and its card, one component for every
|
|
22
|
+
surface. It makes no network call. See [Widget](#widget-describe-score).
|
|
23
|
+
|
|
20
24
|
---
|
|
21
25
|
|
|
22
26
|
## Sixty seconds
|
|
@@ -119,16 +123,65 @@ if (hasCaveat(rep, 'burn-address')) { /* nobody controls this address */ }
|
|
|
119
123
|
if (hasCaveat(rep, 'few-raters')) { /* thin evidence */ }
|
|
120
124
|
```
|
|
121
125
|
|
|
122
|
-
The
|
|
126
|
+
The ten codes are exported and typed: `no-score`, `concentration-degraded`,
|
|
123
127
|
`single-rater`, `few-raters`, `top-client-share`, `campaign-per-rater`,
|
|
124
|
-
`self-rated`, `burn-address
|
|
125
|
-
|
|
128
|
+
`self-rated`, `burn-address`, `thin-chain` (since 0.4.1; served since 2026-09-04,
|
|
129
|
+
on the free route too), `facilitator-authored` (since 0.4.0). The union stays
|
|
130
|
+
**open**, so a code the server adds tomorrow will not be a type error in code you
|
|
131
|
+
already shipped: `isKnownCaveatCode()` answers `false` for it, and the caveat
|
|
132
|
+
still arrives whole.
|
|
126
133
|
|
|
127
134
|
⚠️ On free routes `caveats: []` means *no **public-data** caveat*, not "clean" —
|
|
128
135
|
the evidence-quality cuts need the grain and ride the metered routes. Check
|
|
129
136
|
`rep.caveatScope` (`public-data-subset` vs `full`) before calling anything
|
|
130
137
|
clean.
|
|
131
138
|
|
|
139
|
+
**Since 0.4.0 the free route names the cuts it skipped, and there is a gate for
|
|
140
|
+
it.** karma-hello found the trap (2026-08-31): a quality gate on `wallet()`
|
|
141
|
+
passes *every* wallet, because the cuts it checks never ran. describe.net now
|
|
142
|
+
declares them in `caveats_not_computed` (`rep.caveatsNotComputed`), and
|
|
143
|
+
`requireFullCaveats` is the gate that reads the declaration:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
import { CaveatsNotComputedError, requireFullCaveats } from 'uvd-describe-sdk';
|
|
147
|
+
|
|
148
|
+
const rep = await describe.wallet(w);
|
|
149
|
+
if (rep === null) { /* no answer at all: decide that first */ }
|
|
150
|
+
|
|
151
|
+
try {
|
|
152
|
+
requireFullCaveats(rep);
|
|
153
|
+
} catch (e) {
|
|
154
|
+
if (e instanceof CaveatsNotComputedError) {
|
|
155
|
+
e.notComputed; // ['campaign-per-rater', …] — or null: nothing was declared
|
|
156
|
+
e.recovery; // the route that does evaluate them
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
| `rep.caveatsNotComputed` | `requireFullCaveats(rep)` |
|
|
162
|
+
|---|---|
|
|
163
|
+
| `[]` | returns `rep` — the only state that passes |
|
|
164
|
+
| `['few-raters', …]` | throws; `notComputed` is the list |
|
|
165
|
+
| `null` — a server before 2026-09-14, a payload stored before then, or a declaration that cannot be read whole | **throws**; `notComputed` is `null` |
|
|
166
|
+
|
|
167
|
+
🔴 **Today it throws for every free answer** (seven codes declared on
|
|
168
|
+
2026-09-15). That is the gate working: the evidence-quality cuts are what
|
|
169
|
+
`walletBreakdown()` sells, and a decision that needs them reads that — or the
|
|
170
|
+
partner rail. `null` is not `[]`: an old answer's silence is the old gap, not a
|
|
171
|
+
clean bill (describe.net's position of 2026-08-31 is *"el scope es la señal"*,
|
|
172
|
+
and its own MCP tool keeps the same `None`). Passing means the caveats are
|
|
173
|
+
**complete**, not empty — ask `hasCaveat()` after the gate.
|
|
174
|
+
|
|
175
|
+
Two things it is not, on purpose — and the Python twin (`require_full_caveats`,
|
|
176
|
+
`CaveatsNotComputedError`) makes the same two choices:
|
|
177
|
+
|
|
178
|
+
* **Not a `DescribeError`.** A refusal is a successful read that does not support
|
|
179
|
+
the decision. A `catch` that fails open on `DescribeError` must not be able to
|
|
180
|
+
read it as "describe is down" and wave the subject through.
|
|
181
|
+
* **Not for metered results.** It takes the `WalletReputation` of `wallet()` and
|
|
182
|
+
throws a `TypeError` for anything else: a breakdown evaluates its own scope and
|
|
183
|
+
declares no omissions.
|
|
184
|
+
|
|
132
185
|
### 4. One display format, ecosystem-wide
|
|
133
186
|
|
|
134
187
|
**Two decimals, trailing zeros trimmed.** `86.65`, `84.7`, `87` — never `82.0`.
|
|
@@ -462,6 +515,228 @@ server already knows which is which. Measured cost of signing everything:
|
|
|
462
515
|
|
|
463
516
|
---
|
|
464
517
|
|
|
518
|
+
## Widget: `<describe-score>`
|
|
519
|
+
|
|
520
|
+
One component for "a describe.net score, with its credit", for every surface of
|
|
521
|
+
the stack. Until 0.5.0 three repos drew it three ways: Execution Market and
|
|
522
|
+
MeshRelay put `Powered by describe.net` in a native `title=` (the grey box the
|
|
523
|
+
operating system draws), and KarmaKadabra built a styled card. This is that card,
|
|
524
|
+
with EM's link rule and credit and MeshRelay's custom face, behind its own
|
|
525
|
+
subpath so that importing the root in Node never meets a DOM.
|
|
526
|
+
|
|
527
|
+

|
|
528
|
+
|
|
529
|
+
```ts
|
|
530
|
+
import { defineDescribeScore } from 'uvd-describe-sdk/widget';
|
|
531
|
+
|
|
532
|
+
defineDescribeScore(); // registers <describe-score>. Importing registers nothing.
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
```html
|
|
536
|
+
<describe-score score="83.0" wallet="0x97cd…0996" reviews="123"
|
|
537
|
+
policy="equal-weight-per-chain@2" refreshed-at="2026-09-30T14:15:39Z"
|
|
538
|
+
lang="es"></describe-score>
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
`defineDescribeScore()` returns `false` and does nothing where there is no
|
|
542
|
+
`customElements` (Node, SSR) or when the tag is already defined, so calling it
|
|
543
|
+
at module scope in a server-rendered app is safe. `defineDescribeScore('my-tag')`
|
|
544
|
+
registers another name.
|
|
545
|
+
|
|
546
|
+
### It makes no network call, and that is why it can exist
|
|
547
|
+
|
|
548
|
+
describe.net deliberately publishes no widget (`describenet/badge.py:13-24`): only
|
|
549
|
+
an `<img>` + SVG, because a site that embeds a widget which *transmits* data is
|
|
550
|
+
co-responsible for it, and because a `fetch` per pageview would burn a rate limit
|
|
551
|
+
every consumer shares. This component does not contradict that. It fetches
|
|
552
|
+
nothing, loads no image and no font, and paints only what the host already read
|
|
553
|
+
through `DescribeClient`. It draws a number; it does not get one. The only URL in
|
|
554
|
+
it is the link to the public profile, which the reader chooses to follow.
|
|
555
|
+
|
|
556
|
+
### `null` is never `0`, here either
|
|
557
|
+
|
|
558
|
+
An absent, empty or non-numeric `score` paints **"no data"** (`sin datos`,
|
|
559
|
+
`sem dados`), never `0`. Pass `rep.globalScore` as it comes: React drops the
|
|
560
|
+
attribute for `null` (measured on React 18.3.1 and 19.2.0), and the element
|
|
561
|
+
reads an absent attribute as no data. It does not use `Number(attr)`, because
|
|
562
|
+
`Number('')` is `0`. A real `0` is a score and paints `0`.
|
|
563
|
+
|
|
564
|
+
### Attributes
|
|
565
|
+
|
|
566
|
+
Every attribute is also a property that reflects it (`el.refreshedAt` ↔
|
|
567
|
+
`refreshed-at`).
|
|
568
|
+
|
|
569
|
+
| Attribute | What it carries | Shown as |
|
|
570
|
+
|---|---|---|
|
|
571
|
+
| `score` | `globalScore` | the face, written by `formatScore` (`83.0` → `83`) |
|
|
572
|
+
| `wallet` | EVM or Solana base58 | link to `describe.net/agent.html?wallet=…` |
|
|
573
|
+
| `query` | fallback lookup | `?q=…` when there is no wallet. With neither — or with a value that cannot be URL-encoded, such as a name cut in half an emoji — **no link** |
|
|
574
|
+
| `reviews` · `identities` · `chains` · `policy` | `totalReviews` · `identityCount` · `chainsWithReputation` · `policyVersion` | a row each, **only if it came** |
|
|
575
|
+
| `refreshed-at` · `retrieved-at` | when describe.net refreshed it · when you read it (ISO 8601 with a time) | a readable date (`Intl`, medium + short). Anything else is shown raw — a bare `2026-09-30` too, which `new Date()` would print as the previous day west of UTC |
|
|
576
|
+
| `lang` | `es` \| `en` \| `pt`, or a full tag (`es-CO`) | default: `<html lang>`, then `en`. Read at render, so a host that switches language at runtime passes it |
|
|
577
|
+
| `theme` | `auto` (default) \| `light` \| `dark` | `auto` follows `prefers-color-scheme` |
|
|
578
|
+
| `placement` | `bottom-start` (default) \| `bottom-end` | the card is kept inside the viewport either way |
|
|
579
|
+
|
|
580
|
+
The credit (`Powered by describe.net`, and `POWERED BY DESCRIBE.NET` on the
|
|
581
|
+
card) is **never translated**. It is exported as `DESCRIBE_ATTRIBUTION` for the
|
|
582
|
+
one visible credit a site carries in its footer.
|
|
583
|
+
|
|
584
|
+
🔴 **Tailwind `darkMode: 'class'` is invisible to a shadow root.** A media query
|
|
585
|
+
cannot see a `.dark` class on `<html>`, and `:host-context()` is Chromium-only.
|
|
586
|
+
A host that themes by class (Execution Market) passes `theme` itself.
|
|
587
|
+
|
|
588
|
+
### The face
|
|
589
|
+
|
|
590
|
+
With no children the element paints the formatted score and inherits the font
|
|
591
|
+
and colour of the element, so the host's classes style the number. With
|
|
592
|
+
children, the children are the face (MeshRelay's bar):
|
|
593
|
+
|
|
594
|
+
```html
|
|
595
|
+
<describe-score score="81.86" wallet="0x…"><span class="bar">…</span></describe-score>
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
Whitespace does not count as a child. A plain `<slot>` fallback would show
|
|
599
|
+
nothing for `<describe-score score="83">⏎</describe-score>`: measured in
|
|
600
|
+
Chromium, one whitespace text node is assigned to the slot and the fallback
|
|
601
|
+
measures 0 px.
|
|
602
|
+
|
|
603
|
+
### Styling
|
|
604
|
+
|
|
605
|
+
| Custom property | Default (light / dark), from describe.net's `theme-describeme.css` |
|
|
606
|
+
|---|---|
|
|
607
|
+
| `--describe-score-bg` | `#ffffff` / `#1e1b2d` (`--surface-raised`). Painted with `background`, so a gradient works |
|
|
608
|
+
| `--describe-score-border` | `#e2ded4` / `#2c2840` (`--border-subtle`) |
|
|
609
|
+
| `--describe-score-text` | `#1a1730` / `#f2f0ea` (`--text-primary`) |
|
|
610
|
+
| `--describe-score-text-secondary` | `#4a4668` / `#c3bfd4` (`--text-secondary`) |
|
|
611
|
+
| `--describe-score-accent` | `#332c86` / `#a9a2ff` (`--accent`) |
|
|
612
|
+
| `--describe-score-radius` | `0.375rem` (`--radius-surface`) |
|
|
613
|
+
| `--describe-score-shadow` | `--shadow-overlay` |
|
|
614
|
+
| `--describe-score-font` | the system sans stack. The card never inherits the number's font |
|
|
615
|
+
|
|
616
|
+
The contrast of every default text colour against its background is computed
|
|
617
|
+
in the tests (WCAG AA, both themes). Parts: `::part(link)`, `::part(face)`,
|
|
618
|
+
`::part(card)`.
|
|
619
|
+
|
|
620
|
+
```css
|
|
621
|
+
/* KarmaKadabra's card, through the properties */
|
|
622
|
+
describe-score {
|
|
623
|
+
--describe-score-bg: linear-gradient(160deg, #4c2f8f 0%, #3b2470 100%);
|
|
624
|
+
--describe-score-border: rgba(201, 162, 255, .34);
|
|
625
|
+
--describe-score-text: #f3efff;
|
|
626
|
+
--describe-score-text-secondary: #d9ccff;
|
|
627
|
+
--describe-score-accent: #c9a2ff;
|
|
628
|
+
}
|
|
629
|
+
/* Mute the NUMBER, not the element: */
|
|
630
|
+
describe-score.empty::part(face) { opacity: .6; }
|
|
631
|
+
```
|
|
632
|
+
|
|
633
|
+
⚠️ `opacity`, `filter` and `transform` on the element itself apply to its whole
|
|
634
|
+
box, **card included**. Style the number through `::part(face)`. The card is
|
|
635
|
+
positioned inside the element, so an ancestor with `overflow: hidden` clips it.
|
|
636
|
+
The element puts a `<style>` in its shadow root; a Content-Security-Policy whose
|
|
637
|
+
`style-src` forbids inline styles would block it (none of the three hosts sends
|
|
638
|
+
one as of 2026-09-30).
|
|
639
|
+
|
|
640
|
+
### Accessibility (WCAG 1.4.13, 2.1.1)
|
|
641
|
+
|
|
642
|
+
- The card opens on **hover and on keyboard focus**. With a link, the link is
|
|
643
|
+
the trigger; without one, the face takes `tabindex="0"`, so the card that
|
|
644
|
+
explains "no data" can still be read without a mouse.
|
|
645
|
+
- The trigger's `aria-describedby` points to the card (`role="tooltip"`).
|
|
646
|
+
- **Hoverable**: a transparent bridge covers the gap between number and card.
|
|
647
|
+
- **Dismissible**: `Escape` closes it without moving focus. When the card is
|
|
648
|
+
open because its trigger has keyboard focus, that `Escape` is consumed, so a
|
|
649
|
+
modal behind it (EM renders scores inside modals) does not close on the same
|
|
650
|
+
keypress. When it is open by hover alone, it closes and the `Escape` still
|
|
651
|
+
reaches the control that has focus (a textarea, a combobox). While no card is
|
|
652
|
+
open nothing listens.
|
|
653
|
+
- `prefers-reduced-motion` removes the transition. The card is clamped to the
|
|
654
|
+
viewport on narrow screens.
|
|
655
|
+
|
|
656
|
+
### React (Execution Market, MeshRelay)
|
|
657
|
+
|
|
658
|
+
Declare the element once in the host, for example `src/types/describe-score.d.ts`
|
|
659
|
+
(type-checked against `@types/react` 18.3.3 and 19.2.5):
|
|
660
|
+
|
|
661
|
+
```ts
|
|
662
|
+
import type { HTMLAttributes } from 'react';
|
|
663
|
+
|
|
664
|
+
type DescribeScoreAttributes = Omit<HTMLAttributes<HTMLElement>, 'className'> & {
|
|
665
|
+
/** React 18 writes `className` on a custom element as a literal `classname` attribute. */
|
|
666
|
+
class?: string;
|
|
667
|
+
score?: number | string | null;
|
|
668
|
+
wallet?: string | null;
|
|
669
|
+
query?: string | null;
|
|
670
|
+
reviews?: number | string | null;
|
|
671
|
+
identities?: number | string | null;
|
|
672
|
+
chains?: number | string | null;
|
|
673
|
+
policy?: string | null;
|
|
674
|
+
'refreshed-at'?: string | null;
|
|
675
|
+
'retrieved-at'?: string | null;
|
|
676
|
+
theme?: 'auto' | 'light' | 'dark';
|
|
677
|
+
placement?: 'bottom-start' | 'bottom-end';
|
|
678
|
+
};
|
|
679
|
+
|
|
680
|
+
declare module 'react' {
|
|
681
|
+
namespace JSX {
|
|
682
|
+
interface IntrinsicElements {
|
|
683
|
+
'describe-score': DescribeScoreAttributes;
|
|
684
|
+
}
|
|
685
|
+
}
|
|
686
|
+
}
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
```tsx
|
|
690
|
+
import { defineDescribeScore } from 'uvd-describe-sdk/widget';
|
|
691
|
+
defineDescribeScore();
|
|
692
|
+
|
|
693
|
+
<describe-score
|
|
694
|
+
class="text-sm font-semibold"
|
|
695
|
+
score={rep.globalScore}
|
|
696
|
+
wallet={rep.wallet}
|
|
697
|
+
reviews={rep.totalReviews}
|
|
698
|
+
identities={rep.identityCount}
|
|
699
|
+
policy={rep.policyVersion}
|
|
700
|
+
refreshed-at={rep.refreshedAt}
|
|
701
|
+
lang={i18n.language}
|
|
702
|
+
theme={isDark ? 'dark' : 'light'}
|
|
703
|
+
/>
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
🔴 **On React 18, `className` does not work on a custom element.** Measured with
|
|
707
|
+
React 18.3.1: `<describe-score className="text-sm">` renders the attribute
|
|
708
|
+
`classname="text-sm"`, which no stylesheet matches. React 19 translates it to
|
|
709
|
+
`class`. The declaration above leaves `className` out so the React 18 mistake is
|
|
710
|
+
a compile error; on React 19 (MeshRelay) you may drop the `Omit`.
|
|
711
|
+
|
|
712
|
+
### HTML without a bundler (KarmaKadabra)
|
|
713
|
+
|
|
714
|
+
`dist/widget/index.mjs` imports nothing (asserted in CI), so it vendors as one file:
|
|
715
|
+
|
|
716
|
+
```html
|
|
717
|
+
<script type="module">
|
|
718
|
+
import { defineDescribeScore } from '/vendor/uvd-describe-sdk/widget.mjs';
|
|
719
|
+
defineDescribeScore();
|
|
720
|
+
</script>
|
|
721
|
+
```
|
|
722
|
+
|
|
723
|
+
⚠️ **The server must send `.mjs` as `text/javascript`.** A module served as
|
|
724
|
+
`text/plain` is refused by the browser and nothing renders. Measured: Python's
|
|
725
|
+
`http.server` on Windows guesses `text/plain` for `.mjs`. Check the
|
|
726
|
+
`Content-Type` your server or bucket gives the file, or vendor it as `.js`.
|
|
727
|
+
|
|
728
|
+
### Painting it yourself
|
|
729
|
+
|
|
730
|
+
`buildDescribeScoreCard(data, lang)` returns what the card shows (`face`,
|
|
731
|
+
`title`, `seal`, `text`, `rows`, `href`, `hasScore`, `openHint`) with no DOM and
|
|
732
|
+
no network. Use it to test a surface in Node, or to draw the same card where a
|
|
733
|
+
custom element cannot run.
|
|
734
|
+
|
|
735
|
+
Demo, no network: `npm run build`, serve the repo root (`npx serve .`), open
|
|
736
|
+
`/examples/widget.html` (add `?pin` to open every card at once).
|
|
737
|
+
|
|
738
|
+
---
|
|
739
|
+
|
|
465
740
|
## Jitter, on by default
|
|
466
741
|
|
|
467
742
|
Every request waits a random `[0, 400)` ms first. **That is on unless you turn
|
|
@@ -548,6 +823,33 @@ and an alarm that screams about good data is worse than no alarm.
|
|
|
548
823
|
|
|
549
824
|
---
|
|
550
825
|
|
|
826
|
+
## Who signed a rating: `authorClass`
|
|
827
|
+
|
|
828
|
+
Since describe.net 2026-09-14 every row of `agent().ratings` carries the class of
|
|
829
|
+
whoever **signed** it:
|
|
830
|
+
|
|
831
|
+
```ts
|
|
832
|
+
const agent = await describe.agent('base', 42);
|
|
833
|
+
const relayed = agent.ratings.filter((r) => r.authorClass === 'facilitator-authored');
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
* `facilitator-authored` — `client` is a known relayer (today the x402
|
|
837
|
+
facilitator's EVM wallet) writing on behalf of the real rater. `client` is
|
|
838
|
+
**not** the counterparty, and every such row shares it, so any per-rater count
|
|
839
|
+
merges them into one voice. The agent answer then also carries the caveat of
|
|
840
|
+
the same name.
|
|
841
|
+
* `rater-authored` — `client` is not a relayer the index knows about. It does
|
|
842
|
+
**not** prove who signed.
|
|
843
|
+
* `null` — no class was served (an older server, or a stored payload). Unknown,
|
|
844
|
+
and never defaulted to `rater-authored`.
|
|
845
|
+
|
|
846
|
+
The union is **open**: a class the server adds later arrives verbatim — never
|
|
847
|
+
thrown, never nulled — and `isKnownAuthorClass()` tells you whether this SDK has
|
|
848
|
+
heard of it. There is no count or score by author class, upstream or here; what
|
|
849
|
+
to do with the rows you bought is your call.
|
|
850
|
+
|
|
851
|
+
---
|
|
852
|
+
|
|
551
853
|
## Counting distinct raters
|
|
552
854
|
|
|
553
855
|
```ts
|
|
@@ -631,8 +933,10 @@ Never hardcode a threshold. `health()` publishes the live `readingPolicy` and
|
|
|
631
933
|
|
|
632
934
|
Hand-written, and tied to the schema by two gates rather than by a generator:
|
|
633
935
|
|
|
634
|
-
- `npm test` — offline, compares the types against
|
|
635
|
-
`schema/
|
|
936
|
+
- `npm test` — offline, compares the types against `schema/openapi.json`, the
|
|
937
|
+
describe.net spec vendored with its sha256 in `schema/SOURCE`, and checks
|
|
938
|
+
`schema/sdk-map.json`: every public operation is called by a method or listed
|
|
939
|
+
in `fuera` with its reason. Answers *did we drift?*
|
|
636
940
|
- `npm run schema:check` — re-fetches the live OpenAPI and diffs it. Answers
|
|
637
941
|
*did they move?*
|
|
638
942
|
|
|
@@ -650,7 +954,7 @@ cycle.
|
|
|
650
954
|
|
|
651
955
|
```bash
|
|
652
956
|
npm install
|
|
653
|
-
npm test # offline.
|
|
957
|
+
npm test # offline, no network. 336 tests on 2026-09-30 (227 on 2026-09-15)
|
|
654
958
|
npm run typecheck
|
|
655
959
|
npm run lint
|
|
656
960
|
npm run build
|