@paidfor/x402-safe-fetch 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.2
4
+
5
+ - **Client header.** Every request to the index (`GET {indexUrl}/check` and `POST {indexUrl}/telemetry`) sends
6
+ `X-Paidfor-Client: x402-safe-fetch/0.2.2`, so paidfor.dev can count checks per client instead of filing them
7
+ under `api`. The header carries only the package name and version, the same string as the telemetry `client`
8
+ field. It is sent with telemetry `"off"` too, on the index check; `indexUrl: false` sends no index request.
9
+ - `client` in telemetry rows is `x402-safe-fetch/0.2.2`.
10
+
11
+ ## 0.2.1
12
+
13
+ - **Path for sellers the index has never measured.** With `telemetry: "verified"`, when the pre-pay index check
14
+ answered `unknown`, that call's v2 row adds `path`: the plain URL path (no query string or fragment, at most
15
+ 512 characters), so the index can put the seller on its candidate list and buy it itself. For known sellers
16
+ `path` is absent and `path_hash` is unchanged; `"anonymous"` never sends it. See docs/telemetry.md.
17
+ - `client` in telemetry rows is `x402-safe-fetch/0.2.1`.
18
+
3
19
  ## 0.2.0
4
20
 
5
21
  - **Verified telemetry.** `telemetry` takes a third value, `"verified"`, which sends a v2 row: the outcome under
package/README.md CHANGED
@@ -97,7 +97,7 @@ v1 row:
97
97
 
98
98
  ```json
99
99
  { "v": 1, "host": "api.example.com", "path_hash": "<sha256 hex of the path>", "outcome": "ok",
100
- "amount_usdc": "0.010000", "latency_ms": 412, "validator_failures": [], "client": "x402-safe-fetch/0.2.0" }
100
+ "amount_usdc": "0.010000", "latency_ms": 412, "validator_failures": [], "client": "x402-safe-fetch/0.2.2" }
101
101
  ```
102
102
 
103
103
  Both payloads and every field are documented in [docs/telemetry.md](docs/telemetry.md).
@@ -109,9 +109,8 @@ paidfor.dev measures sellers with its own wallet, which cannot cover the whole m
109
109
  on-chain that you actually paid: it looks up the `AuthorizationUsed(payer, nonce)` event and the matching USDC
110
110
  `Transfer` on Base. Rows that do not verify are stored but never counted.
111
111
 
112
- > **Status:** the index verifies v2 rows starting with its next release. Until then it accepts only v1 rows, so a
113
- > verified row is answered with a 400, which the client swallows and counts in `debug.log`, and
114
- > `verification_url` answers 404. Nothing about your purchase changes.
112
+ > **Status:** paidfor.dev verifies v2 rows on Base within about five minutes; `verification_url` shows the
113
+ > result for each row.
115
114
 
116
115
  This is the whole message, for a paid call that got a 500:
117
116
 
@@ -124,7 +123,7 @@ This is the whole message, for a paid call that got a 500:
124
123
  "amount_usdc": "0.002000",
125
124
  "latency_ms": 1840,
126
125
  "validator_failures": ["http_status:500"],
