@paidfor/x402-safe-fetch 0.5.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 +84 -0
- package/README.md +138 -39
- package/dist/index.d.ts +4 -2
- package/dist/index.js +3 -1
- package/dist/intents.d.ts +19 -1
- package/dist/intents.js +7 -0
- package/dist/proof.js +2 -1
- package/dist/receipt.d.ts +28 -2
- package/dist/receipt.js +20 -0
- package/dist/safe-fetch.d.ts +27 -5
- package/dist/safe-fetch.js +240 -36
- package/dist/team.d.ts +38 -0
- package/dist/team.js +47 -2
- 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 +45 -17
- package/package.json +1 -1
package/dist/team.js
CHANGED
|
@@ -17,10 +17,25 @@ import { join } from "node:path";
|
|
|
17
17
|
export const TEAM_ORIGIN = "https://paidfor.dev";
|
|
18
18
|
export const AUTHORIZE_TIMEOUT_MS = 10_000;
|
|
19
19
|
export const REPORT_TIMEOUT_MS = 5_000;
|
|
20
|
+
/** How long a refusal notice may take. Never awaited by a payment. */
|
|
21
|
+
export const REFUSAL_TIMEOUT_MS = 2_000;
|
|
20
22
|
/** The words the server takes for a paid outcome. */
|
|
21
23
|
const PAID_OUTCOMES = ["ok", "non_delivery", "wrong_goods", "overcharge", "duplicate", "paid_no_response"];
|
|
22
24
|
/** Shown when the team does not know the wallet. */
|
|
23
|
-
const MCP_INIT = "npx -y @paidfor/mcp@
|
|
25
|
+
const MCP_INIT = "npx -y @paidfor/mcp@latest init --wallet --link";
|
|
26
|
+
/**
|
|
27
|
+
* The server's rule for a project tag (paidfor lib/team/project.ts): trimmed, then 1 to 64 letters, digits, spaces or
|
|
28
|
+
* . _ -. A tag the server would refuse is refused here, when the client is made, instead of on every payment.
|
|
29
|
+
*/
|
|
30
|
+
const PROJECT_RE = /^[A-Za-z0-9._ -]{1,64}$/;
|
|
31
|
+
export const PROJECT_RULE = 'a project tag is 1 to 64 letters, digits, spaces or . _ - (for example "research-q4")';
|
|
32
|
+
/** The tag made canonical (trimmed), or null when the server would refuse it. */
|
|
33
|
+
export function cleanProject(v) {
|
|
34
|
+
if (typeof v !== "string")
|
|
35
|
+
return null;
|
|
36
|
+
const t = v.trim();
|
|
37
|
+
return PROJECT_RE.test(t) ? t : null;
|
|
38
|
+
}
|
|
24
39
|
/** What to report for a payment that was approved, from its receipt. */
|
|
25
40
|
export function outcomeFor(r, wallet, authRef) {
|
|
26
41
|
const base = { wallet, intent_id: r.intent_id, auth_ref: authRef };
|
|
@@ -54,7 +69,9 @@ function extras(d) {
|
|
|
54
69
|
})
|
|
55
70
|
: [];
|
|
56
71
|
const usage = d.usage && typeof d.usage === "object" && !Array.isArray(d.usage) ? d.usage : undefined;
|
|
57
|
-
|
|
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 } : {}) };
|
|
58
75
|
}
|
|
59
76
|
function failedStatus(status, body, wallet, origin) {
|
|
60
77
|
const said = body && typeof body === "object" && str(body.error) ? ` ${body.error.slice(0, 300)}` : "";
|
|
@@ -116,6 +133,8 @@ export class TeamClient {
|
|
|
116
133
|
/** Reports that could not be written to disk; sent again like the disk queue, lost if the process ends. */
|
|
117
134
|
memory = new Map();
|
|
118
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;
|
|
119
138
|
constructor(o) {
|
|
120
139
|
if (typeof o.key !== "string" || !o.key.trim() || /\s/.test(o.key.trim()))
|
|
121
140
|
throw new TypeError("team: key must be a non-empty team key with no spaces");
|
|
@@ -144,6 +163,19 @@ export class TeamClient {
|
|
|
144
163
|
}
|
|
145
164
|
/** Never throws: anything but a 200 with a readable decision is { kind: "failed" }. */
|
|
146
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) {
|
|
147
179
|
let res;
|
|
148
180
|
try {
|
|
149
181
|
res = await this.post("/v1/team/authorize", body, this.authorizeTimeoutMs);
|
|
@@ -160,6 +192,19 @@ export class TeamClient {
|
|
|
160
192
|
}
|
|
161
193
|
return res.status === 200 ? readDecision(parsed) : failedStatus(res.status, parsed, body.wallet, this.origin);
|
|
162
194
|
}
|
|
195
|
+
/**
|
|
196
|
+
* Tell the team about a payment this client refused before asking it, so the ledger and the bill can count what was
|
|
197
|
+
* saved. Fire-and-forget: one try, a 2 s timeout, every failure (a 404 from a server without the route included)
|
|
198
|
+
* swallowed and never logged. Never throws or rejects; the promise is returned only so tests can wait on it.
|
|
199
|
+
*/
|
|
200
|
+
reportRefusal(body) {
|
|
201
|
+
try {
|
|
202
|
+
return this.post("/v1/team/refusals", body, REFUSAL_TIMEOUT_MS).then((res) => void res.body?.cancel().catch(() => undefined), () => undefined).catch(() => undefined);
|
|
203
|
+
}
|
|
204
|
+
catch {
|
|
205
|
+
return Promise.resolve();
|
|
206
|
+
}
|
|
207
|
+
}
|
|
163
208
|
/** One try. "retry" means the server could not take it now; a 4xx will never be taken, so it is not kept. */
|
|
164
209
|
async send(body) {
|
|
165
210
|
try {
|
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
|
{
|
|
@@ -19,7 +22,7 @@ No account and no key are needed to send it.
|
|
|
19
22
|
"amount_usdc": "0.010000",
|
|
20
23
|
"latency_ms": 412,
|
|
21
24
|
"validator_failures": [],
|
|
22
|
-
"client": "x402-safe-fetch
|
|
25
|
+
"client": "x402-safe-fetch/<version>"
|
|
23
26
|
}
|
|
24
27
|
```
|
|
25
28
|
|
|
@@ -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>`, `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
|
|
|
@@ -42,7 +45,9 @@ No account and no key are needed to send it.
|
|
|
42
45
|
- The `intentId`, the request hash, or anything that links two calls together.
|
|
43
46
|
- Validator evidence, error messages, or seller response text.
|
|
44
47
|
|
|
45
|
-
Calls to free resources (no 402) and replays of a stored intent send nothing.
|
|
48
|
+
Calls to free resources (no 402) and replays of a stored intent send nothing. Nor does a payment the seller
|
|
49
|
+
rejected (receipt outcome `payment_rejected`, from 0.6.0: the paid request answered 402 again and nothing settled),
|
|
50
|
+
in either version: nothing was paid, and the row would otherwise read as a failure of the seller.
|
|
46
51
|
|
|
47
52
|
## How it is sent
|
|
48
53
|
|
|
@@ -56,9 +61,11 @@ Calls to free resources (no 402) and replays of a stored intent send nothing.
|
|
|
56
61
|
## The promise
|
|
57
62
|
|
|
58
63
|
This client sends paidfor.dev the outcome of a purchase and nothing that identifies the buyer, the wallet,
|
|
59
|
-
or what was bought beyond the seller host and a path hash. The exceptions are
|
|
60
|
-
|
|
61
|
-
|
|
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.
|
|
62
69
|
|
|
63
70
|
## Version 2 (`"verified"`)
|
|
64
71
|
|
|
@@ -74,7 +81,7 @@ Additive over v1. `v` is `2`, `outcome` uses the harness names, `validator_failu
|
|
|
74
81
|
"amount_usdc": "0.002000",
|
|
75
82
|
"latency_ms": 1840,
|
|
76
83
|
"validator_failures": ["http_status:500"],
|
|
77
|
-
"client": "x402-safe-fetch
|
|
84
|
+
"client": "x402-safe-fetch/<version>",
|
|
78
85
|
"proof": {
|
|
79
86
|
"network": "eip155:8453",
|
|
80
87
|
"scheme": "exact",
|
|
@@ -104,14 +111,35 @@ Outcomes (`outcome`), mapped like the harness classifier, first match wins:
|
|
|
104
111
|
| v2 outcome | When |
|
|
105
112
|
| --- | --- |
|
|
106
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. |
|
|
107
|
-
| `error` | The settlement header says `success: false` and the answer was
|
|
108
|
-
| `non_delivery` | A non-2xx answer after the payment (even with `http_status` turned off), or `non_empty`, `content_type` or `not_truncated` failed. |
|
|
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). |
|
|
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). |
|
|
109
116
|
| `wrong_goods` | A schema, entity or freshness validator failed. This client ships none of them, so it does not send this today. |
|
|
110
117
|
| `overcharge` | Paid more than 1.1x the reference (index listed price, else the last price paid). Only possible if `maxOverListedRatio` was raised. |
|
|
111
118
|
| `ok` | None of the above. |
|
|
112
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. |
|
|
113
120
|
| `paid_no_response`, `error` | Signed and sent with no response (with `proof`, `tx_hash` null), or failed before signing (no `proof`). |
|
|
114
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
|
+
|
|
115
143
|
### `path` (0.2.1): only for sellers the index has never measured
|
|
116
144
|
|
|
117
145
|
When the pre-pay `GET {indexUrl}/check` answered and its verdict was `unknown` (the index has no data on the
|
|
@@ -126,14 +154,14 @@ the URL path exactly as it was hashed for `path_hash` (no query string, no fragm
|
|
|
126
154
|
the host and path of a verified payment to such a seller on its candidate list (`GET {indexUrl}/candidates`) so
|
|
127
155
|
it can buy the seller itself at its next scheduled run, and drops the path from the stored row once the payment
|
|
128
156
|
is checked. These are public API endpoints; the index already saw the same origin and path in the pre-pay
|
|
129
|
-
lookup. `"anonymous"`
|
|
157
|
+
lookup. A v1 row (`"anonymous"` up to 0.6.0) never carried it.
|
|
130
158
|
|
|
131
159
|
`validator_failed` stays a v1-only outcome. The payer address, amount and pay-to are public on-chain for every
|
|
132
160
|
settled payment; the v2 row adds the link from that payment to the seller host, path hash, outcome, validator
|
|
133
161
|
failures and response hash. Bodies, request parameters, headers, the intent id and validator evidence are never
|
|
134
162
|
sent in either version. `"verified"` requires an https `indexUrl` (loopback excepted), and no telemetry request
|
|
135
163
|
follows a redirect. Each receipt stores the same `proof` and, in `"verified"` mode,
|
|
136
|
-
`verification_url` = `{indexUrl}/telemetry/<payer>/<nonce
|
|
164
|
+
`verification_url` = `{indexUrl}/telemetry/<payer>/<nonce>`, which shows whether the index verified the row.
|
|
137
165
|
|
|
138
166
|
## tx_only (report-only)
|
|
139
167
|
|
|
@@ -151,7 +179,7 @@ Base settlement header, one object goes to `POST {indexUrl}/telemetry` (default
|
|
|
151
179
|
"outcome": "ok",
|
|
152
180
|
"latency_ms": 412,
|
|
153
181
|
"validator_failures": [],
|
|
154
|
-
"client": "x402-safe-fetch
|
|
182
|
+
"client": "x402-safe-fetch/<version>",
|
|
155
183
|
"proof": { "network": "eip155:8453", "tx_hash": "0x<settlement transaction hash>" }
|
|
156
184
|
}
|
|
157
185
|
```
|
|
@@ -168,7 +196,7 @@ Base settlement header, one object goes to `POST {indexUrl}/telemetry` (default
|
|
|
168
196
|
No payer, pay-to, nonce, amount or signature is sent: the index reads the payer, the recipient and the amount from the
|
|
169
197
|
transaction on Base, and the report counts only once that transaction is a USDC transfer to the seller. The index
|
|
170
198
|
answers `verified`, `pending` or a 422 with the reason; one transaction is one row across every channel. The request
|
|
171
|
-
carries `X-Paidfor-Client: x402-safe-fetch
|
|
199
|
+
carries `X-Paidfor-Client: x402-safe-fetch/<version>`, waits up to 10 seconds (the index checks the chain before
|
|
172
200
|
answering), never follows a redirect, and needs an https `indexUrl` (loopback excepted). Failures are counted in
|
|
173
201
|
`<receiptsDir>/debug.log` when you pass a `receiptsDir`, otherwise nowhere. The same row is what the paidfor MCP tool
|
|
174
202
|
`report_x402_payment` and the paidfor skill send.
|
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",
|