@paidfor/x402-safe-fetch 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,50 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.0
4
+
5
+ > **Upgrading turns reporting on.** Through 0.6.0 `telemetry` was `"off"` by default and a from-code payment told the
6
+ > index nothing. From this release, every priced call reports its outcome to the index with its proof of payment
7
+ > (the v2 row in docs/telemetry.md: payer, nonce, pay-to, tx hash; never bodies, request parameters, IP or identity),
8
+ > with no options. If you used the default, you start reporting when you upgrade. Issue
9
+ > [sarmadahsan/paidfor-index#41](https://github.com/sarmadahsan/paidfor-index/issues/41).
10
+
11
+ - **Reporting is on by default, and the account decides who can turn it off.** paidfor is free because these
12
+ reports are what the index is made from. With no account, or a team key on the Free plan, reporting cannot be
13
+ turned off. A team on a paid plan turns it off on its account page, and every client holding one of its keys follows
14
+ that from its next payment: the server says so in every `/v1/team/authorize` answer (`telemetry.report`), which
15
+ the client asks before each payment anyway. When it cannot tell (an older server, no field, a local refusal before
16
+ the team was first asked), it reports.
17
+ - **`telemetry: "anonymous"` and `"off"` are no longer honoured on their own.** They still type-check. Without a
18
+ paid account that turned reporting off, verified rows are still sent and one line says so, once per process, with
19
+ the plans page; `telemetryNotice: false` does not hide that line. Nothing throws. `safeFetch` no longer sends the v1
20
+ row; the index still accepts it from older versions. A paid team's account switch wins over `telemetry: "verified"`.
21
+ - **A plain-http `indexUrl`** (not loopback) gets no rows by default, and one line says so; an explicit
22
+ `telemetry: "verified"` still throws, as before.
23
+ - **The one-time notice** now says reporting is on, why, and who can turn it off. It is shown once per receipts
24
+ directory, as before, also with no options.
25
+ - Unchanged: `indexUrl: false` sends nothing (and checks no seller); the report-only adapters
26
+ (`withPaidforReporting`, `withPaidforReportingAxios`, `report()`) exist only to report and have no switch; refusals
27
+ carry no proof and are counted by reason. This is open source: opting out through the account is a paid feature, not
28
+ the only way out.
29
+ - `TeamDecision` carries `telemetry?: "verified" | "off"`, and `TeamClient.telemetryReport()` returns what the last
30
+ authorize answer said.
31
+ - **Usable content in another format than declared is a warning, not a failed delivery** (paidfor-index issue 40).
32
+ When the seller declares one type and answers with usable content in another (`application/json` declared, the
33
+ article sent as `text/markdown`; JSON labelled `text/plain`), or with no `Content-Type` header, the receipt's
34
+ outcome is now `ok` (it was `validator_failed`), `reported_outcome` is `ok` (it was `non_delivery`), and the
35
+ `content_type` validator says `pass` with `reason` `content_type_mismatch` or `missing_content_type` and
36
+ `evidence.warning: true`. New receipt field `warnings` says it in words, with the declared and received types. The
37
+ v2 telemetry row adds `warnings: ["content_type_mismatch"]` only when there is one (see docs/telemetry.md); rows
38
+ without warnings are unchanged. The price is recorded in `prices.json` as for any `ok` call.
39
+ - It stays a failure when the answer has the shape of an error rather than of content: an HTML page, by its
40
+ `Content-Type` or its first bytes (new reason `html_body`), where HTML was not declared (an HTML label over a body that parses as JSON is JSON mislabelled: a warning); an undeclared
41
+ `application/problem+json` document; a body that should be JSON and does not parse (`body_not_json`, now also for
42
+ broken JSON labelled as another type or sent with no header). The JSON family (`application/json`, `text/json`, any
43
+ `+json` type) is one format: a declared `application/vnd.api+json` answered with `application/json` passes without
44
+ a warning (it failed before). Empty, truncated and non-2xx answers fail as before.
45
+ - New exports: `WARNING_REASONS` and `isFormatWarning` (validators), `ReceiptWarning` and `receiptWarnings` (receipt).
46
+ All additive; older receipts have no `warnings` field.
47
+
3
48
  ## 0.6.0
4
49
 
5
50
  - **A payment the seller rejects is no longer recorded as paid.** When the paid request is answered with HTTP 402
package/README.md CHANGED
@@ -3,7 +3,11 @@
3
3
  A drop-in wrapper around the official [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) client (2.28.x)
4
4
  that protects the buyer before and after paying. It refuses overpriced quotes and sellers rated "avoid", never
5
5
  pays twice for the same intent, and checks what it bought. No account, no key, nothing to sign up for: not to
6
- install it, not to read the index, and not to contribute telemetry.
6
+ install it, not to read the index, and not to contribute to it.
7
+
8
+ **It reports each purchase outcome to the index by default**, with its proof of payment (see
9
+ [Telemetry](#telemetry)). That is the deal that keeps paidfor free: the index is made from these reports. Only a team
10
+ account on a paid plan can turn reporting off.
7
11
 
8
12
  This is the client-side half of the x402 seller index at [paidfor.dev](https://paidfor.dev).
9
13
 
@@ -20,7 +24,7 @@ const fetchWithPay = safeFetch(walletClient, {
20
24
  refuseVerdicts: ["avoid"], // consult the index; "caution" is allowed but logged
21
25
  indexUrl: "https://paidfor.dev/v1",
22
26
  validators: ["http_status", "non_empty", "content_type", "not_truncated"],
23
- telemetry: "verified", // or "anonymous" (no proof of payment) or "off" (the default)
27
+ // Reporting to the index is on by default; only a paid team account turns it off (see Telemetry).
24
28
  receiptsDir: "./.x402-receipts",
25
29
  });
26
30
 
@@ -51,7 +55,7 @@ Payments are exact-scheme USDC on Base mainnet by default (`network: "eip155:845
51
55
  id, quote, amount, reference price and its source, seller verdict, validator results, the settlement header,
52
56
  and the on-chain tx hash when the header carries it. The same receipt is written to the receipts directory as
53
57
  one JSON file per call.
54
- 4. **Telemetry, when enabled.** One POST per call, fire-and-forget. See below.
58
+ 4. **Telemetry.** One POST per call to the index, fire-and-forget, on by default. See below.
55
59
 
56
60
  ## What it blocks and what it does not
57
61
 
@@ -64,7 +68,7 @@ Payments are exact-scheme USDC on Base mainnet by default (`network: "eip155:845
64
68
  | Paying twice for the same `intentId`, across restarts and concurrent processes | Duplicates when each retry uses a new `intentId` (pass a stable one) |
65
69
  | Re-signing after a timeout or crash once a payment was signed | Recovering that money: the call fails with the nonce so you can check the chain |
66
70
  | Non-USDC assets, other networks, non-`exact` schemes, and redirects of the paid request | A seller that settles and then serves wrong or stale content that still passes the four validators |
67
- | Silent non-delivery: a paid 4xx/5xx, empty, wrong content type or truncated body is flagged in the receipt | Getting the money back: validators report failures, they do not refund or dispute |
71
+ | Silent non-delivery: a paid 4xx/5xx, empty or truncated body, or an HTML page in place of the declared type, is flagged in the receipt | Getting the money back: validators report failures, they do not refund or dispute |
68
72
 
69
73
  ## Outcomes
70
74
 
@@ -72,8 +76,8 @@ Payments are exact-scheme USDC on Base mainnet by default (`network: "eip155:845
72
76
 
73
77
  | `outcome` | What happened | `paid` | Returned or thrown |
74
78
  | --- | --- | --- | --- |
75
- | `ok` | Paid, and every validator passed. | `true` | Returned |
76
- | `validator_failed` | Paid, and a validator failed (a non-2xx answer, an empty or truncated body, the wrong content type). | `true` | Returned |
79
+ | `ok` | Paid, and every validator passed. A usable answer in another format than the seller declared is `ok` with a warning in `warnings` (0.7.0). | `true` | Returned |
80
+ | `validator_failed` | Paid, and a validator failed (a non-2xx answer, an empty or truncated body, an HTML or error page in place of the declared type, JSON that does not parse). | `true` | Returned |
77
81
  | `payment_rejected` (0.6.0) | The signed payment was sent and the seller answered HTTP 402 again, with no settlement header or one saying it failed: usually a wallet without enough USDC. Nothing settled. | `false` | Returned (status 402) |
78
82
  | `paid_no_response` | Signed and maybe sent, and no response came back. | `true` if sent | Thrown |
79
83
  | `refused_verdict`, `refused_ratio`, `refused_max_per_call`, `refused_authorize` | Refused before signing. | `false` | Thrown |
@@ -82,6 +86,26 @@ Payments are exact-scheme USDC on Base mainnet by default (`network: "eip155:845
82
86
  | `replayed` | The stored result of an earlier call with this `intentId`. | `false` | Returned |
83
87
  | `error` | Anything else before signing (network, SDK). | `false` | Thrown |
84
88
 
89
+ ### Format warnings (0.7.0)
90
+
91
+ A paid answer whose content is usable but whose format differs from what the seller declared in its 402 (the seller
92
+ declares `application/json` and sends the article as `text/markdown`, or JSON labelled `text/plain`), or that has no
93
+ `Content-Type` header, is not a failed delivery. The receipt's outcome is `ok`, the `content_type` validator says
94
+ `pass` with `reason` `content_type_mismatch` (or `missing_content_type`) and `evidence.warning: true`, and
95
+ `receipt.warnings` says it in words:
96
+
97
+ ```json
98
+ [{ "code": "content_type_mismatch", "validator": "content_type", "declared": "application/json", "received": "text/markdown",
99
+ "message": "the seller declared application/json and the response is text/markdown; the content is returned as sent and the call is not counted as a failure" }]
100
+ ```
101
+
102
+ It stays a failure (`validator_failed`) when the answer has the shape of an error rather than of content: an HTML page
103
+ (by its `Content-Type` or its first bytes) where HTML was not declared (an HTML label over a body that parses as JSON is
104
+ JSON mislabelled, so a warning), an undeclared `application/problem+json`
105
+ document, or a body that should be JSON and does not parse. A different `+json` type or parameters (`; charset=utf-8`)
106
+ are the same format and raise no warning. A seller that declares no type is judged against `application/json`.
107
+ Empty, truncated and non-2xx answers fail as before.
108
+
85
109
  ### When the seller rejects the payment
86
110
 
87
111
  A `payment_rejected` receipt has `paid: false`, no `tx_hash`, no `proof`, and `error.code` `payment_rejected`.
@@ -123,11 +147,11 @@ the chain, so that check is yours.
123
147
  intents/<sha256(intentId)>.json idempotency state and the stored response
124
148
  prices.json last price paid per resource (method + origin + path)
125
149
  debug.log telemetry failures, local only
126
- .verified-telemetry-notice marks that the one-time "verified" notice was shown
150
+ .verified-telemetry-notice marks that the one-time reporting notice was shown
127
151
  ```
128
152
 
129
- Each receipt for a paid call has a `proof` (the same object a verified telemetry row carries) and, with
130
- `telemetry: "verified"`, a `verification_url` of the form `{indexUrl}/telemetry/<payer>/<nonce>`, which shows
153
+ Each receipt for a paid call has a `proof` (the same object a verified telemetry row carries) and, when the row was
154
+ sent, a `verification_url` of the form `{indexUrl}/telemetry/<payer>/<nonce>`, which shows
131
155
  whether the index has verified your row on-chain (usually within about five minutes of the payment).
132
156
  `reported_outcome` is the outcome under the harness names, as the row reports it.
133
157
 
@@ -135,28 +159,38 @@ Keep this directory if you want the idempotency guarantee to survive restarts.
135
159
 
136
160
  ## Telemetry
137
161
 
138
- Three settings. Every one is fire-and-forget: a 1-second timeout, never awaited, every failure swallowed and
162
+ **On by default.** Every priced call sends one v2 row to the index: the outcome under the index's names, the
163
+ seller host, a sha256 of the path, the amount, latency and validator names, and for a paid call a proof of payment
164
+ the index checks on Base (below). Fire-and-forget: a 1-second timeout, never awaited, every failure swallowed and
139
165
  only counted in `debug.log`. Nothing is sent for free resources (no 402) or for replays of a stored intent.
140
166
 
141
- | `telemetry` | Sends |
167
+ **Who can turn it off.** paidfor is free because these reports are what the index is made from. So the account
168
+ decides, not a local flag:
169
+
170
+ | You use the library | Reporting |
142
171
  | --- | --- |
143
- | `"off"` (default) | Nothing. |
144
- | `"anonymous"` | A v1 row: the outcome, amount, latency and validator names. No wallet address, no proof. |
145
- | `"verified"` | A v2 row: the same fields with the outcome under the index's names, plus a proof of payment the index checks on Base. |
172
+ | With no account | On. It cannot be turned off. |
173
+ | With a team key on the Free plan | On. It cannot be turned off. |
174
+ | With a team key on a paid plan (Team, Platform) | On, unless the team turns it off on its [account page](https://paidfor.dev/team). Every client holding one of the team's keys follows that switch from its next payment. |
146
175
 
147
- v1 row:
176
+ In team mode the server says which applies in every `/v1/team/authorize` answer (`telemetry.report`), which the
177
+ client asks before each payment anyway: there is no extra request. When it cannot tell (an older server, an answer
178
+ without the field, a refusal before the team was first asked), it reports.
148
179
 
149
- ```json
150
- { "v": 1, "host": "api.example.com", "path_hash": "<sha256 hex of the path>", "outcome": "ok",
151
- "amount_usdc": "0.010000", "latency_ms": 412, "validator_failures": [], "client": "x402-safe-fetch/<version>" }
152
- ```
180
+ `telemetry: "anonymous"` and `telemetry: "off"` still type-check, but are requests the client cannot grant on its
181
+ own: without a paid account that turned reporting off, verified rows are still sent and one line says so, once per
182
+ process. From this release on, the v1 ("anonymous") row is no longer sent; the index still accepts it from older versions.
183
+
184
+ **Plainly:** this is open source. You can edit your copy, point `indexUrl` at another index, or set
185
+ `indexUrl: false`, which sends nothing and also turns off the seller check before paying. Opting out through the
186
+ account is a paid feature, not the only way out. It is the way that keeps the protections.
153
187
 
154
- Both payloads and every field are documented in [docs/telemetry.md](docs/telemetry.md).
188
+ Every field is documented in [docs/telemetry.md](docs/telemetry.md).
155
189
 
156
190
  ## What verified telemetry sends and why
157
191
 
158
- paidfor.dev measures sellers with its own wallet, which cannot cover the whole market. With
159
- `telemetry: "verified"`, each of your purchases becomes a data point the index can trust, because it can prove
192
+ paidfor.dev measures sellers with its own wallet, which cannot cover the whole market. With reporting on, each of
193
+ your purchases becomes a data point the index can trust, because it can prove
160
194
  on-chain that you actually paid: it looks up the `AuthorizationUsed(payer, nonce)` event and the matching USDC
161
195
  `Transfer` on Base. Rows that do not verify are stored but never counted.
162
196
 
@@ -193,16 +227,17 @@ This is the whole message, for a paid call that got a 500:
193
227
  - **What the payer address adds.** Every settled x402 payment is already a public USDC transfer from your
194
228
  address to the seller's pay-to address, with this nonce, on Base; the address, the amount and the seller's
195
229
  pay-to are readable by anyone. What the row adds is the link from that payment to the seller host, the path
196
- hash, the outcome you observed, the validator failures and the response hash. Use `"verified"` only if you
197
- are comfortable with that association; `"anonymous"` sends the outcome without it.
230
+ hash, the outcome you observed, the validator failures and the response hash. If you are not comfortable with
231
+ that association, use a team account on a paid plan and turn reporting off, or `indexUrl: false` (above).
198
232
  - **The plain path, for unknown sellers only (0.2.1).** When the index answered `unknown` before paying (it has
199
233
  never measured that seller), the row also carries `"path": "/v1/quote"`: the URL path, never the query string
200
234
  or fragment. The index keeps the host and path of a verified payment to such a seller so it can buy that
201
235
  seller itself at its next scheduled run, and lists it at paidfor.dev/candidates. For every seller the index
202
- knows, only `path_hash` is sent, as before. `"anonymous"` never sends a path.
236
+ knows, only `path_hash` is sent, as before.
203
237
  - **Keyless ingest, https only.** `POST {indexUrl}/telemetry` needs no account and no key, and the index stores
204
- no IP address or identity with the row. With `"verified"`, `safeFetch` refuses a plain-http `indexUrl`
205
- (loopback excepted, for local testing), and telemetry never follows a redirect.
238
+ no IP address or identity with the row. A row goes only to an https `indexUrl` (loopback excepted, for local
239
+ testing): with a plain-http one, nothing is sent and one line says so (an explicit `telemetry: "verified"` makes
240
+ it throw instead), and telemetry never follows a redirect.
206
241
  - **Client header (0.2.2).** Every request to the index, the pre-pay check and the telemetry POST, carries
207
242
  `X-Paidfor-Client: x402-safe-fetch/<version>`: the package name and version, nothing else. The index uses it
208
243
  only to count calls per client.
@@ -217,12 +252,14 @@ This is the whole message, for a paid call that got a 500:
217
252
  `overcharge` (paid more than 1.1x the reference, possible only if you raised `maxOverListedRatio`),
218
253
  `wrong_goods`, `duplicate`, plus the client-only `refused_*`, `no_acceptable_quote`, `paid_no_response` and
219
254
  `error`.
220
- - **Turning it off.** `telemetry: "anonymous"` sends the v1 row without any address; `telemetry: "off"` (the
221
- default) sends nothing. `indexUrl: false` turns off the index lookup and all telemetry.
255
+ - **Turning it off.** See [who can turn it off](#telemetry): a team account on a paid plan, on its account page.
256
+ `indexUrl: false` turns off the index lookup and all telemetry.
222
257
 
223
- The first time a receipts directory is used with `"verified"`, the client prints a one-line notice pointing
258
+ The first time a receipts directory is used with reporting on, the client prints a one-line notice pointing
224
259
  here, through `logger.warn` (stderr with the default console). `telemetryNotice: false` turns it off;
225
- `telemetryNotice: (msg) => ...` sends it to your own function instead. Nothing else changes.
260
+ `telemetryNotice: (msg) => ...` sends it to your own function instead. Nothing else changes. The line that
261
+ `"anonymous"` or `"off"` was not honoured is never silenced: `telemetryNotice: false` does not hide it, and a
262
+ function receives it.
226
263
 
227
264
  ## With a team account
228
265
 
package/dist/index.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  export { safeFetch, hashRequest, type SafeFetch, type SafeFetchOptions, type SafeResponse, type CallOptions, type WalletLike, type SafeNetwork, type AuthorizeRequest, type AuthorizeAnswer } from "./safe-fetch.js";
2
2
  export { SafeFetchError, PaymentRefusedError, IntentConflictError, IntentIndeterminateError, TeamRefusedError, type SafeFetchErrorCode } from "./errors.js";
3
- export type { Receipt, Outcome } from "./receipt.js";
3
+ export type { Receipt, Outcome, ReceiptWarning } from "./receipt.js";
4
+ export { receiptWarnings } from "./receipt.js";
5
+ export { WARNING_REASONS, isFormatWarning, type WarningReason } from "./validators/content_type.js";
4
6
  export type { Verdict, IndexCheck } from "./index-client.js";
5
7
  export type { ValidatorName } from "./taxonomy.js";
6
8
  export type { ValidatorResult } from "./validators/types.js";
package/dist/index.js CHANGED
@@ -1,4 +1,6 @@
1
1
  export { safeFetch, hashRequest } from "./safe-fetch.js";
2
2
  export { SafeFetchError, PaymentRefusedError, IntentConflictError, IntentIndeterminateError, TeamRefusedError } from "./errors.js";
3
+ export { receiptWarnings } from "./receipt.js";
4
+ export { WARNING_REASONS, isFormatWarning } from "./validators/content_type.js";
3
5
  export { reportOnly, withPaidforReporting, withPaidforReportingAxios, buildTxOnlyPayload, settlementTx } from "./report-only.js";
4
6
  export { TeamClient, outcomeFor, readDecision, isKeySafeOrigin, cleanProject, TEAM_ORIGIN } from "./team.js";
package/dist/receipt.d.ts CHANGED
@@ -6,6 +6,20 @@ import type { TeamReceipt } from "./team.js";
6
6
  import type { SettlementResponse } from "./x402/types.js";
7
7
  import type { ValidatorResult } from "./validators/types.js";
8
8
  export type Outcome = "ok" | "validator_failed" | "refused_verdict" | "refused_ratio" | "refused_max_per_call" | "refused_authorize" | "no_acceptable_quote" | "no_payment_required" | "paid_no_response" | "payment_rejected" | "replayed" | "error";
9
+ /**
10
+ * Something the caller should know about a call that did not fail it (0.7.0). Today only the format rule: the paid
11
+ * answer is usable but in another format than the seller declared (`content_type_mismatch`), or carried no
12
+ * Content-Type header (`missing_content_type`). The outcome stays `ok`.
13
+ */
14
+ export interface ReceiptWarning {
15
+ code: "content_type_mismatch" | "missing_content_type";
16
+ validator: ValidatorName;
17
+ /** The media type the seller declared in its 402; null when it declared none (application/json was expected). */
18
+ declared: string | null;
19
+ /** The media type of the response; null when it had no Content-Type header. */
20
+ received: string | null;
21
+ message: string;
22
+ }
9
23
  export interface Receipt {
10
24
  v: 1;
11
25
  client: string;
@@ -58,6 +72,8 @@ export interface Receipt {
58
72
  index_note: string | null;
59
73
  validators: Partial<Record<ValidatorName, ValidatorResult>>;
60
74
  validator_failures: ValidatorName[];
75
+ /** Warnings that did not fail the call (0.7.0; absent on older receipts). See ReceiptWarning. */
76
+ warnings?: ReceiptWarning[];
61
77
  settlement: {
62
78
  header: string | null;
63
79
  version: 1 | 2 | null;
@@ -100,5 +116,7 @@ export interface Receipt {
100
116
  */
101
117
  team?: TeamReceipt;
102
118
  }
119
+ /** The receipt's `warnings` from the validator results: a content_type pass with a format warning. */
120
+ export declare function receiptWarnings(results: Partial<Record<ValidatorName, ValidatorResult>>): ReceiptWarning[];
103
121
  /** One JSON file per call: <receiptsDir>/<timestamp>-<random>.json. Returns the file name. */
104
122
  export declare function writeReceipt(dir: string, r: Receipt): Promise<string>;
package/dist/receipt.js CHANGED
@@ -1,6 +1,26 @@
1
1
  import { randomBytes } from "node:crypto";
2
2
  import { join } from "node:path";
3
3
  import { writeJsonDurable } from "./fsutil.js";
4
+ import { isFormatWarning } from "./validators/content_type.js";
5
+ /** The receipt's `warnings` from the validator results: a content_type pass with a format warning. */
6
+ export function receiptWarnings(results) {
7
+ const out = [];
8
+ const ct = results.content_type;
9
+ if (isFormatWarning(ct)) {
10
+ const declared = ct.evidence.expected_source === "requirements" && typeof ct.evidence.expected === "string" ? ct.evidence.expected : null;
11
+ const received = typeof ct.evidence.actual === "string" ? ct.evidence.actual : null;
12
+ const want = declared ? `the seller declared ${declared}` : "the seller declared no type (application/json was expected)";
13
+ const got = received ? `the response is ${received}` : "the response has no Content-Type header";
14
+ out.push({
15
+ code: ct.reason,
16
+ validator: "content_type",
17
+ declared,
18
+ received,
19
+ message: `${want} and ${got}; the content is returned as sent and the call is not counted as a failure`,
20
+ });
21
+ }
22
+ return out;
23
+ }
4
24
  /** One JSON file per call: <receiptsDir>/<timestamp>-<random>.json. Returns the file name. */
5
25
  export async function writeReceipt(dir, r) {
6
26
  const name = `${r.started_at.replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}.json`;
@@ -16,8 +16,13 @@ export interface SafeFetchOptions {
16
16
  /** Validators to run on paid responses. Default: all four. */
17
17
  validators?: ValidatorName[];
18
18
  /**
19
- * Default "off". "anonymous" posts the outcome-only v1 payload in docs/telemetry.md. "verified" posts the v2
20
- * payload: the same fields plus a proof of payment (payer, nonce, pay-to, tx hash) the index checks on Base.
19
+ * Reporting each outcome to the index. On by default: the v2 payload in docs/telemetry.md, the outcome with a proof
20
+ * of payment (payer, nonce, pay-to, tx hash) the index checks on Base. paidfor is free because these reports feed it.
21
+ *
22
+ * The account decides, not this option: reporting stops only for a client in team mode whose account is on a paid
23
+ * plan and turned reporting off on its account page (the server says so in every authorize answer). "anonymous" and
24
+ * "off" ask for less than that; without such an account they are not honoured: verified rows are still sent and one
25
+ * line says so, once per process. Never a throw. `indexUrl: false` sends nothing (and checks no seller).
21
26
  */
22
27
  telemetry?: "anonymous" | "verified" | "off";
23
28
  /** Receipts, intents, price book and debug log. Default "./.x402-receipts" (resolved once, at creation). */
@@ -33,7 +38,7 @@ export interface SafeFetchOptions {
33
38
  warn(msg: string): void;
34
39
  };
35
40
  /**
36
- * The one-time notice that says what `telemetry: "verified"` sends. Default true: it goes to `logger.warn` (stderr
41
+ * The one-time notice that says what reporting sends. Default true: it goes to `logger.warn` (stderr
37
42
  * with the default console). `false` never shows it; a function receives the text instead of `logger`. Useful in
38
43
  * an MCP server, whose client may show anything on stderr as an error.
39
44
  */
@@ -109,4 +114,8 @@ export declare function hashRequest(r: {
109
114
  url: string;
110
115
  body?: Uint8Array | undefined;
111
116
  }): string;
117
+ /** Tests only: show the once-per-process lines again. Not exported from the package. */
118
+ export declare function resetOnceNotices(): void;
119
+ /** Said when `telemetry: "anonymous"` or `"off"` is not honoured: no account, or an account whose plan does not allow it. */
120
+ export declare const TELEMETRY_NOT_HONOURED: (asked: string) => string;
112
121
  export declare function safeFetch(wallet: WalletLike, options: SafeFetchOptions): SafeFetch;
@@ -20,10 +20,10 @@ 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";
23
- import { writeReceipt } from "./receipt.js";
23
+ import { receiptWarnings, writeReceipt } from "./receipt.js";
24
24
  import { PROJECT_RULE, TEAM_ORIGIN, TeamClient, cleanProject, outcomeFor } from "./team.js";
25
25
  import { ALL_VALIDATORS, MAX_BODY_BYTES } from "./taxonomy.js";
26
- import { CLIENT_ID, buildPayload, buildPayloadV2, sendTelemetry } from "./telemetry.js";
26
+ import { CLIENT_ID, buildPayloadV2, sendTelemetry } from "./telemetry.js";
27
27
  import { runAllValidators, validatorsByName } from "./validators/index.js";
28
28
  import { buildResponseRecord, headersToRecord } from "./x402/http.js";
29
29
  import { quoteFromResponse } from "./x402/quote.js";
@@ -72,6 +72,17 @@ function wrapResponse(status, statusText, headers, body, url, receipt) {
72
72
  }
73
73
  const TX_HASH_RE = /^0x[0-9a-fA-F]{64}$/;
74
74
  let envNoticeShown = false;
75
+ /** The line that a request for less than verified reporting is not honoured, once per process. */
76
+ let lessNoticeShown = false;
77
+ /** The line that nothing is reported to a plain-http index, once per process. */
78
+ let insecureNoticeShown = false;
79
+ /** Tests only: show the once-per-process lines again. Not exported from the package. */
80
+ export function resetOnceNotices() {
81
+ envNoticeShown = lessNoticeShown = insecureNoticeShown = false;
82
+ }
83
+ /** Said when `telemetry: "anonymous"` or `"off"` is not honoured: no account, or an account whose plan does not allow it. */
84
+ export const TELEMETRY_NOT_HONOURED = (asked) => `telemetry: "${asked}" is not honoured: purchase outcomes are reported to the index with their proof of payment, because that is what keeps paidfor free. ` +
85
+ "Only a team account on a paid plan can turn reporting off, on its account page (https://paidfor.dev/team); plans: https://paidfor.dev/pricing. Shown once.";
75
86
  /** A project tag as the server takes it, or a TypeError naming where the bad one came from. */
76
87
  function projectTag(v, from) {
77
88
  const p = cleanProject(v);
@@ -166,10 +177,14 @@ export function safeFetch(wallet, options) {
166
177
  const indexUrl = options.indexUrl === false ? undefined : (options.indexUrl ?? "https://paidfor.dev/v1").replace(/\/$/, "");
167
178
  const refuseVerdicts = new Set(options.refuseVerdicts ?? ["avoid"]);
168
179
  const validators = validatorsByName(options.validators ?? [...ALL_VALIDATORS]);
169
- if (options.telemetry === "verified" && indexUrl !== undefined && !isSecureOrLoopback(indexUrl)) {
180
+ const secureIndex = indexUrl !== undefined && isSecureOrLoopback(indexUrl);
181
+ if (options.telemetry === "verified" && indexUrl !== undefined && !secureIndex) {
170
182
  throw new TypeError(`safeFetch: telemetry "verified" needs an https indexUrl (or a loopback one for local testing), got ${indexUrl}`);
171
183
  }
172
- const telemetry = indexUrl !== undefined && (options.telemetry === "anonymous" || options.telemetry === "verified") ? options.telemetry : "off";
184
+ /** Rows carry the payer and nonce, so they go only to an https index, or to this machine. */
185
+ const reporting = secureIndex;
186
+ /** A request for less than verified, which only the account can grant (issue 41). */
187
+ const askedLess = options.telemetry === "anonymous" || options.telemetry === "off" ? options.telemetry : null;
173
188
  const receiptsDir = resolve(options.receiptsDir ?? "./.x402-receipts");
174
189
  const baseFetch = options.fetch ?? globalThis.fetch;
175
190
  const indexTimeoutMs = options.indexTimeoutMs ?? 2000;
@@ -187,8 +202,12 @@ export function safeFetch(wallet, options) {
187
202
  }
188
203
  };
189
204
  const noticeOpt = options.telemetryNotice ?? true;
190
- if (telemetry === "verified" && noticeOpt !== false)
205
+ if (reporting && noticeOpt !== false)
191
206
  void verifiedNotice();
207
+ if (indexUrl !== undefined && !secureIndex && !insecureNoticeShown) {
208
+ insecureNoticeShown = true;
209
+ warn(`nothing is reported to ${indexUrl}: outcome reports carry the payer and nonce and go only to an https index (or a loopback one).`);
210
+ }
192
211
  const team = teamConf
193
212
  ? new TeamClient({
194
213
  origin: teamConf.team.origin ?? TEAM_ORIGIN,
@@ -214,10 +233,10 @@ export function safeFetch(wallet, options) {
214
233
  catch {
215
234
  /* first run */
216
235
  }
217
- const text = 'telemetry: "verified" sends each purchase outcome with its proof of payment (payer address, nonce, pay-to, tx hash) ' +
236
+ const text = "reporting is on: each purchase outcome is sent with its proof of payment (payer address, nonce, pay-to, tx hash) " +
218
237
  `to ${indexUrl}/telemetry so the index can check it on Base. No bodies, request parameters, IP or identity. ` +
219
- 'See "What verified telemetry sends and why": https://www.npmjs.com/package/@paidfor/x402-safe-fetch#what-verified-telemetry-sends-and-why ' +
220
- '(set telemetry: "anonymous" or "off" to change it). Shown once.';
238
+ "This is what keeps paidfor free; a team account on a paid plan can turn it off on its account page. " +
239
+ 'See "What verified telemetry sends and why": https://www.npmjs.com/package/@paidfor/x402-safe-fetch#what-verified-telemetry-sends-and-why. Shown once.';
221
240
  if (typeof noticeOpt === "function") {
222
241
  try {
223
242
  noticeOpt(`x402-safe-fetch: ${text}`);
@@ -246,24 +265,58 @@ export function safeFetch(wallet, options) {
246
265
  return null;
247
266
  }
248
267
  }
268
+ /**
269
+ * Each payment's own authorize answer about reporting, kept with its receipt so that payments in flight at the same
270
+ * time never read each other's (a shared "last answer" would let one payment's answer decide another's row).
271
+ */
272
+ const askedTeam = new WeakMap();
273
+ /**
274
+ * Whether this outcome goes to the index. The account decides: only a team answer saying "off" stops it: this
275
+ * payment's own authorize answer, or, for a refusal made before this payment asked, the last answer the team gave.
276
+ * No answer means report.
277
+ */
278
+ function reportsNow(r) {
279
+ if (!reporting)
280
+ return false;
281
+ if (!team)
282
+ return true;
283
+ return (askedTeam.has(r) ? askedTeam.get(r) : team.telemetryReport()) !== "off";
284
+ }
285
+ /** Say once that a request for less than verified reporting was not honoured. Never silent, never a throw. */
286
+ function lessNotice() {
287
+ if (!askedLess || lessNoticeShown)
288
+ return;
289
+ lessNoticeShown = true;
290
+ const text = TELEMETRY_NOT_HONOURED(askedLess);
291
+ if (typeof noticeOpt === "function") {
292
+ try {
293
+ noticeOpt(`x402-safe-fetch: ${text}`);
294
+ }
295
+ catch {
296
+ /* ignore */
297
+ }
298
+ }
299
+ else
300
+ warn(text);
301
+ }
249
302
  function emitTelemetry(r) {
250
- if (telemetry === "off" || !indexUrl)
303
+ if (!indexUrl || !reportsNow(r))
251
304
  return;
252
305
  // Nothing was paid and the seller is not at fault for a wallet that cannot pay; the contract has no outcome for it.
253
306
  if (r.outcome === "payment_rejected")
254
307
  return;
308
+ lessNotice();
255
309
  try {
256
- const payload = telemetry === "verified"
257
- ? buildPayloadV2({
258
- url: r.url,
259
- outcome: r.reported_outcome ?? "error",
260
- amountUsdc: r.amount_usdc,
261
- latencyMs: r.latency_ms,
262
- validatorFailures: failureLabels(r.validator_failures, r.response?.status),
263
- proof: r.proof,
264
- unknownSeller: r.index_note === UNKNOWN_SELLER_NOTE,
265
- })
266
- : buildPayload({ url: r.url, outcome: r.outcome, amountUsdc: r.amount_usdc, latencyMs: r.latency_ms, validatorFailures: r.validator_failures });
310
+ const payload = buildPayloadV2({
311
+ url: r.url,
312
+ outcome: r.reported_outcome ?? "error",
313
+ amountUsdc: r.amount_usdc,
314
+ latencyMs: r.latency_ms,
315
+ validatorFailures: failureLabels(r.validator_failures, r.response?.status),
316
+ warnings: (r.warnings ?? []).map((w) => w.code),
317
+ proof: r.proof,
318
+ unknownSeller: r.index_note === UNKNOWN_SELLER_NOTE,
319
+ });
267
320
  void sendTelemetry(indexUrl, payload, { receiptsDir, fetchImpl: baseFetch });
268
321
  }
269
322
  catch {
@@ -298,7 +351,7 @@ export function safeFetch(wallet, options) {
298
351
  responseSha256: r.response?.sha256 ?? null,
299
352
  declaredTimeoutS: r.quote.max_timeout_seconds,
300
353
  });
301
- if (r.proof && telemetry === "verified" && indexUrl) {
354
+ if (r.proof && indexUrl && reportsNow(r)) {
302
355
  r.verification_url = `${indexUrl}/telemetry/${r.proof.payer}/${r.proof.nonce}`;
303
356
  }
304
357
  }
@@ -333,6 +386,7 @@ export function safeFetch(wallet, options) {
333
386
  index_note: null,
334
387
  validators: {},
335
388
  validator_failures: [],
389
+ warnings: [],
336
390
  settlement: { header: null, version: null, parsed: null, parse_error: null },
337
391
  tx_hash: null,
338
392
  nonce: null,
@@ -373,6 +427,8 @@ export function safeFetch(wallet, options) {
373
427
  r.seller = original.seller;
374
428
  r.validators = original.validators;
375
429
  r.validator_failures = original.validator_failures;
430
+ if (original.warnings)
431
+ r.warnings = original.warnings;
376
432
  r.tx_hash = original.tx_hash;
377
433
  r.nonce = original.nonce;
378
434
  r.payer = original.payer ?? null;
@@ -759,6 +815,7 @@ export function safeFetch(wallet, options) {
759
815
  }, validators);
760
816
  r.validators = results;
761
817
  r.validator_failures = Object.entries(results).filter(([, v]) => v.status === "fail").map(([k]) => k);
818
+ r.warnings = receiptWarnings(results);
762
819
  r.response = {
763
820
  status: res.status,
764
821
  content_type: res.headers.get("content-type"),
@@ -866,6 +923,7 @@ export function safeFetch(wallet, options) {
866
923
  const d = await team.authorize({ wallet: q.payer, intent_id: q.intentId, resource_url: q.url, pay_to: q.payTo, amount_atomic: q.amountAtomic, network: q.network, asset: q.asset, scheme: q.scheme, protocol: "x402", ...(project ? { project } : {}) });
867
924
  decision = d;
868
925
  r.team = teamReceipt(team.origin, d);
926
+ askedTeam.set(r, d.telemetry);
869
927
  return d.kind === "approve" ? { approve: true, nonce: d.auth_ref, validBefore: d.valid_before } : { approve: false, message: teamMessage(d, q.intentId) };
870
928
  };
871
929
  /** Say what happened to an approved payment, paid or not. Nothing to say when nothing was approved. */
package/dist/team.d.ts CHANGED
@@ -38,6 +38,11 @@ export interface TeamDecisionExtras {
38
38
  usage?: Record<string, unknown>;
39
39
  /** The ledger row for this decision, when the server named one. */
40
40
  ledger_id?: string;
41
+ /**
42
+ * Whether this payment's outcome goes to the index, as the account decides it (`telemetry.report`). "off" only when
43
+ * the team is on a plan that allows it and turned reporting off; absent (an older server, or anything else) means report.
44
+ */
45
+ telemetry?: "verified" | "off";
41
46
  }
42
47
  /** The server's answer, read strictly. Only `approve` lets a payment be signed. */
43
48
  export type TeamDecision = ({
@@ -154,10 +159,18 @@ export declare class TeamClient {
154
159
  /** Reports that could not be written to disk; sent again like the disk queue, lost if the process ends. */
155
160
  private readonly memory;
156
161
  private flushing;
162
+ /** What the last authorize answer said about reporting to the index; undefined until one says, and after any that does not. */
163
+ private lastTelemetry;
157
164
  constructor(o: TeamClientOptions);
158
165
  private post;
159
166
  /** Never throws: anything but a 200 with a readable decision is { kind: "failed" }. */
160
167
  authorize(body: TeamAuthorizeBody): Promise<TeamDecision>;
168
+ /**
169
+ * Whether outcomes go to the index, from the last authorize answer: "off" only when the account turned reporting off
170
+ * on a plan that allows it. Undefined before any answer said so, which means report.
171
+ */
172
+ telemetryReport(): "verified" | "off" | undefined;
173
+ private ask;
161
174
  /**
162
175
  * Tell the team about a payment this client refused before asking it, so the ledger and the bill can count what was
163
176
  * saved. Fire-and-forget: one try, a 2 s timeout, every failure (a 404 from a server without the route included)
package/dist/team.js CHANGED
@@ -69,7 +69,9 @@ function extras(d) {
69
69
  })
70
70
  : [];
71
71
  const usage = d.usage && typeof d.usage === "object" && !Array.isArray(d.usage) ? d.usage : undefined;
72
- return { warnings, ...(usage ? { usage } : {}), ...(str(d.ledger_id) ? { ledger_id: d.ledger_id } : {}) };
72
+ const t = d.telemetry && typeof d.telemetry === "object" ? d.telemetry.report : undefined;
73
+ const telemetry = t === "off" ? "off" : t === "verified" ? "verified" : undefined;
74
+ return { warnings, ...(usage ? { usage } : {}), ...(str(d.ledger_id) ? { ledger_id: d.ledger_id } : {}), ...(telemetry ? { telemetry } : {}) };
73
75
  }
74
76
  function failedStatus(status, body, wallet, origin) {
75
77
  const said = body && typeof body === "object" && str(body.error) ? ` ${body.error.slice(0, 300)}` : "";
@@ -131,6 +133,8 @@ export class TeamClient {
131
133
  /** Reports that could not be written to disk; sent again like the disk queue, lost if the process ends. */
132
134
  memory = new Map();
133
135
  flushing = null;
136
+ /** What the last authorize answer said about reporting to the index; undefined until one says, and after any that does not. */
137
+ lastTelemetry;
134
138
  constructor(o) {
135
139
  if (typeof o.key !== "string" || !o.key.trim() || /\s/.test(o.key.trim()))
136
140
  throw new TypeError("team: key must be a non-empty team key with no spaces");
@@ -159,6 +163,19 @@ export class TeamClient {
159
163
  }
160
164
  /** Never throws: anything but a 200 with a readable decision is { kind: "failed" }. */
161
165
  async authorize(body) {
166
+ const d = await this.ask(body);
167
+ // Fail towards reporting: an answer that does not say "off" (an older server, a failure) clears what an earlier one said.
168
+ this.lastTelemetry = d.telemetry;
169
+ return d;
170
+ }
171
+ /**
172
+ * Whether outcomes go to the index, from the last authorize answer: "off" only when the account turned reporting off
173
+ * on a plan that allows it. Undefined before any answer said so, which means report.
174
+ */
175
+ telemetryReport() {
176
+ return this.lastTelemetry;
177
+ }
178
+ async ask(body) {
162
179
  let res;
163
180
  try {
164
181
  res = await this.post("/v1/team/authorize", body, this.authorizeTimeoutMs);
@@ -1,5 +1,5 @@
1
1
  import type { TelemetryOutcome, TelemetryProof } from "./proof.js";
2
- export declare const CLIENT_ID = "x402-safe-fetch/0.6.0";
2
+ export declare const CLIENT_ID = "x402-safe-fetch/0.7.0";
3
3
  /** Sent on every request to the index so it can count calls per client. Carries only CLIENT_ID. */
4
4
  export declare const CLIENT_HEADER = "X-Paidfor-Client";
5
5
  export interface TelemetryPayload {
@@ -34,6 +34,11 @@ export interface TelemetryPayloadV2 {
34
34
  proof?: TelemetryProof;
35
35
  /** The plain URL path (no query string or fragment), only when the index answered `unknown` for this seller. */
36
36
  path?: string;
37
+ /**
38
+ * Warnings that did not fail the call (0.7.0), only when there are any: `content_type_mismatch` (usable content in
39
+ * another format than the seller declared) or `missing_content_type`. Codes only, no evidence.
40
+ */
41
+ warnings?: string[];
37
42
  }
38
43
  /** Longest path sent; a longer one is left out rather than risk the row. */
39
44
  export declare const MAX_PATH_LENGTH = 512;
@@ -48,6 +53,8 @@ export declare function buildPayloadV2(i: {
48
53
  proof: TelemetryProof | null;
49
54
  /** The pre-pay index check answered `unknown`: send the plain path for this call. */
50
55
  unknownSeller?: boolean;
56
+ /** Warning codes from the receipt; the field is sent only when there is at least one. */
57
+ warnings?: readonly string[];
51
58
  }): TelemetryPayloadV2;
52
59
  /** Never awaited by callers, never throws, never rejects. Returns the promise only so tests can wait on it. */
53
60
  export declare function sendTelemetry(indexUrl: string, payload: TelemetryPayload | TelemetryPayloadV2, o: {
package/dist/telemetry.js CHANGED
@@ -9,7 +9,7 @@ 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.6.0";
12
+ export const CLIENT_ID = "x402-safe-fetch/0.7.0";
13
13
  /** Sent on every request to the index so it can count calls per client. Carries only CLIENT_ID. */
14
14
  export const CLIENT_HEADER = "X-Paidfor-Client";
15
15
  /** sha256 hex of the URL path with any trailing slash removed. Query string and fragment never enter it. */
@@ -49,6 +49,8 @@ export function buildPayloadV2(i) {
49
49
  if (path)
50
50
  p.path = path;
51
51
  }
52
+ if (i.warnings?.length)
53
+ p.warnings = [...i.warnings];
52
54
  return p;
53
55
  }
54
56
  let failures = 0;
@@ -1,2 +1,16 @@
1
- import type { Validator } from "./types.js";
1
+ import type { Validator, ValidatorResult } from "./types.js";
2
+ /**
3
+ * The format rule (issue 40). A response in another format than the seller declared, whose body is usable, is a
4
+ * warning: status `pass`, `reason` naming it (`content_type_mismatch`, or `missing_content_type` when the header is
5
+ * absent) and `evidence.warning: true`. It stays a failure when the answer has the shape of an error rather than of
6
+ * content: HTML (by header or by its first bytes) where HTML was not declared, an `application/problem+json` document
7
+ * that was not declared, or a body that should be JSON and does not parse. Empty, truncated and non-2xx answers are
8
+ * failed by the other validators.
9
+ */
10
+ export declare const WARNING_REASONS: readonly ["content_type_mismatch", "missing_content_type"];
11
+ export type WarningReason = (typeof WARNING_REASONS)[number];
2
12
  export declare const contentType: Validator;
13
+ /** True for a validator result that passed with a format warning. */
14
+ export declare function isFormatWarning(r: Pick<ValidatorResult, "status" | "reason" | "evidence"> | undefined): r is ValidatorResult & {
15
+ reason: WarningReason;
16
+ };
@@ -1,5 +1,14 @@
1
1
  import { VALIDATORS } from "../taxonomy.js";
2
- import { getHeader, isJsonMediaType, mediaType, parseJsonBody } from "./util.js";
2
+ import { decodeBody, getHeader, isJsonMediaType, mediaType, parseJsonBody } from "./util.js";
3
+ /**
4
+ * The format rule (issue 40). A response in another format than the seller declared, whose body is usable, is a
5
+ * warning: status `pass`, `reason` naming it (`content_type_mismatch`, or `missing_content_type` when the header is
6
+ * absent) and `evidence.warning: true`. It stays a failure when the answer has the shape of an error rather than of
7
+ * content: HTML (by header or by its first bytes) where HTML was not declared, an `application/problem+json` document
8
+ * that was not declared, or a body that should be JSON and does not parse. Empty, truncated and non-2xx answers are
9
+ * failed by the other validators.
10
+ */
11
+ export const WARNING_REASONS = ["content_type_mismatch", "missing_content_type"];
3
12
  function matches(expected, actual) {
4
13
  if (expected === actual || expected === "*/*")
5
14
  return true;
@@ -7,6 +16,28 @@ function matches(expected, actual) {
7
16
  return actual.startsWith(expected.slice(0, -1));
8
17
  return false;
9
18
  }
19
+ const PROBLEM_JSON = "application/problem+json";
20
+ const isHtmlType = (mt) => mt === "text/html" || mt === "application/xhtml+xml";
21
+ /** The expected type admits HTML: HTML itself or a wildcard that covers it. */
22
+ const htmlExpected = (mt) => isHtmlType(mt) || mt === "*/*" || mt === "text/*" || mt === "application/*";
23
+ /** The JSON family as one format: application/json, text/json and +json types, except the error-document type. */
24
+ const jsonFamily = (mt) => isJsonMediaType(mt) && mt !== PROBLEM_JSON;
25
+ /**
26
+ * The body's first 256 characters after the BOM, leading whitespace and any leading HTML comments, lower-cased. An
27
+ * unterminated leading comment reads as HTML: it is markup either way.
28
+ */
29
+ function head(body) {
30
+ let t = decodeBody(body).replace(/^\uFEFF/, "").trimStart();
31
+ while (t.startsWith("<!--")) {
32
+ const end = t.indexOf("-->");
33
+ if (end < 0)
34
+ return "<html";
35
+ t = t.slice(end + 3).trimStart();
36
+ }
37
+ return t.slice(0, 256).toLowerCase();
38
+ }
39
+ const looksHtml = (h) => h.startsWith("<!doctype html") || h.startsWith("<html");
40
+ const looksJson = (h) => h.startsWith("{") || h.startsWith("[");
10
41
  export const contentType = {
11
42
  name: VALIDATORS.CONTENT_TYPE,
12
43
  run(ctx) {
@@ -16,21 +47,49 @@ export const contentType = {
16
47
  const expectedRaw = declared ?? "application/json";
17
48
  const expected = mediaType(expectedRaw);
18
49
  const header = getHeader(ctx.response.headers, "content-type");
19
- if (header === undefined) {
20
- return { status: "fail", reason: "missing_content_type", evidence: { header: null, expected, expected_source } };
50
+ const body = ctx.response.body;
51
+ const h = head(body);
52
+ const bytes = body.length;
53
+ const notJson = (base) => {
54
+ const parsed = parseJsonBody(body);
55
+ return parsed.ok ? null : { status: "fail", reason: "body_not_json", evidence: { ...base, parse_error: parsed.error, bytes } };
56
+ };
57
+ if (header === undefined || mediaType(header) === "") {
58
+ const base = { header: header ?? null, actual: null, expected, expected_source };
59
+ if (!htmlExpected(expected) && looksHtml(h))
60
+ return { status: "fail", reason: "html_body", evidence: { ...base, bytes } };
61
+ if (jsonFamily(expected) && looksJson(h)) {
62
+ const bad = notJson(base);
63
+ if (bad)
64
+ return bad;
65
+ }
66
+ return { status: "pass", reason: "missing_content_type", evidence: { ...base, warning: true, bytes } };
21
67
  }
22
68
  const actual = mediaType(header);
23
69
  const base = { header, actual, expected, expected_source };
24
- if (!matches(expected, actual)) {
25
- return { status: "fail", reason: "content_type_mismatch", evidence: base };
70
+ if (!matches(expected, actual) && !(jsonFamily(expected) && jsonFamily(actual))) {
71
+ if (actual === PROBLEM_JSON)
72
+ return { status: "fail", reason: "content_type_mismatch", evidence: base };
73
+ // An HTML label over a body that parses as JSON is JSON mislabelled, so usable; anything else under it is a page.
74
+ if (isHtmlType(actual) && !htmlExpected(expected) && !(looksJson(h) && parseJsonBody(body).ok)) {
75
+ return { status: "fail", reason: "content_type_mismatch", evidence: base };
76
+ }
77
+ if (!htmlExpected(expected) && looksHtml(h))
78
+ return { status: "fail", reason: "html_body", evidence: { ...base, bytes } };
79
+ if (isJsonMediaType(actual) || (jsonFamily(expected) && looksJson(h))) {
80
+ const bad = notJson(base);
81
+ if (bad)
82
+ return bad;
83
+ }
84
+ return { status: "pass", reason: "content_type_mismatch", evidence: { ...base, warning: true, bytes } };
26
85
  }
27
86
  if (isJsonMediaType(actual)) {
28
- const parsed = parseJsonBody(ctx.response.body);
29
- if (!parsed.ok) {
30
- return { status: "fail", reason: "body_not_json", evidence: { ...base, parse_error: parsed.error, bytes: ctx.response.body.length } };
31
- }
32
- return { status: "pass", evidence: { ...base, json_parsed: true } };
87
+ return notJson(base) ?? { status: "pass", evidence: { ...base, json_parsed: true } };
33
88
  }
34
89
  return { status: "pass", evidence: base };
35
90
  },
36
91
  };
92
+ /** True for a validator result that passed with a format warning. */
93
+ export function isFormatWarning(r) {
94
+ return !!r && r.status === "pass" && r.evidence?.warning === true && WARNING_REASONS.includes(r.reason ?? "");
95
+ }
@@ -4,7 +4,10 @@ export interface ValidatorResult {
4
4
  status: ValidatorStatus;
5
5
  /** Machine-readable evidence; stored verbatim in validator_results.evidence_json. */
6
6
  evidence: Record<string, unknown>;
7
- /** Required when status is "fail" or "skipped". */
7
+ /**
8
+ * Required when status is "fail" or "skipped". On a "pass" it names a warning (`evidence.warning` is true): the
9
+ * content_type validator passes a usable body in another format than declared this way (issue 40).
10
+ */
8
11
  reason?: string;
9
12
  }
10
13
  /** Per-service configuration loaded from config/schemas/<domain>.json. Any section may be absent. */
package/docs/telemetry.md CHANGED
@@ -1,14 +1,17 @@
1
1
  # Telemetry
2
2
 
3
- Telemetry is **off by default**. `telemetry: "anonymous"` sends a v1 row (below). `telemetry: "verified"` sends a
4
- v2 row: the v1 fields plus a proof of payment (see "Version 2"). The report-only adapters send the tx_only row (see
5
- "tx_only (report-only)").
3
+ Telemetry is **on by default** (since 0.7.0; issue
4
+ [sarmadahsan/paidfor-index#41](https://github.com/sarmadahsan/paidfor-index/issues/41)): `safeFetch` sends a v2 row,
5
+ the v1 fields plus a proof of payment (see "Version 2"). Only a team account on a paid plan can turn it off, on its
6
+ account page; the server says so in each `/v1/team/authorize` answer (`telemetry.report: "off"`). `telemetry:
7
+ "anonymous"` and `"off"` are not honoured on their own, and `safeFetch` no longer sends the v1 row (below), which the
8
+ index still accepts from older versions. The report-only adapters send the tx_only row (see "tx_only (report-only)").
6
9
 
7
10
  When it is on, each call that received an HTTP 402 sends one JSON object to `POST {indexUrl}/telemetry`
8
11
  (by default `https://paidfor.dev/v1/telemetry`). That object is the whole message. Nothing else is sent.
9
12
  No account and no key are needed to send it.
10
13
 
11
- ## The exact payload (v1, `"anonymous"`)
14
+ ## The exact payload (v1, `"anonymous"` up to 0.6.0)
12
15
 
13
16
  ```json
14
17
  {
@@ -32,7 +35,7 @@ No account and no key are needed to send it.
32
35
  | `amount_usdc` | Amount of the signed authorization as a 6-decimal string. `"0.000000"` when nothing was signed. |
33
36
  | `latency_ms` | Wall time of the call in milliseconds, rounded. |
34
37
  | `validator_failures` | Names of the validators that failed, for example `["http_status"]`. Names only, no evidence. |
35
- | `client` | `x402-safe-fetch/<version>`, for example `x402-safe-fetch/0.6.0`. |
38
+ | `client` | `x402-safe-fetch/<version>`, for example `x402-safe-fetch/0.7.0`. |
36
39
 
37
40
  ## What is never sent (v1)
38
41
 
@@ -58,9 +61,11 @@ in either version: nothing was paid, and the row would otherwise read as a failu
58
61
  ## The promise
59
62
 
60
63
  This client sends paidfor.dev the outcome of a purchase and nothing that identifies the buyer, the wallet,
61
- or what was bought beyond the seller host and a path hash. The exceptions are opt-in and listed here: v2
62
- (`"verified"`) adds the proof of payment, and from 0.2.1 the plain path for a seller the index has never
63
- measured. If a future version needs to send more, it will list the new fields here and stay opt-in.
64
+ or what was bought beyond the seller host and a path hash. The exceptions are listed here: v2 (`"verified"`) adds
65
+ the proof of payment, and from 0.2.1 the plain path for a seller the index has never measured. Until 0.6.0 this
66
+ promise also said they would stay opt-in; that changed when reporting became the default (above), and the CHANGELOG
67
+ says so at the top. If a future version needs to send more, it will list the new fields here and in the CHANGELOG
68
+ before it sends them.
64
69
 
65
70
  ## Version 2 (`"verified"`)
66
71
 
@@ -107,13 +112,34 @@ Outcomes (`outcome`), mapped like the harness classifier, first match wins:
107
112
  | --- | --- |
108
113
  | `duplicate` | More than one settlement observed for one intent. The client sends one paid request per intent, so in practice it never sees this. |
109
114
  | `error` | The settlement header says `success: false` and the answer was neither 2xx nor 402: the seller rejected the payment (the harness's `not_paid`). Proof is still sent, so the index can confirm nothing moved. A 402 with no settlement, or with `success: false`, is `payment_rejected` on the receipt and sends no row (0.6.0). |
110
- | `non_delivery` | A non-2xx answer after the payment (even with `http_status` turned off), or `non_empty`, `content_type` or `not_truncated` failed. |
115
+ | `non_delivery` | A non-2xx answer after the payment (even with `http_status` turned off), or `non_empty`, `content_type` or `not_truncated` failed. `content_type` fails only on an HTML page or an undeclared `application/problem+json` document where another type was declared, or on JSON that does not parse; usable content in another format is `ok` with a warning (below). |
111
116
  | `wrong_goods` | A schema, entity or freshness validator failed. This client ships none of them, so it does not send this today. |
112
117
  | `overcharge` | Paid more than 1.1x the reference (index listed price, else the last price paid). Only possible if `maxOverListedRatio` was raised. |
113
118
  | `ok` | None of the above. |
114
119
  | `refused_verdict`, `refused_ratio`, `refused_max_per_call`, `no_acceptable_quote` | Refused; nothing was signed. **No `proof`.** A refusal by the `authorize` option (`refused_authorize` on the receipt) sends no row at all. |
115
120
  | `paid_no_response`, `error` | Signed and sent with no response (with `proof`, `tx_hash` null), or failed before signing (no `proof`). |
116
121
 
122
+ ### `warnings` (0.7.0): usable content in another format than declared
123
+
124
+ A paid answer whose content is usable but whose format differs from the one the seller declared in its 402, or that
125
+ has no `Content-Type` header, is `ok`, not `non_delivery`. Its v2 row adds one field, only when there is a warning:
126
+
127
+ ```json
128
+ "outcome": "ok",
129
+ "validator_failures": [],
130
+ "warnings": ["content_type_mismatch"]
131
+ ```
132
+
133
+ | Code | When |
134
+ | --- | --- |
135
+ | `content_type_mismatch` | The response's media type differs from the declared one (or from `application/json` when the seller declared none), and the body is not an HTML page, an undeclared `application/problem+json` document or JSON that fails to parse. Parameters and `+json` suffixes are the same format. |
136
+ | `missing_content_type` | The response had no `Content-Type` header, and the body is usable by the same test. |
137
+
138
+ Codes only: the declared and received types stay in the receipt (`receipt.warnings`), never in the row. A row without
139
+ warnings has no `warnings` field, exactly as before. The index counts these rows as delivered (in the denominator, not
140
+ in the failures) and shows them on the seller's page as their own observation. An index that predates the field answers 400 to a row that carries it (the client sends it to whatever `indexUrl` is set), so this release is published only after paidfor.dev accepts the field. v1
141
+ rows (`"anonymous"` up to 0.6.0; `safeFetch` no longer sends them) carry no warnings: the call is simply `ok`.
142
+
117
143
  ### `path` (0.2.1): only for sellers the index has never measured
118
144
 
119
145
  When the pre-pay `GET {indexUrl}/check` answered and its verdict was `unknown` (the index has no data on the
@@ -128,7 +154,7 @@ the URL path exactly as it was hashed for `path_hash` (no query string, no fragm
128
154
  the host and path of a verified payment to such a seller on its candidate list (`GET {indexUrl}/candidates`) so
129
155
  it can buy the seller itself at its next scheduled run, and drops the path from the stored row once the payment
130
156
  is checked. These are public API endpoints; the index already saw the same origin and path in the pre-pay
131
- lookup. `"anonymous"` (v1) never sends it.
157
+ lookup. A v1 row (`"anonymous"` up to 0.6.0) never carried it.
132
158
 
133
159
  `validator_failed` stays a v1-only outcome. The payer address, amount and pay-to are public on-chain for every
134
160
  settled payment; the v2 row adds the link from that payment to the seller host, path hash, outcome, validator
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@paidfor/x402-safe-fetch",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
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",