127
- "client": "x402-safe-fetch/0.2.0",
126
+ "client": "x402-safe-fetch/0.2.2",
128
127
  "proof": {
129
128
  "network": "eip155:8453",
130
129
  "scheme": "exact",
@@ -145,9 +144,17 @@ This is the whole message, for a paid call that got a 500:
145
144
  pay-to are readable by anyone. What the row adds is the link from that payment to the seller host, the path
146
145
  hash, the outcome you observed, the validator failures and the response hash. Use `"verified"` only if you
147
146
  are comfortable with that association; `"anonymous"` sends the outcome without it.
147
+ - **The plain path, for unknown sellers only (0.2.1).** When the index answered `unknown` before paying (it has
148
+ never measured that seller), the row also carries `"path": "/v1/quote"`: the URL path, never the query string
149
+ or fragment. The index keeps the host and path of a verified payment to such a seller so it can buy that
150
+ seller itself at its next scheduled run, and lists it at paidfor.dev/candidates. For every seller the index
151
+ knows, only `path_hash` is sent, as before. `"anonymous"` never sends a path.
148
152
  - **Keyless ingest, https only.** `POST {indexUrl}/telemetry` needs no account and no key, and the index stores
149
153
  no IP address or identity with the row. With `"verified"`, `safeFetch` refuses a plain-http `indexUrl`
150
154
  (loopback excepted, for local testing), and telemetry never follows a redirect.
155
+ - **Client header (0.2.2).** Every request to the index, the pre-pay check and the telemetry POST, carries
156
+ `X-Paidfor-Client: x402-safe-fetch/<version>`: the package name and version, nothing else. The index uses it
157
+ only to count calls per client.
151
158
  - **Bodies and request parameters never leave your machine.** The path is hashed, the query string is dropped
152
159
  before hashing, and the response is represented only by its sha256. Headers, request bodies, the intent id and
153
160
  validator evidence are never sent.
@@ -1,11 +1,3 @@
1
- /**
2
- * The only file that knows the shape of GET {indexUrl}/check?url=. Contract (paidfor-index lib/check.ts):
3
- * { input, host, verdict: "avoid"|"caution"|"ok"|"unknown", verdict_text, seller: {..., verdict, url} | null,
4
- * resource: { url, listed_price_usdc: "0.002000" | null, modal_quote_usdc, ... } | null,
5
- * probe, seller_url, evidence_url, methodology_url, generated_at }
6
- * Every field is optional here. Advisory only: this never throws, and anything other than a parseable answer
7
- * with a known verdict inside the timeout comes back as { available: false }.
8
- */
9
1
  export type Verdict = "avoid" | "caution" | "ok" | "unknown";
10
2
  export interface IndexCheck {
11
3
  available: boolean;
@@ -19,6 +11,8 @@ export interface IndexCheck {
19
11
  /** Listed price for this exact resource, USDC decimal string, when the index has one. */
20
12
  listed_price_usdc: string | null;
21
13
  }
14
+ /** `note` when the index answered and said `unknown`: it has never measured this seller (not a timeout or an error). */
15
+ export declare const UNKNOWN_SELLER_NOTE = "verdict unknown";
22
16
  /** Seller page on the site that hosts the index: https://paidfor.dev/v1 -> https://paidfor.dev/seller/<host>. */
23
17
  export declare function sellerPageUrl(indexUrl: string, host: string): string;
24
18
  /** Strip query and fragment: the index matches on host + path and never needs request parameters. */
@@ -1,4 +1,15 @@
1
+ /**
2
+ * The only file that knows the shape of GET {indexUrl}/check?url=. Contract (paidfor-index lib/check.ts):
3
+ * { input, host, verdict: "avoid"|"caution"|"ok"|"unknown", verdict_text, seller: {..., verdict, url} | null,
4
+ * resource: { url, listed_price_usdc: "0.002000" | null, modal_quote_usdc, ... } | null,
5
+ * probe, seller_url, evidence_url, methodology_url, generated_at }
6
+ * Every field is optional here. Advisory only: this never throws, and anything other than a parseable answer
7
+ * with a known verdict inside the timeout comes back as { available: false }.
8
+ */
9
+ import { CLIENT_HEADER, CLIENT_ID } from "./telemetry.js";
1
10
  const VERDICTS = ["avoid", "caution", "ok", "unknown"];
11
+ /** `note` when the index answered and said `unknown`: it has never measured this seller (not a timeout or an error). */
12
+ export const UNKNOWN_SELLER_NOTE = "verdict unknown";
2
13
  const str = (v) => (typeof v === "string" && v.trim() !== "" ? v : null);
3
14
  const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : null);
4
15
  /** Seller page on the site that hosts the index: https://paidfor.dev/v1 -> https://paidfor.dev/seller/<host>. */
@@ -35,7 +46,7 @@ export function parseCheck(body, indexUrl, resourceUrl) {
35
46
  listed_price_usdc: str(resource?.listed_price_usdc),
36
47
  };
37
48
  if (verdict === "unknown")
38
- out.note = rawVerdict ? "verdict unknown" : "no verdict in response";
49
+ out.note = rawVerdict ? UNKNOWN_SELLER_NOTE : "no verdict in response";
39
50
  return out;
40
51
  }
