@paidfor/x402-safe-fetch 0.2.1 → 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,13 @@
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
+
3
11
  ## 0.2.1
4
12
 
5
13
  - **Path for sellers the index has never measured.** With `telemetry: "verified"`, when the pre-pay index check
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.1" }
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).
@@ -123,7 +123,7 @@ This is the whole message, for a paid call that got a 500:
123
123
  "amount_usdc": "0.002000",
124
124
  "latency_ms": 1840,
125
125
  "validator_failures": ["http_status:500"],
126
- "client": "x402-safe-fetch/0.2.1",
126
+ "client": "x402-safe-fetch/0.2.2",
127
127
  "proof": {
128
128
  "network": "eip155:8453",
129
129
  "scheme": "exact",
@@ -152,6 +152,9 @@ This is the whole message, for a paid call that got a 500:
152
152
  - **Keyless ingest, https only.** `POST {indexUrl}/telemetry` needs no account and no key, and the index stores
153
153
  no IP address or identity with the row. With `"verified"`, `safeFetch` refuses a plain-http `indexUrl`
154
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.
155
158
  - **Bodies and request parameters never leave your machine.** The path is hashed, the query string is dropped
156
159
  before hashing, and the response is represented only by its sha256. Headers, request bodies, the intent id and
157
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;
@@ -1,3 +1,12 @@
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"];
2
11
  /** `note` when the index answered and said `unknown`: it has never measured this seller (not a timeout or an error). */
3
12
  export const UNKNOWN_SELLER_NOTE = "verdict unknown";
@@ -56,7 +65,7 @@ export async function checkIndex(indexUrl, resourceUrl, o = {}) {
56
65
  try {
57
66
  const url = `${indexUrl.replace(/\/$/, "")}/check?url=${encodeURIComponent(lookupUrl(resourceUrl))}`;
58
67
  const signal = AbortSignal.timeout(timeoutMs);
59
- 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 });
60
69
  if (!res.ok) {
61
70
  res.body?.cancel().catch(() => undefined);
62
71
  return unavailable(`http ${res.status}`);
@@ -1,5 +1,7 @@
1
1
  import type { TelemetryOutcome, TelemetryProof } from "./proof.js";
2
- export declare const CLIENT_ID = "x402-safe-fetch/0.2.1";
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;
package/dist/telemetry.js CHANGED
@@ -9,7 +9,9 @@ import { createHash } from "node:crypto";
9
9
  import { appendFile, mkdir } from "node:fs/promises";
10
10
  import { join } from "node:path";
11
11
  import { REFUSED_OUTCOMES } from "./proof.js";
12
- export const CLIENT_ID = "x402-safe-fetch/0.2.1";
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";
13
15
  /** sha256 hex of the URL path with any trailing slash removed. Query string and fragment never enter it. */
14
16
  export function pathHash(url) {
15
17
  const p = new URL(url).pathname.replace(/\/$/, "") || "/";
@@ -67,7 +69,7 @@ export function sendTelemetry(indexUrl, payload, o) {
67
69
  try {
68
70
  const res = await fetchImpl(`${indexUrl.replace(/\/$/, "")}/telemetry`, {
69
71
  method: "POST",
70
- headers: { "content-type": "application/json" },
72
+ headers: { "content-type": "application/json", [CLIENT_HEADER]: CLIENT_ID },
71
73
  body: JSON.stringify(payload),
72
74
  signal: AbortSignal.timeout(1000),
73
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.1"
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.1` 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.
@@ -71,7 +73,7 @@ Additive over v1. `v` is `2`, `outcome` uses the harness names, `validator_failu
71
73
  "amount_usdc": "0.002000",
72
74
  "latency_ms": 1840,
73
75
  "validator_failures": ["http_status:500"],
74
- "client": "x402-safe-fetch/0.2.1",
76
+ "client": "x402-safe-fetch/0.2.2",
75
77
  "proof": {
76
78
  "network": "eip155:8453",
77
79
  "scheme": "exact",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@paidfor/x402-safe-fetch",
3
- "version": "0.2.1",
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",