uvd-describe-sdk 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +612 -0
- package/dist/client-s3KrgrCt.d.mts +1537 -0
- package/dist/client-s3KrgrCt.d.ts +1537 -0
- package/dist/config-Y2VK_neB.d.mts +169 -0
- package/dist/config-Y2VK_neB.d.ts +169 -0
- package/dist/index.d.mts +488 -0
- package/dist/index.d.ts +488 -0
- package/dist/index.js +1082 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +1038 -0
- package/dist/index.mjs.map +1 -0
- package/dist/partner/index.d.mts +194 -0
- package/dist/partner/index.d.ts +194 -0
- package/dist/partner/index.js +77 -0
- package/dist/partner/index.js.map +1 -0
- package/dist/partner/index.mjs +71 -0
- package/dist/partner/index.mjs.map +1 -0
- package/dist/x402/index.d.mts +91 -0
- package/dist/x402/index.d.ts +91 -0
- package/dist/x402/index.js +29 -0
- package/dist/x402/index.js.map +1 -0
- package/dist/x402/index.mjs +26 -0
- package/dist/x402/index.mjs.map +1 -0
- package/package.json +97 -0
- package/src/caveats.ts +124 -0
- package/src/client.ts +953 -0
- package/src/config.ts +181 -0
- package/src/errors.ts +596 -0
- package/src/format.ts +67 -0
- package/src/hashes.ts +229 -0
- package/src/index.ts +192 -0
- package/src/jitter.ts +112 -0
- package/src/parse.ts +388 -0
- package/src/partner/index.ts +295 -0
- package/src/raters.ts +118 -0
- package/src/recovery.ts +254 -0
- package/src/types.ts +457 -0
- package/src/x402/index.ts +123 -0
package/src/config.ts
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The only place this package defines a calibrable value.
|
|
3
|
+
*
|
|
4
|
+
* House rule (decisión de Saul, 2026-08-26, born from a measured case in
|
|
5
|
+
* describe.net: one threshold written with TWO DIFFERENT VALUES across four
|
|
6
|
+
* surfaces, and the one charged was not the one the site promised). Nothing
|
|
7
|
+
* else in this package re-types these numbers — modules import them.
|
|
8
|
+
*
|
|
9
|
+
* What does NOT live here, by the same rule: anything that moves a score or a
|
|
10
|
+
* price. This SDK computes neither, so the list is short: `POLICY_VERSION` and
|
|
11
|
+
* the prices are the server's and travel in its responses. We never type a
|
|
12
|
+
* price. See `errors.ts` for what we do with a 402 challenge instead.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/** Where the index answers. Overridable per client for a staging deploy. */
|
|
16
|
+
export const DEFAULT_BASE_URL = 'https://api.describe.net';
|
|
17
|
+
|
|
18
|
+
/** Where a human reads the same wallet. Never fetched — only linked. */
|
|
19
|
+
export const DEFAULT_SITE_URL = 'https://describe.net';
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* 30 s, and the number is not taste — it is the one number of the three live
|
|
23
|
+
* consumers that came with its measurement written down (EM `client.py:19-23`,
|
|
24
|
+
* INC-2026-08-19):
|
|
25
|
+
*
|
|
26
|
+
* * the provider's Lambda cold start was measured at **15,2 s**, so anything
|
|
27
|
+
* under it turns a cold index into a fake outage. An 8 s timeout already
|
|
28
|
+
* broke a real integration once.
|
|
29
|
+
* * its API Gateway integration ceiling is **29 s**, so waiting past 30 buys
|
|
30
|
+
* nothing the gateway will ever deliver.
|
|
31
|
+
* * it is deliberately DISTINCT from the Facilitator's 45 s so two clocks can
|
|
32
|
+
* never expire in the same second and produce an error nobody can attribute.
|
|
33
|
+
*
|
|
34
|
+
* Measured across the ecosystem on 2026-08-30: EM 30 s, MeshRelay 30 000 ms,
|
|
35
|
+
* KarmaKadabra 25 s. Two of three already sit here.
|
|
36
|
+
*/
|
|
37
|
+
export const DEFAULT_TIMEOUT_MS = 30_000;
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* 400 ms, **on by default**, and the default is the decision — so here is the
|
|
41
|
+
* argument, because it is the one thing about this package that spends the
|
|
42
|
+
* caller's latency without being asked.
|
|
43
|
+
*
|
|
44
|
+
* The number is not ours: it is what **KarmaKadabra** sleeps before every read
|
|
45
|
+
* (`random.uniform(0, 0.4)`), contributed on 2026-08-30 with the measurement
|
|
46
|
+
* that produced it — *"27 agentes despiertan al MISMO tiempo por EventBridge y
|
|
47
|
+
* pegan simultáneo contra su límite de rps COMPARTIDO con los otros
|
|
48
|
+
* consumidores. Sin jitter, un enjambre es un DDoS educado."* They run the
|
|
49
|
+
* largest fleet against this index, so their calibration beats our taste.
|
|
50
|
+
*
|
|
51
|
+
* ## Why ON, when a library that sleeps unasked is a surprise
|
|
52
|
+
*
|
|
53
|
+
* The surprise is real and it is the honest objection. Three things outweigh it:
|
|
54
|
+
*
|
|
55
|
+
* 1. **The cost of the mistake does not land on whoever makes it.** The rate
|
|
56
|
+
* limit is shared with no per-partner bucket (see `userAgent` below), so an
|
|
57
|
+
* unjittered swarm is paid for by the OTHER consumer, who gets the 429 and
|
|
58
|
+
* has no lever to fix it. When the cost of a default falls on someone who
|
|
59
|
+
* cannot change it, the default has to be the safe one.
|
|
60
|
+
* 2. **Opt-out is discoverable; opt-in is not.** `jitterMs: 0` is one field
|
|
61
|
+
* away and typed. The other direction cannot be found by reading your own
|
|
62
|
+
* code: you learn you needed jitter from someone else's incident, and by
|
|
63
|
+
* then you have already spent their budget. KarmaKadabra's own framing —
|
|
64
|
+
* whoever writes a single script never finds out the problem exists until
|
|
65
|
+
* they have a fleet.
|
|
66
|
+
* 3. **It is bounded and small against this package's own numbers.** At most
|
|
67
|
+
* 400 ms, 200 ms on average, against a 30 000 ms timeout and a provider
|
|
68
|
+
* cold start measured at 15,2 s. And it is the same shape of default this
|
|
69
|
+
* client already ships: `failOpen: true` also changes behaviour without
|
|
70
|
+
* being asked, for the same reason — the safe thing, loudly documented,
|
|
71
|
+
* with one field to turn it off.
|
|
72
|
+
*
|
|
73
|
+
* ## What is NOT written here, on purpose
|
|
74
|
+
*
|
|
75
|
+
* The rate limit itself. KarmaKadabra's own note cited 20 rps, which was the
|
|
76
|
+
* documentation's figure and is now stale (it is 50 sustained / burst 40 since
|
|
77
|
+
* 2026-08-28). A number that has already gone stale once in one hop between two
|
|
78
|
+
* teams does not belong in a constant: **the `RateLimit-Policy` response header
|
|
79
|
+
* is the authority**, and this value is calibrated against a fleet size, not
|
|
80
|
+
* against a ceiling. See the correction in `userAgent`.
|
|
81
|
+
*/
|
|
82
|
+
export const DEFAULT_JITTER_MS = 400;
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The treasury this SDK will pay, and NOTHING else.
|
|
86
|
+
*
|
|
87
|
+
* Read live from the 402 challenge of `GET /reputation/wallet/{w}` on
|
|
88
|
+
* 2026-08-30 (`recipient`, and `payTo` on all six `accepts[]` entries — base,
|
|
89
|
+
* avalanche, arbitrum, optimism, polygon, celo — identical on every one).
|
|
90
|
+
*
|
|
91
|
+
* Pinning it is the point: an x402 challenge is fetched over the network and
|
|
92
|
+
* names its own recipient, so a client that pays whatever `payTo` arrives will
|
|
93
|
+
* happily pay an attacker who can answer as the API. A challenge whose `payTo`
|
|
94
|
+
* is not this address is `DO_NOT_PAY` — never a retry, never a warning that a
|
|
95
|
+
* caller can ignore.
|
|
96
|
+
*
|
|
97
|
+
* 🔴 THE FAILURE MODE OF PINNING, written down because it will happen: if
|
|
98
|
+
* describe.net rotates its treasury, every published version of this SDK stops
|
|
99
|
+
* paying until it is republished. That is the SAFE direction of the failure
|
|
100
|
+
* (refusing to pay a stranger beats paying one), and the escape hatch is
|
|
101
|
+
* `expectedPayTo` in the client config — a caller who has verified the new
|
|
102
|
+
* address out of band can move without waiting for us.
|
|
103
|
+
*/
|
|
104
|
+
export const TREASURY_EVM = '0xe4dc963c56979E0260fc146b87eE24F18220e545';
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* The chain id that goes in the ERC-8128 keyid of a partner signature.
|
|
108
|
+
*
|
|
109
|
+
* 8453 (Base). Not a preference — it is what the gate accepts:
|
|
110
|
+
* `describe-net/describenet/partner.py:90` sets `CHAIN_ID = 8453` and passes it
|
|
111
|
+
* as the ONLY member of `allowed_chain_ids`, with its own comment explaining
|
|
112
|
+
* that `None` (accept any chain) would be "innecesariamente laxo para una
|
|
113
|
+
* allowlist de tres servicios propios". Read 2026-08-30.
|
|
114
|
+
*
|
|
115
|
+
* The payment SDK's own default happens to be 8453 too, and this constant
|
|
116
|
+
* deliberately does not lean on that: this value belongs to describe.net's
|
|
117
|
+
* policy, not to the signer's convenience, and the day one moves the other must
|
|
118
|
+
* not follow by accident. Measured failure mode of getting it wrong: the gate
|
|
119
|
+
* answers `chain_not_allowed` and the route charges — loud, since partner mode
|
|
120
|
+
* throws `DescribePartnerRejected` instead of paying.
|
|
121
|
+
*/
|
|
122
|
+
export const PARTNER_CHAIN_ID = 8453;
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* The environment variable `partnerFromEnv()` reads the signing key from.
|
|
126
|
+
*
|
|
127
|
+
* A variable name is not a secret; the value it holds is. Naming it here means
|
|
128
|
+
* a consumer can grep for it, a deploy manifest can set it, and nobody has to
|
|
129
|
+
* guess — while `partnerFromEnv()` staying the ONLY reader means the key has
|
|
130
|
+
* exactly one path into this package.
|
|
131
|
+
*/
|
|
132
|
+
export const PARTNER_KEY_ENV = 'DESCRIBE_PARTNER_PRIVATE_KEY';
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* The package version, for the `User-Agent`.
|
|
136
|
+
*
|
|
137
|
+
* MeshRelay reads its version from `package.json` at runtime because "a
|
|
138
|
+
* User-Agent that lies about the version is worse than none"
|
|
139
|
+
* (`describenet.js:39`). It can afford the `readFileSync`: it is a server, not
|
|
140
|
+
* a bundled library. We cannot — a library that reads its own manifest at
|
|
141
|
+
* runtime either bundles `package.json` into the artifact or breaks in a
|
|
142
|
+
* browser, and this package has to run in a browser.
|
|
143
|
+
*
|
|
144
|
+
* So the constant is typed here and `config.test.ts` asserts it equals
|
|
145
|
+
* `package.json`'s `version`. Same guarantee (the UA cannot lie), paid at test
|
|
146
|
+
* time instead of at runtime. Bumping the version without the constant is a
|
|
147
|
+
* red test, not a silent lie in someone's access log.
|
|
148
|
+
*/
|
|
149
|
+
export const SDK_VERSION = '0.1.0';
|
|
150
|
+
|
|
151
|
+
/** `uvd-describe-sdk-ts/0.1.0`, plus `(+<product>)` when the caller names itself. */
|
|
152
|
+
export const SDK_NAME = 'uvd-describe-sdk-ts';
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Build the `User-Agent`.
|
|
156
|
+
*
|
|
157
|
+
* The provider's rate limit is **shared by every consumer with no per-partner
|
|
158
|
+
* bucket**, so identifying ourselves is the only thing that makes our share of
|
|
159
|
+
* it attributable at all. That is why the UA is on by default and `product` is
|
|
160
|
+
* the one field a caller should bother to fill.
|
|
161
|
+
*
|
|
162
|
+
* ⚠️ CORRECTION 2026-08-30, left written rather than swapped: this comment
|
|
163
|
+
* first said "20 rps", copied from `meshrelay/describenet.js:19-20`. The live
|
|
164
|
+
* OpenAPI says **50 requests/second sustained, bursts up to 40**, at the API
|
|
165
|
+
* Gateway edge, and it also says where the truth lives: *"Every response
|
|
166
|
+
* carries the policy as a header, `RateLimit-Policy: 50;w=1;burst=40` … and
|
|
167
|
+
* **that header is the authority**"*. So neither number belongs in this file —
|
|
168
|
+
* read the header. Cached free routes (`/health`, `/pricing`, `/leaderboard`,
|
|
169
|
+
* `/stats/*`) are served by CloudFront and do not consume the budget on a hit.
|
|
170
|
+
* The 20 was probably right when MeshRelay wrote it; a dated figure does not
|
|
171
|
+
* stop being stale, it only stops being a lie.
|
|
172
|
+
*
|
|
173
|
+
* ⚠️ It is attribution, not authentication. describe.net has no accounts and
|
|
174
|
+
* no API keys — "el pago es la autenticación" — so anyone can send any UA.
|
|
175
|
+
* Never treat this string as identity, on either side.
|
|
176
|
+
*/
|
|
177
|
+
export function userAgent(product?: string): string {
|
|
178
|
+
const base = `${SDK_NAME}/${SDK_VERSION}`;
|
|
179
|
+
const trimmed = (product ?? '').trim();
|
|
180
|
+
return trimmed ? `${base} (+${trimmed})` : base;
|
|
181
|
+
}
|