41
52
  export async function checkIndex(indexUrl, resourceUrl, o = {}) {
@@ -54,7 +65,7 @@ export async function checkIndex(indexUrl, resourceUrl, o = {}) {
54
65
  try {
55
66
  const url = `${indexUrl.replace(/\/$/, "")}/check?url=${encodeURIComponent(lookupUrl(resourceUrl))}`;
56
67
  const signal = AbortSignal.timeout(timeoutMs);
57
- const res = await fetchImpl(url, { headers: { accept: "application/json" }, signal });
68
+ const res = await fetchImpl(url, { headers: { accept: "application/json", [CLIENT_HEADER]: CLIENT_ID }, signal });
58
69
  if (!res.ok) {
59
70
  res.body?.cancel().catch(() => undefined);
60
71
  return unavailable(`http ${res.status}`);
@@ -16,7 +16,7 @@ import { registerExactEvmScheme } from "@x402/evm/exact/client";
16
16
  import { wrapFetchWithPayment } from "@x402/fetch";
17
17
  import { readBodyTee } from "./body.js";
18
18
  import { IntentIndeterminateError, PaymentRefusedError, SafeFetchError } from "./errors.js";
19
- import { checkIndex } from "./index-client.js";
19
+ import { UNKNOWN_SELLER_NOTE, checkIndex } from "./index-client.js";
20
20
  import { IntentStore } from "./intents.js";
21
21
  import { PriceBook, USDC_BY_NETWORK, atomicToUsdc, exceedsRatio, quoteRatio, resourceKey, usdToAtomic, usdcStringToAtomic } from "./price.js";
22
22
  import { DEFAULT_MAX_RATIO, REFUSED_OUTCOMES, buildProof, failureLabels, harnessOutcome } from "./proof.js";
@@ -160,6 +160,7 @@ export function safeFetch(wallet, options) {
160
160
  latencyMs: r.latency_ms,
161
161
  validatorFailures: failureLabels(r.validator_failures, r.response?.status),
162
162
  proof: r.proof,
163
+ unknownSeller: r.index_note === UNKNOWN_SELLER_NOTE,
163
164
  })
164
165
  : buildPayload({ url: r.url, outcome: r.outcome, amountUsdc: r.amount_usdc, latencyMs: r.latency_ms, validatorFailures: r.validator_failures });
165
166
  void sendTelemetry(indexUrl, payload, { receiptsDir, fetchImpl: baseFetch });
@@ -1,5 +1,7 @@
1
1
  import type { TelemetryOutcome, TelemetryProof } from "./proof.js";
2
- export declare const CLIENT_ID = "x402-safe-fetch/0.2.0";
2
+ export declare const CLIENT_ID = "x402-safe-fetch/0.2.2";
3
+ /** Sent on every request to the index so it can count calls per client. Carries only CLIENT_ID. */
4
+ export declare const CLIENT_HEADER = "X-Paidfor-Client";
3
5
  export interface TelemetryPayload {
4
6
  v: 1;
5
7
  host: string;
@@ -30,7 +32,13 @@ export interface TelemetryPayloadV2 {
30
32
  client: typeof CLIENT_ID;
31
33
  /** Present only when an authorization was signed and sent. Never on a refused outcome. */
32
34
  proof?: TelemetryProof;
35
+ /** The plain URL path (no query string or fragment), only when the index answered `unknown` for this seller. */
36
+ path?: string;
33
37
  }
38
+ /** Longest path sent; a longer one is left out rather than risk the row. */
39
+ export declare const MAX_PATH_LENGTH = 512;
40
+ /** The URL path exactly as it is hashed for path_hash, before the trailing slash is removed. Null past MAX_PATH_LENGTH. */
41
+ export declare function plainPath(url: string): string | null;
34
42
  export declare function buildPayloadV2(i: {
35
43
  url: string;
36
44
  outcome: TelemetryOutcome;
@@ -38,6 +46,8 @@ export declare function buildPayloadV2(i: {
38
46
  latencyMs: number;
39
47
  validatorFailures: string[];
40
48
  proof: TelemetryProof | null;
49
+ /** The pre-pay index check answered `unknown`: send the plain path for this call. */
50
+ unknownSeller?: boolean;
41
51
  }): TelemetryPayloadV2;
42
52
  /** Never awaited by callers, never throws, never rejects. Returns the promise only so tests can wait on it. */
43
53
  export declare function sendTelemetry(indexUrl: string, payload: TelemetryPayload | TelemetryPayloadV2, o: {
package/dist/telemetry.js CHANGED
@@ -1,14 +1,17 @@
1
1
  /**
2
2
  * Outcome telemetry. Exactly the payloads in docs/telemetry.md. "anonymous" sends v1: no bodies, no wallet
3
3
  * address, no request parameters, no intent id. "verified" sends v2: the v1 fields with harness outcome names,
4
- * plus `proof` (payer, nonce, pay-to, tx hash) for paid calls so the index can check the payment on Base.
4
+ * plus `proof` (payer, nonce, pay-to, tx hash) for paid calls so the index can check the payment on Base, and the
5
+ * plain `path` only when the index answered `unknown` before paying, so it can buy that seller itself.
5
6
  * Fire-and-forget with a 1 s timeout; failures are only counted in <receiptsDir>/debug.log.
6
7
  */
7
8
  import { createHash } from "node:crypto";
8
9
  import { appendFile, mkdir } from "node:fs/promises";
9
10
  import { join } from "node:path";
10
11
  import { REFUSED_OUTCOMES } from "./proof.js";
11
- export const CLIENT_ID = "x402-safe-fetch/0.2.0";
12
+ export const CLIENT_ID = "x402-safe-fetch/0.2.2";
13
+ /** Sent on every request to the index so it can count calls per client. Carries only CLIENT_ID. */
14
+ export const CLIENT_HEADER = "X-Paidfor-Client";
12
15
  /** sha256 hex of the URL path with any trailing slash removed. Query string and fragment never enter it. */
13
16
  export function pathHash(url) {
14
17
  const p = new URL(url).pathname.replace(/\/$/, "") || "/";
@@ -26,6 +29,13 @@ export function buildPayload(i) {
26
29
  client: CLIENT_ID,
27
30
  };
28
31
  }
32
+ /** Longest path sent; a longer one is left out rather than risk the row. */
33
+ export const MAX_PATH_LENGTH = 512;
34
+ /** The URL path exactly as it is hashed for path_hash, before the trailing slash is removed. Null past MAX_PATH_LENGTH. */
35
+ export function plainPath(url) {
36
+ const p = new URL(url).pathname || "/";
37
+ return p.length <= MAX_PATH_LENGTH ? p : null;
38
+ }
29
39
  export function buildPayloadV2(i) {
30
40
  const p = {
31
41
  ...buildPayload({ ...i, outcome: i.outcome }),
@@ -34,6 +44,11 @@ export function buildPayloadV2(i) {
34
44
  };
35
45
  if (i.proof && !REFUSED_OUTCOMES.has(i.outcome))
36
46
  p.proof = { ...i.proof };
47
+ if (i.unknownSeller) {
48
+ const path = plainPath(i.url);
49
+ if (path)
50
+ p.path = path;
51
+ }
37
52
  return p;
38
53
  }
39
54
  let failures = 0;
@@ -54,7 +69,7 @@ export function sendTelemetry(indexUrl, payload, o) {
54
69
  try {
55
70
  const res = await fetchImpl(`${indexUrl.replace(/\/$/, "")}/telemetry`, {
56
71
  method: "POST",
57
- headers: { "content-type": "application/json" },
72
+ headers: { "content-type": "application/json", [CLIENT_HEADER]: CLIENT_ID },
58
73
  body: JSON.stringify(payload),
59
74
  signal: AbortSignal.timeout(1000),
60
75
  // The route answers directly; never let a redirect carry the row somewhere else (or to plain http).
package/docs/telemetry.md CHANGED
@@ -18,7 +18,7 @@ No account and no key are needed to send it.
18
18
  "amount_usdc": "0.010000",
19
19
  "latency_ms": 412,
20
20
  "validator_failures": [],
21
- "client": "x402-safe-fetch/0.2.0"
21
+ "client": "x402-safe-fetch/0.2.2"
22
22
  }
23
23
  ```
24
24
 
@@ -31,7 +31,7 @@ No account and no key are needed to send it.
31
31
  | `amount_usdc` | Amount of the signed authorization as a 6-decimal string. `"0.000000"` when nothing was signed. |
32
32
  | `latency_ms` | Wall time of the call in milliseconds, rounded. |
33
33
  | `validator_failures` | Names of the validators that failed, for example `["http_status"]`. Names only, no evidence. |
34
- | `client` | `x402-safe-fetch/<version>`, `x402-safe-fetch/0.2.0` for this version. |
34
+ | `client` | `x402-safe-fetch/<version>`, `x402-safe-fetch/0.2.2` for this version. |
35
35
 
36
36
  ## What is never sent (v1)
37
37
 
@@ -46,6 +46,8 @@ Calls to free resources (no 402) and replays of a stored intent send nothing.
46
46
  ## How it is sent
47
47
 
48
48
  - Fire-and-forget. The purchase never waits for it.
49
+ - With the header `X-Paidfor-Client: x402-safe-fetch/<version>` (from 0.2.2): the package name and version,
50
+ nothing else. The pre-pay `GET {indexUrl}/check` sends the same header, also when telemetry is off.
49
51
  - 1-second timeout.
50
52
  - Any failure is swallowed, including a 404 while the route does not exist yet. Failures are only counted in
51
53
  `<receiptsDir>/debug.log`, which never leaves your machine.
@@ -53,8 +55,9 @@ Calls to free resources (no 402) and replays of a stored intent send nothing.
53
55
  ## The promise
54
56
 
55
57
  This client sends paidfor.dev the outcome of a purchase and nothing that identifies the buyer, the wallet,
56
- or what was bought beyond the seller host and a path hash. If a future version needs to send more, it will
57
- bump `v`, list the new fields here, and stay opt-in.
58
+ or what was bought beyond the seller host and a path hash. The exceptions are opt-in and listed here: v2
59
+ (`"verified"`) adds the proof of payment, and from 0.2.1 the plain path for a seller the index has never
60
+ measured. If a future version needs to send more, it will list the new fields here and stay opt-in.
58
61
 
59
62
  ## Version 2 (`"verified"`)
60
63
 
@@ -70,7 +73,7 @@ Additive over v1. `v` is `2`, `outcome` uses the harness names, `validator_failu
70
73
  "amount_usdc": "0.002000",
71
74
  "latency_ms": 1840,
72
75
  "validator_failures": ["http_status:500"],
73
- "client": "x402-safe-fetch/0.2.0",
76
+ "client": "x402-safe-fetch/0.2.2",
74
77
  "proof": {
75
78
  "network": "eip155:8453",
76
79
  "scheme": "exact",
@@ -108,6 +111,22 @@ Outcomes (`outcome`), mapped like the harness classifier, first match wins:
108
111
  | `refused_verdict`, `refused_ratio`, `refused_max_per_call`, `no_acceptable_quote` | Refused; nothing was signed. **No `proof`.** |
109
112
  | `paid_no_response`, `error` | Signed and sent with no response (with `proof`, `tx_hash` null), or failed before signing (no `proof`). |
110
113
 
114
+ ### `path` (0.2.1): only for sellers the index has never measured
115
+
116
+ When the pre-pay `GET {indexUrl}/check` answered and its verdict was `unknown` (the index has no data on the
117
+ seller; not a timeout or an error), that call's v2 row adds one field:
118
+
119
+ ```json
120
+ "path": "/v1/quote"
121
+ ```
122
+
123
+ the URL path exactly as it was hashed for `path_hash` (no query string, no fragment; left out when longer than
124
+ 512 characters). For any seller the index knows, `path` is absent and `path_hash` is unchanged. The index keeps
125
+ the host and path of a verified payment to such a seller on its candidate list (`GET {indexUrl}/candidates`) so
126
+ it can buy the seller itself at its next scheduled run, and drops the path from the stored row once the payment
127
+ is checked. These are public API endpoints; the index already saw the same origin and path in the pre-pay
128
+ lookup. `"anonymous"` (v1) never sends it.
129
+
111
130
  `validator_failed` stays a v1-only outcome. The payer address, amount and pay-to are public on-chain for every
112
131
  settled payment; the v2 row adds the link from that payment to the seller host, path hash, outcome, validator
113
132
  failures and response hash. Bodies, request parameters, headers, the intent id and validator evidence are never
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@paidfor/x402-safe-fetch",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "Drop-in wrapper around @x402/fetch that refuses overpriced quotes and bad sellers, never pays twice for one intent, and checks what it bought.",
5
5
  "type": "module",
6
6
  "license": "MIT",