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

package/README.md

@@ -324,6 +324,152 @@ 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.
+
+That package is a private repo-local set of reference adapters, not part of the published `@402flow/sdk` package itself.
+
+Current repo-local adapters:
+
+| Adapter | Current scope | Key dependencies |
+| --- | --- | --- |
+| Dexter | Host-owned delegated execution against Dexter's paid request client | `@dexterai/x402` |
+| pay.sh | Host-owned x402 Solana exact delegated execution | `@x402/core`, `@x402/svm`, `@solana/kit` |
+
+The pay.sh adapter intentionally does not depend on `@solana/pay` today. The current proof targets pay.sh's x402 Solana exact flow, so challenge parsing, signed payment payload creation, and paid response parsing come from `@x402/core` plus `@x402/svm`, while `@solana/kit` only supplies the signer. `@solana/pay` becomes relevant when the repo adds a separate Solana Pay or MPP-specific adapter path.
+
+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"}'
+```
+
+For a repo-local host-owned pay.sh x402 example, run:
+
+```bash
+cd third-party-executors
+npm install
+npm run example:pay-sh-delegated-executor -- --help
+```
+
+The pay.sh example expects the standard SDK auth environment plus a local Solana signer path in `PAY_SH_SOLANA_KEYPAIR_PATH`. Run the `--help` form first to see the full required environment and argument contract.
+
 ## Prepared Result Semantics
 
 `preparePaidRequest()` separates request checking from paid execution.
@@ -477,8 +623,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.