@402flow/sdk 0.1.0-alpha.21 → 0.1.0-alpha.23

package/README.md

@@ -132,6 +132,46 @@ If the merchant does not require payment for that exact request, the SDK returns
 
 `result.response` is always the merchant HTTP response. SDK-owned payment metadata such as `paidRequestId`, `paymentAttemptId`, `receiptId`, and `receipt` stays on the SDK result instead of being injected into the merchant JSON body.
 
+### Optional Attribution
+
+Most SDK users do not need to send attribution at all.
+
+The optional `attribution` field is for callers that already know where this paid endpoint came from and want that provenance to survive into control-plane audit, reporting, and later policy analysis.
+
+Common cases:
+
+1. your app found the endpoint through your own registry or catalog
+2. your app imported the endpoint from a saved workspace config
+3. your agent is calling a merchant directly and you want to mark that path as `direct`
+4. your host selected the endpoint from a discovery surface such as Bazaar, Dexter, pay.sh, x402scan, or another catalog
+
+This field does not make payment execution work. It improves lifecycle explainability.
+
+If you do not already know the endpoint provenance, omit it.
+
+```ts
+const result = await client.fetchPaid(
+  'https://merchant.example.com/reports/daily',
+  {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: createJsonRequestBody({
+      date: '2026-03-25',
+    }),
+  },
+  {
+    description: 'sync daily paid report',
+    attribution: {
+      discoverySource: 'direct',
+    },
+  },
+);
+```
+
+For the first attribution slice, `discoverySource` is the main field callers should set when they have a clear answer. The control plane derives an early endpoint-level `resourceIdentity` from the request method and URL, so callers do not need to compute that themselves.
+
 ### Interpreting Merchant Responses
 
 The SDK gives you a stable place for payment metadata, but it does not invent a universal fulfilled-response schema for merchant content.
@@ -228,6 +268,13 @@ const prepared = await client.preparePaidRequest(
 
 `externalMetadata` is optional caller context. It improves preparation when the caller already has structured endpoint knowledge, but it is not required for normal SDK use.
 
+`attribution` is separate from `externalMetadata`.
+
+1. `externalMetadata` helps the SDK understand request shape before execution
+2. `attribution` helps the control plane explain where the paid endpoint came from after execution
+
+Use `externalMetadata` for request hints. Use `attribution` for provenance. Either may be omitted.
+
 ### What `ready` Means
 
 `ready` means this exact request can proceed through governed paid execution as-is; it does not mean the SDK has inferred the best task parameters for you.
@@ -256,6 +303,13 @@ const prepared = await client.preparePaidRequest(
       prompt: 'foggy coastline',
     }),
   },
+
+  const result = await client.executePreparedRequest(prepared, {
+    description: 'generate paid image',
+    attribution: {
+      discoverySource: 'manual',
+    },
+  });
 );
 
 if (prepared.kind === 'ready') {
@@ -308,7 +362,10 @@ Receipt notes:
 1. `receipt.status = 'confirmed'` means the control plane has chain-backed settlement attribution for the paid attempt
 2. `receipt.status = 'provisional'` means the paid outcome was supportable by merchant-provided evidence, but final settlement attribution is still pending reconciliation
 3. callers should treat provisional receipts as payment-attempt evidence, not as proof of final settlement
-4. if you safely retry the same logical paid request with the same `idempotencyKey`, the SDK returns the same durable paid outcome instead of creating a second paid attempt
+4. `idempotencyKey` is optional for normal SDK use, which keeps low-value one-off integrations simple
+5. if you safely retry the same logical paid request with the same `idempotencyKey`, the SDK returns the same durable paid outcome instead of creating a second paid attempt
+6. if you omit `idempotencyKey`, the request still works, but you should not assume replay-safe duplicate suppression across retries
+7. use `idempotencyKey` for retrying callers, automation loops, and higher-load integrations where duplicate suppression matters
 
 ## Receipt Lookup
 
@@ -370,10 +427,10 @@ export X402FLOW_AGENT="reporting-worker"
 export X402FLOW_BOOTSTRAP_KEY="..."
 
 npm run example:openai-tools-quickstart -- \
-  "Prepare and execute a paid POST request to https://nickeljoke.vercel.app/api/joke with JSON body {\"topic\":\"sdk integration\",\"tone\":\"dry\",\"audience\":\"platform engineers\"}"
+  "Prepare and execute a paid POST request to http://127.0.0.1:4123/demo-merchant/research-brief/solana-devnet with JSON body {\"topic\":\"sdk integration rollout\",\"audience\":\"platform engineers\",\"format\":\"bullets\"}"
 ```
 
-Use this when you want the shortest real host integration path. Use the full evaluation harness only when you need scenarios, transcripts, or repeated eval runs.
+Use this when you want the shortest real host integration path. For now, this quickstart defaults to the self-hosted first-party demo merchant in `agent-pay` so SDK adoption starts from the canonical proving ground. Switch the merchant URL to the public AWS demo-merchant host once that deployment is live.
 
 ## Optional `AgentHarness`
 
@@ -392,6 +449,31 @@ For harness usage, presets, transcripts, and scenario packs, see:
 1. [docs/evaluation-harness.md](docs/evaluation-harness.md)
 2. [docs/harness-scenarios.md](docs/harness-scenarios.md)
 
+For the canonical cross-repo core proving sweep (first-party + mock), run:
+
+```bash
+pnpm scenario:core
+```
+
+`pnpm scenario:core` runs first-party + mock in a single pass and keeps one combined artifact set under `tmp/`.
+
+Additional scenario commands:
+
+1. `pnpm scenario:core`: core proving sweep (first-party + mock)
+2. `pnpm scenario:first-party`: first-party self-hosted demo-merchant scenarios only
+3. `pnpm scenario:third-party`: third-party merchant compatibility scenarios only
+4. `pnpm scenario:mock`: fixture-only mock outcomes, no live merchant required
+
+`pnpm scenario:all` now literally runs all scenarios (first-party + third-party + mock).
+
+As the public AWS demo-merchant host comes online, keep these command boundaries and flip first-party scenario fixtures with one env variable:
+
+```bash
+export X402FLOW_FIRST_PARTY_MERCHANT_BASE_URL="https://demo-merchant.402flow.ai"
+```
+
+When unset, first-party fixtures default to the self-hosted demo merchant at `http://127.0.0.1:4123`.
+
 ## Publish
 
 ```bash