uvd-describe-sdk 0.4.1 → 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 +112 -2
- package/README.md +231 -3
- package/dist/{client-0sg4J53x.d.mts → client-DOq3Kr0S.d.mts} +6 -4
- package/dist/{client-0sg4J53x.d.ts → client-DOq3Kr0S.d.ts} +6 -4
- package/dist/{config-gjJ08BUJ.d.mts → config-DPJgPNgs.d.mts} +1 -1
- package/dist/{config-gjJ08BUJ.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 +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1 -1
- 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 +10 -1
- package/src/caveats.ts +1 -1
- package/src/config.ts +1 -1
- package/src/types.ts +5 -3
- 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
CHANGED
|
@@ -1,12 +1,122 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
3
|
Newest first. A version listed here is a version on `main`, **not** a version on
|
|
4
|
-
npm: publishing is a `
|
|
5
|
-
never
|
|
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.
|
|
6
13
|
|
|
7
14
|
This file starts at 0.4.0. The versions before it are summarised from their
|
|
8
15
|
commits, so they are shorter than they deserve — `git log` has the measurements.
|
|
9
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
|
+
|
|
10
120
|
## 0.4.1 — 2026-09-15 (not published yet)
|
|
11
121
|
|
|
12
122
|
### Added
|
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
|
|
@@ -511,6 +515,228 @@ server already knows which is which. Measured cost of signing everything:
|
|
|
511
515
|
|
|
512
516
|
---
|
|
513
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
|
+
|
|
514
740
|
## Jitter, on by default
|
|
515
741
|
|
|
516
742
|
Every request waits a random `[0, 400)` ms first. **That is on unless you turn
|
|
@@ -707,8 +933,10 @@ Never hardcode a threshold. `health()` publishes the live `readingPolicy` and
|
|
|
707
933
|
|
|
708
934
|
Hand-written, and tied to the schema by two gates rather than by a generator:
|
|
709
935
|
|
|
710
|
-
- `npm test` — offline, compares the types against
|
|
711
|
-
`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?*
|
|
712
940
|
- `npm run schema:check` — re-fetches the live OpenAPI and diffs it. Answers
|
|
713
941
|
*did they move?*
|
|
714
942
|
|
|
@@ -726,7 +954,7 @@ cycle.
|
|
|
726
954
|
|
|
727
955
|
```bash
|
|
728
956
|
npm install
|
|
729
|
-
npm test # offline, no network.
|
|
957
|
+
npm test # offline, no network. 336 tests on 2026-09-30 (227 on 2026-09-15)
|
|
730
958
|
npm run typecheck
|
|
731
959
|
npm run lint
|
|
732
960
|
npm run build
|
|
@@ -747,7 +747,7 @@ declare function requireFullCaveats(result: WalletReputation): WalletReputation;
|
|
|
747
747
|
* The two classes served in `ratings[].author_class` since describe.net
|
|
748
748
|
* 2026-09-14 — the schema's own enum (`describenet/api.py:962`,
|
|
749
749
|
* `Literal["facilitator-authored", "rater-authored"]`), and
|
|
750
|
-
* `types.schema.test.ts` pins this tuple against the
|
|
750
|
+
* `types.schema.test.ts` pins this tuple against the vendored spec's `enum`. The
|
|
751
751
|
* Python twin calls the same set `KNOWN_AUTHOR_CLASSES`, the way it calls
|
|
752
752
|
* `CAVEAT_CODES` `KNOWN_CAVEAT_CODES`.
|
|
753
753
|
*
|
|
@@ -815,10 +815,12 @@ declare function isKnownAuthorClass(value: string | null | undefined): value is
|
|
|
815
815
|
* schema, at two speeds.
|
|
816
816
|
*
|
|
817
817
|
* * `types.schema.test.ts` runs in the normal loop, offline, against
|
|
818
|
-
* `schema/openapi.
|
|
819
|
-
* 2026-
|
|
818
|
+
* `schema/openapi.json` — describe.net's committed spec, vendored (until
|
|
819
|
+
* 2026-09-28, `schema/openapi.snapshot.json`, a pinned copy of the live
|
|
820
|
+
* schema fetched 2026-08-30). It fails when a hand-written type drifts
|
|
821
|
+
* from the schema.
|
|
820
822
|
* * `npm run schema:check` re-fetches the live schema and diffs it against
|
|
821
|
-
* the
|
|
823
|
+
* the vendored spec. It fails when the SERVER moves. Deliberate, networked, and
|
|
822
824
|
* never in the test loop (tests do not touch the network).
|
|
823
825
|
*
|
|
824
826
|
* Two gates because there are two different failures: we drifted, and they
|
|
@@ -747,7 +747,7 @@ declare function requireFullCaveats(result: WalletReputation): WalletReputation;
|
|
|
747
747
|
* The two classes served in `ratings[].author_class` since describe.net
|
|
748
748
|
* 2026-09-14 — the schema's own enum (`describenet/api.py:962`,
|
|
749
749
|
* `Literal["facilitator-authored", "rater-authored"]`), and
|
|
750
|
-
* `types.schema.test.ts` pins this tuple against the
|
|
750
|
+
* `types.schema.test.ts` pins this tuple against the vendored spec's `enum`. The
|
|
751
751
|
* Python twin calls the same set `KNOWN_AUTHOR_CLASSES`, the way it calls
|
|
752
752
|
* `CAVEAT_CODES` `KNOWN_CAVEAT_CODES`.
|
|
753
753
|
*
|
|
@@ -815,10 +815,12 @@ declare function isKnownAuthorClass(value: string | null | undefined): value is
|
|
|
815
815
|
* schema, at two speeds.
|
|
816
816
|
*
|
|
817
817
|
* * `types.schema.test.ts` runs in the normal loop, offline, against
|
|
818
|
-
* `schema/openapi.
|
|
819
|
-
* 2026-
|
|
818
|
+
* `schema/openapi.json` — describe.net's committed spec, vendored (until
|
|
819
|
+
* 2026-09-28, `schema/openapi.snapshot.json`, a pinned copy of the live
|
|
820
|
+
* schema fetched 2026-08-30). It fails when a hand-written type drifts
|
|
821
|
+
* from the schema.
|
|
820
822
|
* * `npm run schema:check` re-fetches the live schema and diffs it against
|
|
821
|
-
* the
|
|
823
|
+
* the vendored spec. It fails when the SERVER moves. Deliberate, networked, and
|
|
822
824
|
* never in the test loop (tests do not touch the network).
|
|
823
825
|
*
|
|
824
826
|
* Two gates because there are two different failures: we drifted, and they
|
|
@@ -138,7 +138,7 @@ declare const PARTNER_KEY_ENV = "DESCRIBE_PARTNER_PRIVATE_KEY";
|
|
|
138
138
|
* time instead of at runtime. Bumping the version without the constant is a
|
|
139
139
|
* red test, not a silent lie in someone's access log.
|
|
140
140
|
*/
|
|
141
|
-
declare const SDK_VERSION = "0.
|
|
141
|
+
declare const SDK_VERSION = "0.5.0";
|
|
142
142
|
/** `uvd-describe-sdk-ts/0.1.0`, plus `(+<product>)` when the caller names itself. */
|
|
143
143
|
declare const SDK_NAME = "uvd-describe-sdk-ts";
|
|
144
144
|
/**
|
|
@@ -138,7 +138,7 @@ declare const PARTNER_KEY_ENV = "DESCRIBE_PARTNER_PRIVATE_KEY";
|
|
|
138
138
|
* time instead of at runtime. Bumping the version without the constant is a
|
|
139
139
|
* red test, not a silent lie in someone's access log.
|
|
140
140
|
*/
|
|
141
|
-
declare const SDK_VERSION = "0.
|
|
141
|
+
declare const SDK_VERSION = "0.5.0";
|
|
142
142
|
/** `uvd-describe-sdk-ts/0.1.0`, plus `(+<product>)` when the caller names itself. */
|
|
143
143
|
declare const SDK_NAME = "uvd-describe-sdk-ts";
|
|
144
144
|
/**
|
package/dist/index.d.mts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
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-
|
|
2
|
-
export { b as AUTHOR_CLASSES, c as Activity, d as AuthorClass, C as CAVEAT_CODES, e as CAVEAT_SCOPE_FREE, f as CAVEAT_SCOPE_METERED, g as Caveat, h as CaveatCode, i as CaveatsNotComputedError, j as Concentration, k as Confidence, l as DescribeClient, m as DescribeClientConfig, n as DescribeError, o as DescribeFailure, p as DescribeHTTPError, q as DescribeMalformedHash, r as DescribeNotFound, s as DescribePartnerRejected, t as DescribePartnerUnsigned, u as DescribePaymentRefused, v as DescribePaymentRequired, w as DescribeTimeout, x as DescribeUnparseable, y as DescribeUnreachable, F as Facet, z as Freshness, B as FreshnessScope, H as HealthChain, K as KnownAuthorClass, E as KnownCaveatCode, N as Network, O as Ownership, G as PartnerSigner, J as PaymentAttempt, R as Rating, S as Sealed, M as SelfRated, Q as Snapshot, T as Timestamp, U as WalletChainRow, X as X402Challenge, V as X402Payer, Y as failOpenCovers, Z as failedAfterPaying, _ as hasCaveat, $ as isKnownAuthorClass, a0 as isKnownCaveatCode, a1 as requireFullCaveats } from './client-
|
|
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-
|
|
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-DOq3Kr0S.mjs';
|
|
2
|
+
export { b as AUTHOR_CLASSES, c as Activity, d as AuthorClass, C as CAVEAT_CODES, e as CAVEAT_SCOPE_FREE, f as CAVEAT_SCOPE_METERED, g as Caveat, h as CaveatCode, i as CaveatsNotComputedError, j as Concentration, k as Confidence, l as DescribeClient, m as DescribeClientConfig, n as DescribeError, o as DescribeFailure, p as DescribeHTTPError, q as DescribeMalformedHash, r as DescribeNotFound, s as DescribePartnerRejected, t as DescribePartnerUnsigned, u as DescribePaymentRefused, v as DescribePaymentRequired, w as DescribeTimeout, x as DescribeUnparseable, y as DescribeUnreachable, F as Facet, z as Freshness, B as FreshnessScope, H as HealthChain, K as KnownAuthorClass, E as KnownCaveatCode, N as Network, O as Ownership, G as PartnerSigner, J as PaymentAttempt, R as Rating, S as Sealed, M as SelfRated, Q as Snapshot, T as Timestamp, U as WalletChainRow, X as X402Challenge, V as X402Payer, Y as failOpenCovers, Z as failedAfterPaying, _ as hasCaveat, $ as isKnownAuthorClass, a0 as isKnownCaveatCode, a1 as requireFullCaveats } from './client-DOq3Kr0S.mjs';
|
|
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-DPJgPNgs.mjs';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
6
|
* What to do INSTEAD — the sentence `transient` cannot say.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
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-
|
|
2
|
-
export { b as AUTHOR_CLASSES, c as Activity, d as AuthorClass, C as CAVEAT_CODES, e as CAVEAT_SCOPE_FREE, f as CAVEAT_SCOPE_METERED, g as Caveat, h as CaveatCode, i as CaveatsNotComputedError, j as Concentration, k as Confidence, l as DescribeClient, m as DescribeClientConfig, n as DescribeError, o as DescribeFailure, p as DescribeHTTPError, q as DescribeMalformedHash, r as DescribeNotFound, s as DescribePartnerRejected, t as DescribePartnerUnsigned, u as DescribePaymentRefused, v as DescribePaymentRequired, w as DescribeTimeout, x as DescribeUnparseable, y as DescribeUnreachable, F as Facet, z as Freshness, B as FreshnessScope, H as HealthChain, K as KnownAuthorClass, E as KnownCaveatCode, N as Network, O as Ownership, G as PartnerSigner, J as PaymentAttempt, R as Rating, S as Sealed, M as SelfRated, Q as Snapshot, T as Timestamp, U as WalletChainRow, X as X402Challenge, V as X402Payer, Y as failOpenCovers, Z as failedAfterPaying, _ as hasCaveat, $ as isKnownAuthorClass, a0 as isKnownCaveatCode, a1 as requireFullCaveats } from './client-
|
|
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-
|
|
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-DOq3Kr0S.js';
|
|
2
|
+
export { b as AUTHOR_CLASSES, c as Activity, d as AuthorClass, C as CAVEAT_CODES, e as CAVEAT_SCOPE_FREE, f as CAVEAT_SCOPE_METERED, g as Caveat, h as CaveatCode, i as CaveatsNotComputedError, j as Concentration, k as Confidence, l as DescribeClient, m as DescribeClientConfig, n as DescribeError, o as DescribeFailure, p as DescribeHTTPError, q as DescribeMalformedHash, r as DescribeNotFound, s as DescribePartnerRejected, t as DescribePartnerUnsigned, u as DescribePaymentRefused, v as DescribePaymentRequired, w as DescribeTimeout, x as DescribeUnparseable, y as DescribeUnreachable, F as Facet, z as Freshness, B as FreshnessScope, H as HealthChain, K as KnownAuthorClass, E as KnownCaveatCode, N as Network, O as Ownership, G as PartnerSigner, J as PaymentAttempt, R as Rating, S as Sealed, M as SelfRated, Q as Snapshot, T as Timestamp, U as WalletChainRow, X as X402Challenge, V as X402Payer, Y as failOpenCovers, Z as failedAfterPaying, _ as hasCaveat, $ as isKnownAuthorClass, a0 as isKnownCaveatCode, a1 as requireFullCaveats } from './client-DOq3Kr0S.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-DPJgPNgs.js';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
6
|
* What to do INSTEAD — the sentence `transient` cannot say.
|
package/dist/index.js
CHANGED
|
@@ -8,7 +8,7 @@ var DEFAULT_JITTER_MS = 400;
|
|
|
8
8
|
var TREASURY_EVM = "0xe4dc963c56979E0260fc146b87eE24F18220e545";
|
|
9
9
|
var PARTNER_CHAIN_ID = 8453;
|
|
10
10
|
var PARTNER_KEY_ENV = "DESCRIBE_PARTNER_PRIVATE_KEY";
|
|
11
|
-
var SDK_VERSION = "0.
|
|
11
|
+
var SDK_VERSION = "0.5.0";
|
|
12
12
|
var SDK_NAME = "uvd-describe-sdk-ts";
|
|
13
13
|
function userAgent(product) {
|
|
14
14
|
const base = `${SDK_NAME}/${SDK_VERSION}`;
|