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 @@
1
+ {"version":3,"sources":["../../src/config.ts","../../src/partner/index.ts"],"names":[],"mappings":";;;;;AAyHO,IAAM,gBAAA,GAAmB;AAUzB,IAAM,eAAA,GAAkB;;;ACnC/B,SAAS,aAAa,OAAA,EAAyC;AAC7D,EAAA,MAAM,MAA8B,EAAC;AACrC,EAAA,KAAA,MAAW,CAAC,IAAA,EAAM,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,OAAO,CAAA,EAAG;AACnD,IAAA,IAAI,OAAO,KAAA,KAAU,QAAA,EAAU,GAAA,CAAI,IAAI,CAAA,GAAI,KAAA;AAAA,EAC7C;AACA,EAAA,OAAO,GAAA;AACT;AAGA,SAAS,SAAA,GAAoB;AAC3B,EAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,EAAE,CAAA;AAG/B,EAAA,UAAA,CAAW,MAAA,CAAO,gBAAgB,KAAK,CAAA;AACvC,EAAA,OAAO,KAAA,CAAM,IAAA,CAAK,KAAA,EAAO,CAAC,MAAM,CAAA,CAAE,QAAA,CAAS,EAAE,CAAA,CAAE,SAAS,CAAA,EAAG,GAAG,CAAC,CAAA,CAAE,KAAK,EAAE,CAAA;AAC1E;AAuCO,SAAS,kBACd,MAAA,EAMe;AACf,EAAA,MAAM,EAAE,OAAA,EAAS,WAAA,EAAa,OAAA,GAAU,kBAAiB,GAAI,MAAA;AAC7D,EAAA,OAAO;AAAA,IACL,OAAA;AAAA,IACA,MAAM,IAAA,CAAK,EAAE,MAAA,EAAQ,KAAI,EAAG;AAC1B,MAAA,OAAO,YAAA;AAAA,QACL,MAAM,qBAAA,CAAsB;AAAA,UAC1B,MAAA;AAAA,UACA,GAAA;AAAA,UACA,OAAA;AAAA,UACA,OAAA;AAAA,UACA,OAAO,SAAA,EAAU;AAAA,UACjB;AAAA,SACD;AAAA,OACH;AAAA,IACF;AAAA,GACF;AACF;AAsDO,SAAS,cAAA,CACd,OAAA,GAKI,EAAC,EACU;AACf,EAAA,MAAM,EAAE,OAAA,GAAU,gBAAA,EAAkB,MAAA,GAAS,iBAAgB,GAAI,OAAA;AACjE,EAAA,MAAM,GAAA,GAAM,OAAA,CAAQ,GAAA,IAAQ,UAAA,CAA0E,OAAA,EAAS,GAAA;AAE/G,EAAA,MAAM,GAAA,GAAM,MAAM,MAAM,CAAA;AACxB,EAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,IAAY,GAAA,CAAI,IAAA,OAAW,EAAA,EAAI;AAChD,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,mBAAmB,MAAM,CAAA,2OAAA;AAAA,KAI3B;AAAA,EACF;AAIA,EAAA,MAAM,GAAA,GAAM,IAAI,IAAA,EAAK;AACrB,EAAA,IAAI,CAAC,wBAAA,CAAyB,IAAA,CAAK,GAAG,CAAA,EAAG;AAGvC,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,gBAAA,EAAmB,MAAM,CAAA,uCAAA,EACf,GAAA,CAAI,MAAM,CAAA,wGAAA;AAAA,KAEtB;AAAA,EACF;AAMA,EAAA,OAAO;AAAA,IACL,MAAM,IAAA,CAAK,EAAE,MAAA,EAAQ,KAAI,EAAG;AAC1B,MAAA,OAAO,YAAA;AAAA,QACL,MAAM,WAAA,CAAY,EAAE,MAAA,EAAQ,GAAA,EAAK,OAAA,EAAS,KAAA,EAAO,SAAA,EAAU,EAAG,UAAA,EAAY,GAAA,EAAK;AAAA,OACjF;AAAA,IACF;AAAA,GACF;AACF;AAcO,SAAS,gBAAA,GAA2B;AACzC,EAAA,MAAM,GAAA,GAAM,yBAAyB,MAAA,CAAO,WAAA;AAC5C,EAAA,IAAI,CAAC,GAAA,EAAK,MAAM,IAAI,MAAM,wDAAwD,CAAA;AAClF,EAAA,OAAO,GAAA;AACT","file":"index.mjs","sourcesContent":["/**\n * The only place this package defines a calibrable value.\n *\n * House rule (decisión de Saul, 2026-08-26, born from a measured case in\n * describe.net: one threshold written with TWO DIFFERENT VALUES across four\n * surfaces, and the one charged was not the one the site promised). Nothing\n * else in this package re-types these numbers — modules import them.\n *\n * What does NOT live here, by the same rule: anything that moves a score or a\n * price. This SDK computes neither, so the list is short: `POLICY_VERSION` and\n * the prices are the server's and travel in its responses. We never type a\n * price. See `errors.ts` for what we do with a 402 challenge instead.\n */\n\n/** Where the index answers. Overridable per client for a staging deploy. */\nexport const DEFAULT_BASE_URL = 'https://api.describe.net';\n\n/** Where a human reads the same wallet. Never fetched — only linked. */\nexport const DEFAULT_SITE_URL = 'https://describe.net';\n\n/**\n * 30 s, and the number is not taste — it is the one number of the three live\n * consumers that came with its measurement written down (EM `client.py:19-23`,\n * INC-2026-08-19):\n *\n * * the provider's Lambda cold start was measured at **15,2 s**, so anything\n * under it turns a cold index into a fake outage. An 8 s timeout already\n * broke a real integration once.\n * * its API Gateway integration ceiling is **29 s**, so waiting past 30 buys\n * nothing the gateway will ever deliver.\n * * it is deliberately DISTINCT from the Facilitator's 45 s so two clocks can\n * never expire in the same second and produce an error nobody can attribute.\n *\n * Measured across the ecosystem on 2026-08-30: EM 30 s, MeshRelay 30 000 ms,\n * KarmaKadabra 25 s. Two of three already sit here.\n */\nexport const DEFAULT_TIMEOUT_MS = 30_000;\n\n/**\n * 400 ms, **on by default**, and the default is the decision — so here is the\n * argument, because it is the one thing about this package that spends the\n * caller's latency without being asked.\n *\n * The number is not ours: it is what **KarmaKadabra** sleeps before every read\n * (`random.uniform(0, 0.4)`), contributed on 2026-08-30 with the measurement\n * that produced it — *\"27 agentes despiertan al MISMO tiempo por EventBridge y\n * pegan simultáneo contra su límite de rps COMPARTIDO con los otros\n * consumidores. Sin jitter, un enjambre es un DDoS educado.\"* They run the\n * largest fleet against this index, so their calibration beats our taste.\n *\n * ## Why ON, when a library that sleeps unasked is a surprise\n *\n * The surprise is real and it is the honest objection. Three things outweigh it:\n *\n * 1. **The cost of the mistake does not land on whoever makes it.** The rate\n * limit is shared with no per-partner bucket (see `userAgent` below), so an\n * unjittered swarm is paid for by the OTHER consumer, who gets the 429 and\n * has no lever to fix it. When the cost of a default falls on someone who\n * cannot change it, the default has to be the safe one.\n * 2. **Opt-out is discoverable; opt-in is not.** `jitterMs: 0` is one field\n * away and typed. The other direction cannot be found by reading your own\n * code: you learn you needed jitter from someone else's incident, and by\n * then you have already spent their budget. KarmaKadabra's own framing —\n * whoever writes a single script never finds out the problem exists until\n * they have a fleet.\n * 3. **It is bounded and small against this package's own numbers.** At most\n * 400 ms, 200 ms on average, against a 30 000 ms timeout and a provider\n * cold start measured at 15,2 s. And it is the same shape of default this\n * client already ships: `failOpen: true` also changes behaviour without\n * being asked, for the same reason — the safe thing, loudly documented,\n * with one field to turn it off.\n *\n * ## What is NOT written here, on purpose\n *\n * The rate limit itself. KarmaKadabra's own note cited 20 rps, which was the\n * documentation's figure and is now stale (it is 50 sustained / burst 40 since\n * 2026-08-28). A number that has already gone stale once in one hop between two\n * teams does not belong in a constant: **the `RateLimit-Policy` response header\n * is the authority**, and this value is calibrated against a fleet size, not\n * against a ceiling. See the correction in `userAgent`.\n */\nexport const DEFAULT_JITTER_MS = 400;\n\n/**\n * The treasury this SDK will pay, and NOTHING else.\n *\n * Read live from the 402 challenge of `GET /reputation/wallet/{w}` on\n * 2026-08-30 (`recipient`, and `payTo` on all six `accepts[]` entries — base,\n * avalanche, arbitrum, optimism, polygon, celo — identical on every one).\n *\n * Pinning it is the point: an x402 challenge is fetched over the network and\n * names its own recipient, so a client that pays whatever `payTo` arrives will\n * happily pay an attacker who can answer as the API. A challenge whose `payTo`\n * is not this address is `DO_NOT_PAY` — never a retry, never a warning that a\n * caller can ignore.\n *\n * 🔴 THE FAILURE MODE OF PINNING, written down because it will happen: if\n * describe.net rotates its treasury, every published version of this SDK stops\n * paying until it is republished. That is the SAFE direction of the failure\n * (refusing to pay a stranger beats paying one), and the escape hatch is\n * `expectedPayTo` in the client config — a caller who has verified the new\n * address out of band can move without waiting for us.\n */\nexport const TREASURY_EVM = '0xe4dc963c56979E0260fc146b87eE24F18220e545';\n\n/**\n * The chain id that goes in the ERC-8128 keyid of a partner signature.\n *\n * 8453 (Base). Not a preference — it is what the gate accepts:\n * `describe-net/describenet/partner.py:90` sets `CHAIN_ID = 8453` and passes it\n * as the ONLY member of `allowed_chain_ids`, with its own comment explaining\n * that `None` (accept any chain) would be \"innecesariamente laxo para una\n * allowlist de tres servicios propios\". Read 2026-08-30.\n *\n * The payment SDK's own default happens to be 8453 too, and this constant\n * deliberately does not lean on that: this value belongs to describe.net's\n * policy, not to the signer's convenience, and the day one moves the other must\n * not follow by accident. Measured failure mode of getting it wrong: the gate\n * answers `chain_not_allowed` and the route charges — loud, since partner mode\n * throws `DescribePartnerRejected` instead of paying.\n */\nexport const PARTNER_CHAIN_ID = 8453;\n\n/**\n * The environment variable `partnerFromEnv()` reads the signing key from.\n *\n * A variable name is not a secret; the value it holds is. Naming it here means\n * a consumer can grep for it, a deploy manifest can set it, and nobody has to\n * guess — while `partnerFromEnv()` staying the ONLY reader means the key has\n * exactly one path into this package.\n */\nexport const PARTNER_KEY_ENV = 'DESCRIBE_PARTNER_PRIVATE_KEY';\n\n/**\n * The package version, for the `User-Agent`.\n *\n * MeshRelay reads its version from `package.json` at runtime because \"a\n * User-Agent that lies about the version is worse than none\"\n * (`describenet.js:39`). It can afford the `readFileSync`: it is a server, not\n * a bundled library. We cannot — a library that reads its own manifest at\n * runtime either bundles `package.json` into the artifact or breaks in a\n * browser, and this package has to run in a browser.\n *\n * So the constant is typed here and `config.test.ts` asserts it equals\n * `package.json`'s `version`. Same guarantee (the UA cannot lie), paid at test\n * time instead of at runtime. Bumping the version without the constant is a\n * red test, not a silent lie in someone's access log.\n */\nexport const SDK_VERSION = '0.1.0';\n\n/** `uvd-describe-sdk-ts/0.1.0`, plus `(+<product>)` when the caller names itself. */\nexport const SDK_NAME = 'uvd-describe-sdk-ts';\n\n/**\n * Build the `User-Agent`.\n *\n * The provider's rate limit is **shared by every consumer with no per-partner\n * bucket**, so identifying ourselves is the only thing that makes our share of\n * it attributable at all. That is why the UA is on by default and `product` is\n * the one field a caller should bother to fill.\n *\n * ⚠️ CORRECTION 2026-08-30, left written rather than swapped: this comment\n * first said \"20 rps\", copied from `meshrelay/describenet.js:19-20`. The live\n * OpenAPI says **50 requests/second sustained, bursts up to 40**, at the API\n * Gateway edge, and it also says where the truth lives: *\"Every response\n * carries the policy as a header, `RateLimit-Policy: 50;w=1;burst=40` … and\n * **that header is the authority**\"*. So neither number belongs in this file —\n * read the header. Cached free routes (`/health`, `/pricing`, `/leaderboard`,\n * `/stats/*`) are served by CloudFront and do not consume the budget on a hit.\n * The 20 was probably right when MeshRelay wrote it; a dated figure does not\n * stop being stale, it only stops being a lie.\n *\n * ⚠️ It is attribution, not authentication. describe.net has no accounts and\n * no API keys — \"el pago es la autenticación\" — so anyone can send any UA.\n * Never treat this string as identity, on either side.\n */\nexport function userAgent(product?: string): string {\n const base = `${SDK_NAME}/${SDK_VERSION}`;\n const trimmed = (product ?? '').trim();\n return trimmed ? `${base} (+${trimmed})` : base;\n}\n","/**\n * The partner rail — how a product of the house reads describe.net for free.\n *\n * ## What this is, in one paragraph\n *\n * describe.net has no accounts and no API keys, on purpose: *\"el pago es la\n * autenticación\"*. So when Execution Market, MeshRelay and KarmaKadabra\n * deprecated their local reputation maths and became read-dependencies of the\n * index (2026-08-28), the question \"does a service of the house pay like a\n * stranger?\" could not be answered with a token. It was answered with an\n * ALLOWLIST OF PUBLIC ADDRESSES plus a per-request ERC-8128 signature\n * (`describe-net/describenet/partner.py`). The partner holds a dedicated wallet\n * with no funds whose only job is to sign; describe.net holds a list of\n * addresses. **The service custodies no secret of ours** — a breach there leaks\n * a list of things that were already public — and that property, not\n * convenience, is why this is a signature and not the `X-API-Key` everyone\n * reaches for first.\n *\n * This module is the client half. It is the only file in this package with a\n * RUNTIME import of `uvd-x402-sdk`, which is why it lives behind the\n * `uvd-describe-sdk/partner` subpath: the main entry and the `x402` entry keep\n * their zero-runtime-imports property, and a consumer who never signs installs\n * nothing.\n *\n * ## Upstream-first: the primitive already existed, MEASURED before writing\n *\n * `uvd-x402-sdk` 2.75.0 (installed, checked 2026-08-30) exports the whole\n * ERC-8128 signer from `uvd-x402-sdk/erc8128` — `signRequest`,\n * `signRequestWithSigner`, `signRequestWithWallet`, plus the pure base builder\n * and the verifier. So NOTHING is signed in this repo: this file picks a chain\n * id and a nonce and forwards. Not one byte of RFC 9421 canonicalisation is\n * reimplemented here, and if any of it ever needs to change, it changes THERE.\n *\n * Verified end to end, offline, on 2026-08-30: headers produced by\n * `signRequestWithSigner` at chain 8453 verify under the EXACT policy\n * `partner.py` builds (authority `api.describe.net`, `allowed_chain_ids=[8453]`,\n * `max_validity_sec=300`, `clock_skew_future_sec=30`), recovering the signer's\n * address. `partner.test.ts` is that probe, kept as a test.\n *\n * ## The nonce: minted here, and here is the argument\n *\n * The payment SDK requires a nonce and refuses to invent one — *\"a local nonce\n * authenticates against a first-use-wins store and is rejected by an\n * issuer-bound one, which turns a server blip into an auth mystery\"*\n * (`erc8128/signer.ts:15-17`). That reasoning is about servers that HAVE a nonce\n * store. describe.net has none: `PartnerGate` builds its `VerifyPolicy` with no\n * `nonce` field at all (`partner.py:216-223`), and the verifier skips every\n * nonce rule when `policy.nonce is None` — no presence check\n * (`verifier.py:458-462`), no consumption (`verifier.py:304`). Read in the\n * installed PyPI `uvd-x402-sdk` 0.70.0 on 2026-08-30.\n *\n * So there is no store to be unknown to, and a locally minted random nonce is\n * strictly better than the alternative the policy would also accept (none at\n * all): it makes each signature unique, so two identical GETs in the same second\n * do not produce byte-identical headers. This is the caller owning the\n * consequence, which is exactly what `onNonceUnavailable` exists to express in\n * the payment SDK — stated here rather than hidden.\n *\n * 🔴 If describe.net ever adds a nonce store, this line becomes wrong and the\n * failure is loud, not silent: every partner request starts answering 402 with\n * `nonce_unknown` and `DescribePartnerRejected` says so. That is the direction\n * this failure should point.\n *\n * ## What is signed, and the consequence of a custom `baseUrl`\n *\n * The signature covers `@method`, `@authority` and `@path` (plus `@query` when\n * there is one), and `@authority` comes from the URL being requested. The gate\n * pins `api.describe.net` and NEVER derives it from a header (`partner.py:73-84`\n * — deriving an authority from client-controlled input is how a verifier was\n * once made to rebuild a base over an attacker's domain). So a client pointed at\n * any other origin — a staging host, a proxy, the raw execute-api host behind\n * CloudFront — signs an authority the gate does not accept and is charged. That\n * is deliberate on both sides, and it fails LOUDLY here as\n * `DescribePartnerRejected` rather than quietly as a bill.\n */\n\nimport {\n CONFORMANCE_VECTORS_F3_1,\n signRequest,\n signRequestWithSigner,\n} from 'uvd-x402-sdk/erc8128';\n\nimport type { PartnerSigner } from '../client';\nimport { PARTNER_CHAIN_ID, PARTNER_KEY_ENV } from '../config';\n\n/**\n * The signer's typed header object as a plain `Record<string, string>`.\n *\n * Not cosmetic: `Erc8128Headers` declares `'Content-Digest'?: string`, and an\n * interface with an optional member is not assignable to `Record<string,\n * string>` — the dts build says so, loudly (TS2322 at the return, TS2345 at the\n * parameter, which is why the parameter is `object` and not a `Record` of its\n * own). Dropping the undefined entries here is the honest conversion, and it\n * means the client never merges a header whose value is `undefined` into a\n * `fetch` call, which is how a literal `\"undefined\"` ends up on a wire.\n */\nfunction plainHeaders(headers: object): Record<string, string> {\n const out: Record<string, string> = {};\n for (const [name, value] of Object.entries(headers)) {\n if (typeof value === 'string') out[name] = value;\n }\n return out;\n}\n\n/** A 128-bit hex nonce. See the module header for why this is minted locally. */\nfunction mintNonce(): string {\n const bytes = new Uint8Array(16);\n // `globalThis.crypto` is standard in Node >= 18 and in every browser, which\n // is the same floor as this package's `engines`. No import, no polyfill.\n globalThis.crypto.getRandomValues(bytes);\n return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');\n}\n\n/** What every factory here accepts. Both fields have defaults that are right. */\nexport interface PartnerOptions {\n /**\n * The keyid's chain id. Defaults to `PARTNER_CHAIN_ID` (8453, Base), which is\n * what the gate pins. Override only if describe.net's `CHAIN_ID` moves.\n */\n chainId?: number;\n}\n\n/**\n * The rail, from a signer you already have. **This is the preferred form.**\n *\n * It takes an OBJECT THAT SIGNS, never a key: a browser wallet, an ethers\n * `Wallet` built somewhere else, an OWS vault, a KMS client, a queue that asks a\n * human. The key material never enters this package, never enters\n * `uvd-x402-sdk`'s signer, and cannot end up in a stack trace it produces.\n *\n * ```ts\n * import { DescribeClient } from 'uvd-describe-sdk';\n * import { partnerFromSigner } from 'uvd-describe-sdk/partner';\n *\n * // `wallet` is yours — this package never learns how it holds its key.\n * const describe = new DescribeClient({\n * product: 'meshrelay',\n * partner: partnerFromSigner({\n * address: await wallet.getAddress(),\n * signMessage: (base) => wallet.signMessage(base),\n * }),\n * });\n *\n * // Metered route, no payer, no USDC: the free rail carries it.\n * const detail = await describe.walletBreakdown('0x97cd…0996');\n * ```\n *\n * `signMessage` is an EIP-191 `personal_sign` over the string it is handed and\n * must return `0x` + 130 hex. It is the ONE thing this rail cannot do for you.\n */\nexport function partnerFromSigner(\n signer: {\n /** The signing wallet's address. Public by design — the allowlist is public. */\n address: string;\n /** EIP-191 personal_sign over the signature base. */\n signMessage(message: string): string | Promise<string>;\n } & PartnerOptions,\n): PartnerSigner {\n const { address, signMessage, chainId = PARTNER_CHAIN_ID } = signer;\n return {\n address,\n async sign({ method, url }) {\n return plainHeaders(\n await signRequestWithSigner({\n method,\n url,\n address,\n chainId,\n nonce: mintNonce(),\n signMessage,\n }),\n );\n },\n };\n}\n\n/**\n * The rail, from a private key **the environment holds**.\n *\n * ## Why this reads the variable itself instead of taking a string\n *\n * Because a function that takes a key as an argument is a function somebody\n * calls with a literal. Two DAO wallets were drained in minutes by bots\n * scanning public repositories for `0x` + 64 hex (INC-2026-03-30), and \"it was\n * only for a test\" is how both got there. This signature makes the safe path\n * the only path: the key can come from `process.env` and from nowhere else, so\n * there is no argument to paste one into. If your key lives somewhere better —\n * Secrets Manager, a vault, a hardware signer — fetch it there and use\n * {@link partnerFromSigner}, which never sees a key at all.\n *\n * ```ts\n * // DESCRIBE_PARTNER_PRIVATE_KEY is set in the environment. Never in code.\n * const describe = new DescribeClient({\n * product: 'karmakadabra',\n * partner: partnerFromEnv(),\n * });\n * ```\n *\n * Throws immediately — at wiring time, not at the first request — when the\n * variable is unset or malformed. A partner rail that is going to fail should\n * fail before the process claims to be up.\n *\n * ## 🔴 The shape check, and the measurement that put it here\n *\n * The key is trimmed and checked against `^(0x)?[0-9a-fA-F]{64}$` before it\n * reaches the payment SDK, and that is a SECURITY guard, not politeness.\n * Measured 2026-08-30 with `ethers` 6.17.0, the version `uvd-x402-sdk` 2.75.0\n * pulls in:\n *\n * * `new ethers.Wallet('0x'+64hex)` with a **trailing newline** — the single\n * most common way an env var gets malformed, e.g. `KEY=$(cat file)` —\n * throws `invalid BytesLike value (argument=\"value\", value=\"0xabab…ab\\n\")`.\n * **The entire private key is inside the message, verbatim.**\n * * only a well-formed-but-invalid key reaches the redacted path,\n * `invalid private key (argument=\"privateKey\", value=\"[REDACTED]\")`.\n *\n * So the redaction everyone assumes is there covers the second case and not the\n * first, and the first is the likely one. Trimming closes the newline path; the\n * shape check guarantees that whatever reaches `ethers` is exactly 64 hex\n * characters and can therefore only fail into the REDACTED branch. The error\n * this function throws names the variable and the length and never the value.\n *\n * ⚠️ Reported upstream, not patched there by this session: `signRequest` in\n * `uvd-x402-sdk/erc8128` hands its `privateKey` straight to `new\n * ethers.Wallet()` (`signer.ts:255-258`) and has the same exposure for anyone\n * calling it directly. The house rule is that the fix goes upstream; this guard\n * protects THIS path in the meantime and is not a reimplementation of anything.\n */\nexport function partnerFromEnv(\n options: PartnerOptions & {\n /** Which variable holds the key. Defaults to `DESCRIBE_PARTNER_PRIVATE_KEY`. */\n envVar?: string;\n /** Injectable for tests. Defaults to `process.env`. */\n env?: Record<string, string | undefined>;\n } = {},\n): PartnerSigner {\n const { chainId = PARTNER_CHAIN_ID, envVar = PARTNER_KEY_ENV } = options;\n const env = options.env ?? (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;\n\n const raw = env?.[envVar];\n if (typeof raw !== 'string' || raw.trim() === '') {\n throw new Error(\n `partnerFromEnv: ${envVar} is not set. The partner rail signs every ` +\n 'request with a dedicated wallet; without its key this client is an ' +\n 'anonymous client, and an anonymous client pays. Set the variable, or ' +\n 'use partnerFromSigner() with a signer you build yourself.',\n );\n }\n\n // Trimmed on purpose: a private key has no meaningful surrounding\n // whitespace, and the alternative to trimming is the ethers leak above.\n const key = raw.trim();\n if (!/^(0x)?[0-9a-fA-F]{64}$/.test(key)) {\n // Length and nothing else. Never the value, never a prefix of it, never a\n // \"did you mean\" that echoes it back.\n throw new Error(\n `partnerFromEnv: ${envVar} is not a 32-byte hex private key ` +\n `(got ${key.length} characters after trimming; expected 64, or 66 with ` +\n 'the 0x prefix). The value is deliberately not shown.',\n );\n }\n\n // The address is derived by the payment SDK from the key, so we do not know\n // it here without building a wallet ourselves — which would mean importing\n // `ethers` into this package. It stays undefined; error messages lose one\n // detail and this package keeps its dependency list empty.\n return {\n async sign({ method, url }) {\n return plainHeaders(\n await signRequest({ method, url, chainId, nonce: mintNonce(), privateKey: key }),\n );\n },\n };\n}\n\n/**\n * The synthetic key the payment SDK ships in its ERC-8128 conformance vectors,\n * documented there as a key that never held funds.\n *\n * Exported for one reason: so that a consumer's own tests can exercise the\n * partner rail without anybody typing 64 hex characters into a repository. It\n * is read out of the installed package at call time and is not stored anywhere\n * in this one.\n *\n * 🔴 It is PUBLIC and it is in everybody's `node_modules`. Never fund it, never\n * allowlist it, never use it outside a test.\n */\nexport function syntheticTestKey(): string {\n const key = CONFORMANCE_VECTORS_F3_1.frozen.private_key;\n if (!key) throw new Error('the installed uvd-x402-sdk ships no synthetic test key');\n return key;\n}\n\nexport type { PartnerSigner } from '../client';\nexport { PARTNER_CHAIN_ID, PARTNER_KEY_ENV } from '../config';\n"]}
@@ -0,0 +1,91 @@
1
+ import { X402Client } from 'uvd-x402-sdk';
2
+ import { X as X402Challenge, E as X402Payer } from '../client-s3KrgrCt.mjs';
3
+
4
+ /**
5
+ * The canonical payer — the ONLY file in this package that knows `uvd-x402-sdk`
6
+ * exists.
7
+ *
8
+ * ## Why it lives behind a subpath instead of in the main entry
9
+ *
10
+ * `uvd-x402-sdk` depends on `ethers` plus three `@noble/*` packages (measured
11
+ * 2026-08-30 with `npm view uvd-x402-sdk dependencies`). Measured on the same
12
+ * day, **all three live HTTP consumers of describe.net read only free routes**:
13
+ * EM's client says so in its docstring (*"Free routes only … Paid routes are a
14
+ * separate, deliberate decision and are NOT implemented here"*), MeshRelay
15
+ * fetches `/wallets/{w}/chains`, KarmaKadabra reads free and falls back to the
16
+ * facilitator. Three of three would install a signing stack for code they never
17
+ * call — and Saul's stated goal for this whole line of work is a widget so
18
+ * light that a stranger pastes it into a news page.
19
+ *
20
+ * So: `uvd-x402-sdk` is an OPTIONAL peer dependency, and the split is enforced
21
+ * by the build (`tsup.config.ts` has two entries; `index` never reaches here).
22
+ * This is the same shape the payment SDK itself uses for its thirteen optional
23
+ * peers — the house convention, not a new one.
24
+ *
25
+ * ## What it does NOT do, and this is the absolute part
26
+ *
27
+ * It does not sign. It does not build an EIP-3009 authorization. It does not
28
+ * touch a private key. Every one of those is `uvd-x402-sdk`'s and stays there:
29
+ * if the payment SDK lacks something, the fix goes UPSTREAM and is consumed
30
+ * from here — never patched in this package.
31
+ *
32
+ * ⚠️ **Measured gap, reported not patched (2026-08-30):** npm `uvd-x402-sdk`
33
+ * 2.75.0 has no `isTransientError` export, while PyPI `uvd-x402-sdk` 0.70.0
34
+ * made one public that day. This package therefore classifies transience
35
+ * itself, in `errors.ts`, over describe.net's HTTP surface only. That is a
36
+ * narrower job than the payment SDK's and it is not a reimplementation of it —
37
+ * but the moment npm ships the helper, the classification of PAYMENT failures
38
+ * should come from there. Filed as a report, deliberately not patched here.
39
+ */
40
+
41
+ /**
42
+ * Wrap a connected `X402Client` as a payer this SDK can use.
43
+ *
44
+ * The challenge maps onto `PaymentInfo` almost field for field, because
45
+ * describe.net serves the standard shape — verified live against the 402 of
46
+ * `GET /reputation/wallet/{w}` on 2026-08-30: `recipient`, `recipients.evm`,
47
+ * `amount: "0.01"`, `token: "USDC"`, `supportedChains: [8453, 43114, 42161, 10,
48
+ * 137, 42220]`. So this function forwards; it does not translate. A translator
49
+ * would be a second place where payment knowledge lives.
50
+ *
51
+ * The recipient has ALREADY been checked against the pinned treasury by the
52
+ * time this runs (`DescribeClient.assertPayableTo`), and that ordering is the
53
+ * contract: this function must never be the thing that decides who gets paid.
54
+ *
55
+ * ```ts
56
+ * import { DescribeClient } from 'uvd-describe-sdk';
57
+ * import { payerFromX402Client } from 'uvd-describe-sdk/x402';
58
+ * import { X402Client } from 'uvd-x402-sdk';
59
+ *
60
+ * const x402 = new X402Client();
61
+ * await x402.connectWithPrivateKey(process.env.PAYER_PRIVATE_KEY!, 'base');
62
+ *
63
+ * const describe = new DescribeClient({
64
+ * product: 'my-app',
65
+ * payer: payerFromX402Client(x402),
66
+ * });
67
+ * ```
68
+ *
69
+ * 🔴 The key comes from the environment. Never a literal, never "just for a
70
+ * test": bots scan public repos for `0x` + 64 hex and drain in minutes (two DAO
71
+ * wallets, INC-2026-03-30).
72
+ *
73
+ * ⚠️ **Verification status, stated plainly:** the mapping below is checked
74
+ * against the live 402 body and against `PaymentInfo` / `PaymentResult` in
75
+ * `uvd-x402-sdk` 2.75.0 (`src/types/index.ts:206,272`), and
76
+ * `x402/payer.test.ts` proves the forwarding with a stub client. It has NOT
77
+ * been run through a real settlement — that costs USDC and was out of scope for
78
+ * the session that wrote it. Treat the first live metered call as the test.
79
+ */
80
+ declare function payerFromX402Client(client: X402Client): X402Payer;
81
+ /**
82
+ * The same seam for a wallet this package knows nothing about.
83
+ *
84
+ * Anything that can turn a challenge into an `X-PAYMENT` value is a payer — a
85
+ * browser wallet, a custodial signer, a queue that asks a human. Exported so
86
+ * that "bring your own payment" does not require importing `uvd-x402-sdk` at
87
+ * all, which is the point of the subpath.
88
+ */
89
+ declare function payerFrom(fn: (challenge: X402Challenge) => Promise<string>): X402Payer;
90
+
91
+ export { X402Challenge, X402Payer, payerFrom, payerFromX402Client };
@@ -0,0 +1,91 @@
1
+ import { X402Client } from 'uvd-x402-sdk';
2
+ import { X as X402Challenge, E as X402Payer } from '../client-s3KrgrCt.js';
3
+
4
+ /**
5
+ * The canonical payer — the ONLY file in this package that knows `uvd-x402-sdk`
6
+ * exists.
7
+ *
8
+ * ## Why it lives behind a subpath instead of in the main entry
9
+ *
10
+ * `uvd-x402-sdk` depends on `ethers` plus three `@noble/*` packages (measured
11
+ * 2026-08-30 with `npm view uvd-x402-sdk dependencies`). Measured on the same
12
+ * day, **all three live HTTP consumers of describe.net read only free routes**:
13
+ * EM's client says so in its docstring (*"Free routes only … Paid routes are a
14
+ * separate, deliberate decision and are NOT implemented here"*), MeshRelay
15
+ * fetches `/wallets/{w}/chains`, KarmaKadabra reads free and falls back to the
16
+ * facilitator. Three of three would install a signing stack for code they never
17
+ * call — and Saul's stated goal for this whole line of work is a widget so
18
+ * light that a stranger pastes it into a news page.
19
+ *
20
+ * So: `uvd-x402-sdk` is an OPTIONAL peer dependency, and the split is enforced
21
+ * by the build (`tsup.config.ts` has two entries; `index` never reaches here).
22
+ * This is the same shape the payment SDK itself uses for its thirteen optional
23
+ * peers — the house convention, not a new one.
24
+ *
25
+ * ## What it does NOT do, and this is the absolute part
26
+ *
27
+ * It does not sign. It does not build an EIP-3009 authorization. It does not
28
+ * touch a private key. Every one of those is `uvd-x402-sdk`'s and stays there:
29
+ * if the payment SDK lacks something, the fix goes UPSTREAM and is consumed
30
+ * from here — never patched in this package.
31
+ *
32
+ * ⚠️ **Measured gap, reported not patched (2026-08-30):** npm `uvd-x402-sdk`
33
+ * 2.75.0 has no `isTransientError` export, while PyPI `uvd-x402-sdk` 0.70.0
34
+ * made one public that day. This package therefore classifies transience
35
+ * itself, in `errors.ts`, over describe.net's HTTP surface only. That is a
36
+ * narrower job than the payment SDK's and it is not a reimplementation of it —
37
+ * but the moment npm ships the helper, the classification of PAYMENT failures
38
+ * should come from there. Filed as a report, deliberately not patched here.
39
+ */
40
+
41
+ /**
42
+ * Wrap a connected `X402Client` as a payer this SDK can use.
43
+ *
44
+ * The challenge maps onto `PaymentInfo` almost field for field, because
45
+ * describe.net serves the standard shape — verified live against the 402 of
46
+ * `GET /reputation/wallet/{w}` on 2026-08-30: `recipient`, `recipients.evm`,
47
+ * `amount: "0.01"`, `token: "USDC"`, `supportedChains: [8453, 43114, 42161, 10,
48
+ * 137, 42220]`. So this function forwards; it does not translate. A translator
49
+ * would be a second place where payment knowledge lives.
50
+ *
51
+ * The recipient has ALREADY been checked against the pinned treasury by the
52
+ * time this runs (`DescribeClient.assertPayableTo`), and that ordering is the
53
+ * contract: this function must never be the thing that decides who gets paid.
54
+ *
55
+ * ```ts
56
+ * import { DescribeClient } from 'uvd-describe-sdk';
57
+ * import { payerFromX402Client } from 'uvd-describe-sdk/x402';
58
+ * import { X402Client } from 'uvd-x402-sdk';
59
+ *
60
+ * const x402 = new X402Client();
61
+ * await x402.connectWithPrivateKey(process.env.PAYER_PRIVATE_KEY!, 'base');
62
+ *
63
+ * const describe = new DescribeClient({
64
+ * product: 'my-app',
65
+ * payer: payerFromX402Client(x402),
66
+ * });
67
+ * ```
68
+ *
69
+ * 🔴 The key comes from the environment. Never a literal, never "just for a
70
+ * test": bots scan public repos for `0x` + 64 hex and drain in minutes (two DAO
71
+ * wallets, INC-2026-03-30).
72
+ *
73
+ * ⚠️ **Verification status, stated plainly:** the mapping below is checked
74
+ * against the live 402 body and against `PaymentInfo` / `PaymentResult` in
75
+ * `uvd-x402-sdk` 2.75.0 (`src/types/index.ts:206,272`), and
76
+ * `x402/payer.test.ts` proves the forwarding with a stub client. It has NOT
77
+ * been run through a real settlement — that costs USDC and was out of scope for
78
+ * the session that wrote it. Treat the first live metered call as the test.
79
+ */
80
+ declare function payerFromX402Client(client: X402Client): X402Payer;
81
+ /**
82
+ * The same seam for a wallet this package knows nothing about.
83
+ *
84
+ * Anything that can turn a challenge into an `X-PAYMENT` value is a payer — a
85
+ * browser wallet, a custodial signer, a queue that asks a human. Exported so
86
+ * that "bring your own payment" does not require importing `uvd-x402-sdk` at
87
+ * all, which is the point of the subpath.
88
+ */
89
+ declare function payerFrom(fn: (challenge: X402Challenge) => Promise<string>): X402Payer;
90
+
91
+ export { X402Challenge, X402Payer, payerFrom, payerFromX402Client };
@@ -0,0 +1,29 @@
1
+ 'use strict';
2
+
3
+ // src/x402/index.ts
4
+ function payerFromX402Client(client) {
5
+ return {
6
+ async pay(challenge) {
7
+ const info = {
8
+ recipient: String(challenge.recipient ?? ""),
9
+ recipients: challenge.recipients,
10
+ amount: String(challenge.amount ?? ""),
11
+ token: typeof challenge.token === "string" ? challenge.token : "USDC",
12
+ supportedChains: Array.isArray(challenge.supportedChains) ? challenge.supportedChains : void 0
13
+ };
14
+ const result = await client.createPayment(info);
15
+ if (!result.success || !result.paymentHeader) {
16
+ throw new Error(`x402 payment was not created: ${result.error ?? "no header returned"}`);
17
+ }
18
+ return result.paymentHeader;
19
+ }
20
+ };
21
+ }
22
+ function payerFrom(fn) {
23
+ return { pay: fn };
24
+ }
25
+
26
+ exports.payerFrom = payerFrom;
27
+ exports.payerFromX402Client = payerFromX402Client;
28
+ //# sourceMappingURL=index.js.map
29
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../../src/x402/index.ts"],"names":[],"mappings":";;;AAuFO,SAAS,oBAAoB,MAAA,EAA+B;AACjE,EAAA,OAAO;AAAA,IACL,MAAM,IAAI,SAAA,EAA2C;AACnD,MAAA,MAAM,IAAA,GAAoB;AAAA,QACxB,SAAA,EAAW,MAAA,CAAO,SAAA,CAAU,SAAA,IAAa,EAAE,CAAA;AAAA,QAC3C,YAAY,SAAA,CAAU,UAAA;AAAA,QACtB,MAAA,EAAQ,MAAA,CAAO,SAAA,CAAU,MAAA,IAAU,EAAE,CAAA;AAAA,QACrC,OAAO,OAAO,SAAA,CAAU,KAAA,KAAU,QAAA,GAAW,UAAU,KAAA,GAAQ,MAAA;AAAA,QAC/D,iBAAiB,KAAA,CAAM,OAAA,CAAQ,UAAU,eAAe,CAAA,GACnD,UAAU,eAAA,GACX;AAAA,OACN;AAEA,MAAA,MAAM,MAAA,GAAS,MAAM,MAAA,CAAO,aAAA,CAAc,IAAI,CAAA;AAC9C,MAAA,IAAI,CAAC,MAAA,CAAO,OAAA,IAAW,CAAC,OAAO,aAAA,EAAe;AAC5C,QAAA,MAAM,IAAI,KAAA,CAAM,CAAA,8BAAA,EAAiC,MAAA,CAAO,KAAA,IAAS,oBAAoB,CAAA,CAAE,CAAA;AAAA,MACzF;AACA,MAAA,OAAO,MAAA,CAAO,aAAA;AAAA,IAChB;AAAA,GACF;AACF;AAUO,SAAS,UAAU,EAAA,EAA8D;AACtF,EAAA,OAAO,EAAE,KAAK,EAAA,EAAG;AACnB","file":"index.js","sourcesContent":["/**\n * The canonical payer — the ONLY file in this package that knows `uvd-x402-sdk`\n * exists.\n *\n * ## Why it lives behind a subpath instead of in the main entry\n *\n * `uvd-x402-sdk` depends on `ethers` plus three `@noble/*` packages (measured\n * 2026-08-30 with `npm view uvd-x402-sdk dependencies`). Measured on the same\n * day, **all three live HTTP consumers of describe.net read only free routes**:\n * EM's client says so in its docstring (*\"Free routes only … Paid routes are a\n * separate, deliberate decision and are NOT implemented here\"*), MeshRelay\n * fetches `/wallets/{w}/chains`, KarmaKadabra reads free and falls back to the\n * facilitator. Three of three would install a signing stack for code they never\n * call — and Saul's stated goal for this whole line of work is a widget so\n * light that a stranger pastes it into a news page.\n *\n * So: `uvd-x402-sdk` is an OPTIONAL peer dependency, and the split is enforced\n * by the build (`tsup.config.ts` has two entries; `index` never reaches here).\n * This is the same shape the payment SDK itself uses for its thirteen optional\n * peers — the house convention, not a new one.\n *\n * ## What it does NOT do, and this is the absolute part\n *\n * It does not sign. It does not build an EIP-3009 authorization. It does not\n * touch a private key. Every one of those is `uvd-x402-sdk`'s and stays there:\n * if the payment SDK lacks something, the fix goes UPSTREAM and is consumed\n * from here — never patched in this package.\n *\n * ⚠️ **Measured gap, reported not patched (2026-08-30):** npm `uvd-x402-sdk`\n * 2.75.0 has no `isTransientError` export, while PyPI `uvd-x402-sdk` 0.70.0\n * made one public that day. This package therefore classifies transience\n * itself, in `errors.ts`, over describe.net's HTTP surface only. That is a\n * narrower job than the payment SDK's and it is not a reimplementation of it —\n * but the moment npm ships the helper, the classification of PAYMENT failures\n * should come from there. Filed as a report, deliberately not patched here.\n */\n\n// TYPE-ONLY, and that is load-bearing: with `import type` the compiler erases\n// this line entirely, so the built `x402/index.js` has **zero** runtime imports\n// and the optional peer stays optional even on the paid path. You get the\n// checked signature of `uvd-x402-sdk` 2.75.0 without the artifact requiring it\n// to be installed — which is what lets a browser bundle this subpath and pass\n// in a wallet-backed client instead.\nimport type { PaymentInfo, X402Client } from 'uvd-x402-sdk';\n\nimport type { X402Payer } from '../client';\nimport type { X402Challenge } from '../errors';\n\n/**\n * Wrap a connected `X402Client` as a payer this SDK can use.\n *\n * The challenge maps onto `PaymentInfo` almost field for field, because\n * describe.net serves the standard shape — verified live against the 402 of\n * `GET /reputation/wallet/{w}` on 2026-08-30: `recipient`, `recipients.evm`,\n * `amount: \"0.01\"`, `token: \"USDC\"`, `supportedChains: [8453, 43114, 42161, 10,\n * 137, 42220]`. So this function forwards; it does not translate. A translator\n * would be a second place where payment knowledge lives.\n *\n * The recipient has ALREADY been checked against the pinned treasury by the\n * time this runs (`DescribeClient.assertPayableTo`), and that ordering is the\n * contract: this function must never be the thing that decides who gets paid.\n *\n * ```ts\n * import { DescribeClient } from 'uvd-describe-sdk';\n * import { payerFromX402Client } from 'uvd-describe-sdk/x402';\n * import { X402Client } from 'uvd-x402-sdk';\n *\n * const x402 = new X402Client();\n * await x402.connectWithPrivateKey(process.env.PAYER_PRIVATE_KEY!, 'base');\n *\n * const describe = new DescribeClient({\n * product: 'my-app',\n * payer: payerFromX402Client(x402),\n * });\n * ```\n *\n * 🔴 The key comes from the environment. Never a literal, never \"just for a\n * test\": bots scan public repos for `0x` + 64 hex and drain in minutes (two DAO\n * wallets, INC-2026-03-30).\n *\n * ⚠️ **Verification status, stated plainly:** the mapping below is checked\n * against the live 402 body and against `PaymentInfo` / `PaymentResult` in\n * `uvd-x402-sdk` 2.75.0 (`src/types/index.ts:206,272`), and\n * `x402/payer.test.ts` proves the forwarding with a stub client. It has NOT\n * been run through a real settlement — that costs USDC and was out of scope for\n * the session that wrote it. Treat the first live metered call as the test.\n */\nexport function payerFromX402Client(client: X402Client): X402Payer {\n return {\n async pay(challenge: X402Challenge): Promise<string> {\n const info: PaymentInfo = {\n recipient: String(challenge.recipient ?? ''),\n recipients: challenge.recipients as PaymentInfo['recipients'],\n amount: String(challenge.amount ?? ''),\n token: typeof challenge.token === 'string' ? challenge.token : 'USDC',\n supportedChains: Array.isArray(challenge.supportedChains)\n ? (challenge.supportedChains as number[])\n : undefined,\n };\n\n const result = await client.createPayment(info);\n if (!result.success || !result.paymentHeader) {\n throw new Error(`x402 payment was not created: ${result.error ?? 'no header returned'}`);\n }\n return result.paymentHeader;\n },\n };\n}\n\n/**\n * The same seam for a wallet this package knows nothing about.\n *\n * Anything that can turn a challenge into an `X-PAYMENT` value is a payer — a\n * browser wallet, a custodial signer, a queue that asks a human. Exported so\n * that \"bring your own payment\" does not require importing `uvd-x402-sdk` at\n * all, which is the point of the subpath.\n */\nexport function payerFrom(fn: (challenge: X402Challenge) => Promise<string>): X402Payer {\n return { pay: fn };\n}\n\nexport type { X402Payer } from '../client';\nexport type { X402Challenge } from '../errors';\n"]}
@@ -0,0 +1,26 @@
1
+ // src/x402/index.ts
2
+ function payerFromX402Client(client) {
3
+ return {
4
+ async pay(challenge) {
5
+ const info = {
6
+ recipient: String(challenge.recipient ?? ""),
7
+ recipients: challenge.recipients,
8
+ amount: String(challenge.amount ?? ""),
9
+ token: typeof challenge.token === "string" ? challenge.token : "USDC",
10
+ supportedChains: Array.isArray(challenge.supportedChains) ? challenge.supportedChains : void 0
11
+ };
12
+ const result = await client.createPayment(info);
13
+ if (!result.success || !result.paymentHeader) {
14
+ throw new Error(`x402 payment was not created: ${result.error ?? "no header returned"}`);
15
+ }
16
+ return result.paymentHeader;
17
+ }
18
+ };
19
+ }
20
+ function payerFrom(fn) {
21
+ return { pay: fn };
22
+ }
23
+
24
+ export { payerFrom, payerFromX402Client };
25
+ //# sourceMappingURL=index.mjs.map
26
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../../src/x402/index.ts"],"names":[],"mappings":";AAuFO,SAAS,oBAAoB,MAAA,EAA+B;AACjE,EAAA,OAAO;AAAA,IACL,MAAM,IAAI,SAAA,EAA2C;AACnD,MAAA,MAAM,IAAA,GAAoB;AAAA,QACxB,SAAA,EAAW,MAAA,CAAO,SAAA,CAAU,SAAA,IAAa,EAAE,CAAA;AAAA,QAC3C,YAAY,SAAA,CAAU,UAAA;AAAA,QACtB,MAAA,EAAQ,MAAA,CAAO,SAAA,CAAU,MAAA,IAAU,EAAE,CAAA;AAAA,QACrC,OAAO,OAAO,SAAA,CAAU,KAAA,KAAU,QAAA,GAAW,UAAU,KAAA,GAAQ,MAAA;AAAA,QAC/D,iBAAiB,KAAA,CAAM,OAAA,CAAQ,UAAU,eAAe,CAAA,GACnD,UAAU,eAAA,GACX;AAAA,OACN;AAEA,MAAA,MAAM,MAAA,GAAS,MAAM,MAAA,CAAO,aAAA,CAAc,IAAI,CAAA;AAC9C,MAAA,IAAI,CAAC,MAAA,CAAO,OAAA,IAAW,CAAC,OAAO,aAAA,EAAe;AAC5C,QAAA,MAAM,IAAI,KAAA,CAAM,CAAA,8BAAA,EAAiC,MAAA,CAAO,KAAA,IAAS,oBAAoB,CAAA,CAAE,CAAA;AAAA,MACzF;AACA,MAAA,OAAO,MAAA,CAAO,aAAA;AAAA,IAChB;AAAA,GACF;AACF;AAUO,SAAS,UAAU,EAAA,EAA8D;AACtF,EAAA,OAAO,EAAE,KAAK,EAAA,EAAG;AACnB","file":"index.mjs","sourcesContent":["/**\n * The canonical payer — the ONLY file in this package that knows `uvd-x402-sdk`\n * exists.\n *\n * ## Why it lives behind a subpath instead of in the main entry\n *\n * `uvd-x402-sdk` depends on `ethers` plus three `@noble/*` packages (measured\n * 2026-08-30 with `npm view uvd-x402-sdk dependencies`). Measured on the same\n * day, **all three live HTTP consumers of describe.net read only free routes**:\n * EM's client says so in its docstring (*\"Free routes only … Paid routes are a\n * separate, deliberate decision and are NOT implemented here\"*), MeshRelay\n * fetches `/wallets/{w}/chains`, KarmaKadabra reads free and falls back to the\n * facilitator. Three of three would install a signing stack for code they never\n * call — and Saul's stated goal for this whole line of work is a widget so\n * light that a stranger pastes it into a news page.\n *\n * So: `uvd-x402-sdk` is an OPTIONAL peer dependency, and the split is enforced\n * by the build (`tsup.config.ts` has two entries; `index` never reaches here).\n * This is the same shape the payment SDK itself uses for its thirteen optional\n * peers — the house convention, not a new one.\n *\n * ## What it does NOT do, and this is the absolute part\n *\n * It does not sign. It does not build an EIP-3009 authorization. It does not\n * touch a private key. Every one of those is `uvd-x402-sdk`'s and stays there:\n * if the payment SDK lacks something, the fix goes UPSTREAM and is consumed\n * from here — never patched in this package.\n *\n * ⚠️ **Measured gap, reported not patched (2026-08-30):** npm `uvd-x402-sdk`\n * 2.75.0 has no `isTransientError` export, while PyPI `uvd-x402-sdk` 0.70.0\n * made one public that day. This package therefore classifies transience\n * itself, in `errors.ts`, over describe.net's HTTP surface only. That is a\n * narrower job than the payment SDK's and it is not a reimplementation of it —\n * but the moment npm ships the helper, the classification of PAYMENT failures\n * should come from there. Filed as a report, deliberately not patched here.\n */\n\n// TYPE-ONLY, and that is load-bearing: with `import type` the compiler erases\n// this line entirely, so the built `x402/index.js` has **zero** runtime imports\n// and the optional peer stays optional even on the paid path. You get the\n// checked signature of `uvd-x402-sdk` 2.75.0 without the artifact requiring it\n// to be installed — which is what lets a browser bundle this subpath and pass\n// in a wallet-backed client instead.\nimport type { PaymentInfo, X402Client } from 'uvd-x402-sdk';\n\nimport type { X402Payer } from '../client';\nimport type { X402Challenge } from '../errors';\n\n/**\n * Wrap a connected `X402Client` as a payer this SDK can use.\n *\n * The challenge maps onto `PaymentInfo` almost field for field, because\n * describe.net serves the standard shape — verified live against the 402 of\n * `GET /reputation/wallet/{w}` on 2026-08-30: `recipient`, `recipients.evm`,\n * `amount: \"0.01\"`, `token: \"USDC\"`, `supportedChains: [8453, 43114, 42161, 10,\n * 137, 42220]`. So this function forwards; it does not translate. A translator\n * would be a second place where payment knowledge lives.\n *\n * The recipient has ALREADY been checked against the pinned treasury by the\n * time this runs (`DescribeClient.assertPayableTo`), and that ordering is the\n * contract: this function must never be the thing that decides who gets paid.\n *\n * ```ts\n * import { DescribeClient } from 'uvd-describe-sdk';\n * import { payerFromX402Client } from 'uvd-describe-sdk/x402';\n * import { X402Client } from 'uvd-x402-sdk';\n *\n * const x402 = new X402Client();\n * await x402.connectWithPrivateKey(process.env.PAYER_PRIVATE_KEY!, 'base');\n *\n * const describe = new DescribeClient({\n * product: 'my-app',\n * payer: payerFromX402Client(x402),\n * });\n * ```\n *\n * 🔴 The key comes from the environment. Never a literal, never \"just for a\n * test\": bots scan public repos for `0x` + 64 hex and drain in minutes (two DAO\n * wallets, INC-2026-03-30).\n *\n * ⚠️ **Verification status, stated plainly:** the mapping below is checked\n * against the live 402 body and against `PaymentInfo` / `PaymentResult` in\n * `uvd-x402-sdk` 2.75.0 (`src/types/index.ts:206,272`), and\n * `x402/payer.test.ts` proves the forwarding with a stub client. It has NOT\n * been run through a real settlement — that costs USDC and was out of scope for\n * the session that wrote it. Treat the first live metered call as the test.\n */\nexport function payerFromX402Client(client: X402Client): X402Payer {\n return {\n async pay(challenge: X402Challenge): Promise<string> {\n const info: PaymentInfo = {\n recipient: String(challenge.recipient ?? ''),\n recipients: challenge.recipients as PaymentInfo['recipients'],\n amount: String(challenge.amount ?? ''),\n token: typeof challenge.token === 'string' ? challenge.token : 'USDC',\n supportedChains: Array.isArray(challenge.supportedChains)\n ? (challenge.supportedChains as number[])\n : undefined,\n };\n\n const result = await client.createPayment(info);\n if (!result.success || !result.paymentHeader) {\n throw new Error(`x402 payment was not created: ${result.error ?? 'no header returned'}`);\n }\n return result.paymentHeader;\n },\n };\n}\n\n/**\n * The same seam for a wallet this package knows nothing about.\n *\n * Anything that can turn a challenge into an `X-PAYMENT` value is a payer — a\n * browser wallet, a custodial signer, a queue that asks a human. Exported so\n * that \"bring your own payment\" does not require importing `uvd-x402-sdk` at\n * all, which is the point of the subpath.\n */\nexport function payerFrom(fn: (challenge: X402Challenge) => Promise<string>): X402Payer {\n return { pay: fn };\n}\n\nexport type { X402Payer } from '../client';\nexport type { X402Challenge } from '../errors';\n"]}
package/package.json ADDED
@@ -0,0 +1,97 @@
1
+ {
2
+ "name": "uvd-describe-sdk",
3
+ "version": "0.1.0",
4
+ "description": "Read reputation from describe.net — the ERC-8004 index across 11 chains. Free lookups need no dependency; metered lookups pay their 402 through uvd-x402-sdk, or read free over the ERC-8128 partner rail. null is never 0.",
5
+ "author": "Ultravioleta DAO <ultravioletadao@gmail.com>",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/UltravioletaDAO/uvd-describe-sdk-typescript"
10
+ },
11
+ "homepage": "https://describe.net",
12
+ "keywords": [
13
+ "describe",
14
+ "reputation",
15
+ "erc-8004",
16
+ "trustless-agents",
17
+ "x402",
18
+ "agents",
19
+ "onchain-reputation",
20
+ "leaderboard",
21
+ "sdk"
22
+ ],
23
+ "main": "./dist/index.js",
24
+ "module": "./dist/index.mjs",
25
+ "types": "./dist/index.d.ts",
26
+ "exports": {
27
+ ".": {
28
+ "types": "./dist/index.d.ts",
29
+ "import": "./dist/index.mjs",
30
+ "require": "./dist/index.js"
31
+ },
32
+ "./x402": {
33
+ "types": "./dist/x402/index.d.ts",
34
+ "import": "./dist/x402/index.mjs",
35
+ "require": "./dist/x402/index.js"
36
+ },
37
+ "./partner": {
38
+ "types": "./dist/partner/index.d.ts",
39
+ "import": "./dist/partner/index.mjs",
40
+ "require": "./dist/partner/index.js"
41
+ }
42
+ },
43
+ "typesVersions": {
44
+ "*": {
45
+ "x402": [
46
+ "./dist/x402/index.d.ts"
47
+ ],
48
+ "partner": [
49
+ "./dist/partner/index.d.ts"
50
+ ]
51
+ }
52
+ },
53
+ "files": [
54
+ "dist",
55
+ "src/**/*.ts",
56
+ "!src/**/*.test.ts",
57
+ "!src/__fixtures__/**",
58
+ "README.md",
59
+ "LICENSE"
60
+ ],
61
+ "scripts": {
62
+ "build": "tsup",
63
+ "dev": "tsup --watch",
64
+ "test": "vitest run",
65
+ "test:watch": "vitest",
66
+ "lint": "eslint src --ext .ts",
67
+ "typecheck": "tsc --noEmit",
68
+ "clean": "rimraf dist",
69
+ "schema:refresh": "node scripts/refresh-schema.mjs",
70
+ "schema:check": "node scripts/refresh-schema.mjs --check",
71
+ "smoke": "node scripts/smoke-free.mjs",
72
+ "prepublishOnly": "npm run clean && npm run typecheck && npm run test && npm run lint && npm run build"
73
+ },
74
+ "dependencies": {},
75
+ "peerDependencies": {
76
+ "uvd-x402-sdk": "^2.75.0"
77
+ },
78
+ "peerDependenciesMeta": {
79
+ "uvd-x402-sdk": {
80
+ "optional": true
81
+ }
82
+ },
83
+ "devDependencies": {
84
+ "@types/node": "^22.0.0",
85
+ "eslint": "^9.0.0",
86
+ "ethers": "^6.17.0",
87
+ "rimraf": "^6.0.0",
88
+ "tsup": "^8.3.0",
89
+ "typescript": "^5.7.0",
90
+ "typescript-eslint": "^8.57.2",
91
+ "uvd-x402-sdk": "^2.75.0",
92
+ "vitest": "^2.1.0"
93
+ },
94
+ "engines": {
95
+ "node": ">=18.0.0"
96
+ }
97
+ }
package/src/caveats.ts ADDED
@@ -0,0 +1,124 @@
1
+ /**
2
+ * The caveat codes, exported as a contract.
3
+ *
4
+ * ## The rule, and it is theirs, not ours
5
+ *
6
+ * describe.net declares it in `describenet/caveats.py:88-93`:
7
+ *
8
+ * > **EL TEXTO puede cambiar sin aviso** —re-redactarse, re-medirse, hasta
9
+ * > traducirse—; **EL CODE jamás.**
10
+ *
11
+ * So a consumer branches on `code` and renders `text`, never the reverse. This
12
+ * is not hygiene, it is a repair: until 2026-08-28 a caveat was a bare Spanish
13
+ * string, ecosystem consumers matched on the prose, and when the thin-evidence
14
+ * cut moved on 2026-08-25 every one of those matches broke silently — the
15
+ * string comparison kept returning false and nobody was told.
16
+ *
17
+ * Exporting the set is one of the four "día 0" requirements the platform team
18
+ * put on any SDK of the house (`D9-c0der.md:234-241`): *los caveat `code`s como
19
+ * contrato exportado*. Typing them here means a consumer never re-types them,
20
+ * and a typo is a compile error rather than a branch that is never taken.
21
+ *
22
+ * ## Why the type is not a closed union
23
+ *
24
+ * `CaveatCode | (string & {})` gives autocomplete on the eight codes that exist
25
+ * today AND still accepts a ninth one the server adds tomorrow. A closed union
26
+ * would turn every new server-side code into a type error in code that is
27
+ * already deployed and working — the passthrough rule (tipar lo conocido,
28
+ * CONSERVAR lo que no) applied to the type system. The measured precedent is
29
+ * `Facet.direction`: FastAPI silently dropped a field nobody had declared, and
30
+ * the response looked correct with the data missing.
31
+ *
32
+ * The codes carry no version and never bump `POLICY_VERSION`: a caveat is
33
+ * advisory by construction and identifies a CUT, it never moves a score.
34
+ */
35
+
36
+ /**
37
+ * The eight cuts served on 2026-08-30, copied from the frozen set in
38
+ * `describenet/caveats.py:172-183` (which its own
39
+ * `tests/test_caveat_codes.py` pins literally, so adding or renaming one over
40
+ * there goes red on purpose).
41
+ *
42
+ * Only `no-score` and `burn-address` are computable from public data, so the
43
+ * free routes serve a documented SUBSET — an empty `caveats: []` on a free
44
+ * response means "no public-data caveat", NOT "clean". The other six need the
45
+ * grain and ride the metered routes. See `CAVEAT_SCOPE_FREE`.
46
+ */
47
+ export const CAVEAT_CODES = [
48
+ /** No score to qualify: there is no eligible rating at all. */
49
+ 'no-score',
50
+ /** The concentration signal itself is degraded and should not be leaned on. */
51
+ 'concentration-degraded',
52
+ /** Exactly one distinct counterparty is behind this score. */
53
+ 'single-rater',
54
+ /** Below the evidence bar (`reading_policy.min_raters`, 3 as of 2026-08-30). */
55
+ 'few-raters',
56
+ /** One client wrote more than `reading_policy.top_share` of the ratings. */
57
+ 'top-client-share',
58
+ /** Ratings-per-rater above `reading_policy.campaign_per_rater` — looks like a campaign. */
59
+ 'campaign-per-rater',
60
+ /** The subject rated itself. */
61
+ 'self-rated',
62
+ /**
63
+ * The subject is a burn address: nobody controls it, anyone may rate it, and
64
+ * nobody can answer for its reputation. The ratings are real on-chain facts
65
+ * — which is why they are still served — but the subject is not an identity.
66
+ */
67
+ 'burn-address',
68
+ ] as const;
69
+
70
+ /** The eight known codes as a union — for `switch`, not for validation. */
71
+ export type KnownCaveatCode = (typeof CAVEAT_CODES)[number];
72
+
73
+ /**
74
+ * What a caveat's `code` may be: one of the eight, or any string the server
75
+ * starts sending. The `(string & {})` half is what keeps autocomplete alive
76
+ * while leaving the union open.
77
+ */
78
+ export type CaveatCode = KnownCaveatCode | (string & {});
79
+
80
+ /** As served since 2026-08-28: `{code, text}`, never a bare string. */
81
+ export interface Caveat {
82
+ /** The contract. Stable, kebab-case. Branch on this. */
83
+ code: CaveatCode;
84
+ /** Prose. May be re-worded, re-measured or translated without notice. Render this. */
85
+ text: string;
86
+ }
87
+
88
+ /**
89
+ * What an empty `caveats: []` claims on a FREE route.
90
+ *
91
+ * describe.net's own definition (given 2026-08-29, recorded in
92
+ * `meshrelay/describenet.js:265-277`): on the free routes `[]` means "no
93
+ * PUBLIC-DATA caveat", not "no caveats" — the evidence-quality cuts are only
94
+ * computable behind the metered routes. A surface that renders a bare `[]` as
95
+ * "clean" publishes a claim the index never made. Carry the scope with the
96
+ * list, the same discipline as the `n/m` coverage next to any aggregate.
97
+ */
98
+ export const CAVEAT_SCOPE_FREE = 'public-data-subset';
99
+
100
+ /** Everything a metered route can fire — the free subset plus the six from the grain. */
101
+ export const CAVEAT_SCOPE_METERED = 'full';
102
+
103
+ /**
104
+ * Is this code known to the version of the SDK you have installed?
105
+ *
106
+ * Deliberately NOT a validator: a `false` means "we have not heard of it",
107
+ * never "it is invalid". An unknown code is served through untouched.
108
+ */
109
+ export function isKnownCaveatCode(code: string): code is KnownCaveatCode {
110
+ return (CAVEAT_CODES as readonly string[]).includes(code);
111
+ }
112
+
113
+ /**
114
+ * Does this result carry `code`?
115
+ *
116
+ * Exists so consumers stop writing `caveats.some(c => c.text.includes('...'))`
117
+ * — the exact line that broke silently on 2026-08-25.
118
+ */
119
+ export function hasCaveat(
120
+ subject: { caveats?: readonly Caveat[] } | null | undefined,
121
+ code: CaveatCode,
122
+ ): boolean {
123
+ return (subject?.caveats ?? []).some((c) => c.code === code);
124
+ }