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