@402flow/sdk 0.1.0-alpha.22 → 0.1.0-alpha.24

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') {
@@ -270,6 +324,131 @@ if (prepared.kind === 'ready') {
 
 If preparation does not return `kind === 'ready'`, that is not necessarily an error. It means this exact request did not currently resolve to a payable executable path. The caller can accept that result, run a normal non-paid path, or revise and prepare again.
 
+### Delegated Execution With Custom Executors
+
+`executePreparedRequest()` now supports governed delegated execution through a caller-supplied executor interface.
+
+This lets the SDK keep authorization, policy, receipts, and final outcome normalization in the 402flow control plane while handing the final paid merchant call to a provider-specific executor owned by the host app or a separate integration package.
+
+The core SDK stays provider-neutral. That means third-party payment clients such as Dexter or pay.sh should live in the host app's own dependency graph, not inside `@402flow/sdk` itself.
+
+The flow is:
+
+1. prepare the exact request locally with `preparePaidRequest()`
+2. ask the control plane to authorize delegated execution
+3. if authorized, let the supplied executor perform the actual paid merchant request
+4. finalize the normalized executor result back through the control plane
+5. return the same stable SDK result or `FetchPaidError` contract the caller already uses elsewhere
+
+If the control plane denies authorization, the delegated executor is never invoked.
+
+```ts
+import {
+  createJsonRequestBody,
+  type PreparedRequestExecutorInput,
+  type PreparedRequestExecutor,
+} from '@402flow/sdk';
+
+async function callDexter(
+  prepared: PreparedRequestExecutorInput['prepared'],
+) {
+  // Replace this with your real Dexter SDK call.
+  return {
+    status: 200,
+    body: { ok: true },
+    settlementReference: 'settlement-ref-1',
+    paymentReference: 'payment-ref-1',
+  };
+}
+
+function mapDexterResult(
+  prepared: PreparedRequestExecutorInput['prepared'],
+  result: Awaited<ReturnType<typeof callDexter>>,
+) {
+  return {
+    protocol: prepared.protocol,
+    executionStatus: 'succeeded' as const,
+    settlementEvidenceClass: 'settled' as const,
+    merchantOutcome: 'success_response' as const,
+    merchantResponse: {
+      status: result.status,
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(result.body),
+    },
+    settlementReference: result.settlementReference,
+    paymentReference: result.paymentReference,
+  };
+}
+
+const dexterExecutor: PreparedRequestExecutor = {
+  provider: 'dexter',
+  async execute({ prepared }) {
+    const dexterResult = await callDexter(prepared);
+    return mapDexterResult(prepared, dexterResult);
+  },
+};
+
+const prepared = await client.preparePaidRequest(
+  'https://merchant.example.com/images/generate',
+  {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: createJsonRequestBody({
+      prompt: 'foggy coastline',
+    }),
+  },
+);
+
+if (prepared.kind === 'ready') {
+  const result = await client.executePreparedRequest(prepared, {
+    description: 'generate image through delegated execution',
+    executionProvider: 'dexter',
+    executor: dexterExecutor,
+  });
+
+  console.log('paid response status:', result.response.status);
+}
+```
+
+This snippet shows the intended split directly: your host-owned code does the provider call and maps it into the delegated execution contract, while the SDK still owns authorize, finalize, and the outward result shape. For a real host-owned Dexter integration that performs the paid call, see `third-party-executors/examples/dexter-delegated-executor.mjs`.
+
+Responsibility split:
+
+1. the SDK asks the control plane for delegated authorization
+2. if authorized, the SDK invokes your executor
+3. your executor performs the provider-specific paid request and returns `SdkDelegatedExecutionResult`
+4. the SDK finalizes that result with the control plane
+5. the SDK returns the same outward `PaidResponse` or `FetchPaidError` contract as the direct path
+
+If your host app wants to execute through Dexter, pay.sh, or another provider, that integration should install and own the third-party SDK directly. `@402flow/sdk` only owns the executor contract and the governed authorize/finalize flow.
+
+The repo keeps third-party executor proofs in the separate `third-party-executors/` package so the main `@402flow/sdk` install path stays provider-neutral.
+
+For a repo-wide verification pass from the SDK root, run:
+
+```bash
+npm run install:all
+npm run check:all
+```
+
+`npm run install:all` installs both the main SDK package and the separate `third-party-executors` package from the SDK root. `npm run check` still validates only the main SDK package. `npm run check:all` runs the main SDK checks first, then runs the separate `third-party-executors` package checks from the top level.
+
+For a repo-local host-owned Dexter example, run:
+
+```bash
+cd third-party-executors
+npm install
+export DEXTER_EVM_PRIVATE_KEY="..."
+
+npm run example:dexter-delegated-executor -- \
+  "https://merchant.example.com/paid-endpoint" \
+  '{"topic":"sdk integration rollout","audience":"platform engineers","format":"bullets"}'
+```
+
 ## Prepared Result Semantics
 
 `preparePaidRequest()` separates request checking from paid execution.
@@ -423,8 +602,10 @@ When unset, first-party fixtures default to the self-hosted demo merchant at `ht
 ## Publish
 
 ```bash
-npm install
-npm run check
+npm run install:all
+npm run check:all
 npm run pack:check
 npm publish --access public
-```
+```
+
+`npm publish` now also runs `npm run check:all` through the root `prepublishOnly` hook, so the repo-wide test pass is enforced before publish even if you skip that step manually.