@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 +45 -0
- package/README.md +68 -31
- package/dist/index.d.ts +3 -1
- package/dist/index.js +2 -0
- package/dist/receipt.d.ts +18 -0
- package/dist/receipt.js +20 -0
- package/dist/safe-fetch.d.ts +12 -3
- package/dist/safe-fetch.js +79 -21
- package/dist/team.d.ts +13 -0
- package/dist/team.js +18 -1
- package/dist/telemetry.d.ts +8 -1
- package/dist/telemetry.js +3 -1
- package/dist/validators/content_type.d.ts +15 -1
- package/dist/validators/content_type.js +69 -10
- package/dist/validators/types.d.ts +4 -1
- package/docs/telemetry.md +36 -10
- package/package.json +1 -1
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
130
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
|
144
|
-
|
|
|
145
|
-
|
|
|
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
|
|
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
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
197
|
-
|
|
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.
|
|
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.
|
|
205
|
-
|
|
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.**
|
|
221
|
-
|
|
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
|
|
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`;
|
package/dist/safe-fetch.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
20
|
-
*
|
|
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
|
|
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;
|
package/dist/safe-fetch.js
CHANGED
|
@@ -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,
|
|
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
|
-
|
|
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
|
-
|
|
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 (
|
|
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 =
|
|
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
|
-
|
|
220
|
-
'
|
|
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 (
|
|
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 =
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
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 &&
|
|
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
|
-
|
|
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);
|
package/dist/telemetry.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { TelemetryOutcome, TelemetryProof } from "./proof.js";
|
|
2
|
-
export declare const CLIENT_ID = "x402-safe-fetch/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.
|
|
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
|
-
|
|
20
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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 **
|
|
4
|
-
|
|
5
|
-
|
|
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.
|
|
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
|
|
62
|
-
|
|
63
|
-
|
|
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"`
|
|
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.
|
|
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",
|