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/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
+ }