@402flow/sdk 0.1.0-alpha.3 → 0.1.0-alpha.30

package/README.md

@@ -1,6 +1,18 @@
 # @402flow/sdk
 
-Node.js SDK for making paid requests through the 402flow control plane.
+Paid API SDK for AI agents, tool hosts, and governed automation.
+
+It gives AI agents, tool hosts, and automation services easy access to paid APIs while organizations keep policy, approvals, receipts, and spend controls outside the agent runtime.
+
+Use `fetchPaid(...)` when the exact request is already known.
+Use `preparePaidRequest(...)` when the agent needs merchant-published hints and an authoritative `nextAction` before paying.
+
+## Why This SDK
+
+- Inspectable paid request flow. Agents and tool hosts can prepare, revise, and execute paid HTTP requests explicitly instead of hiding everything inside one opaque pay-and-fetch call.
+- Control-plane governance. Policy, approvals, receipts, and audit stay centralized instead of being reimplemented in every host.
+- Agent-ready request shaping. `nextAction` gives models and tools a stable contract for revise, execute, or passthrough.
+- Provider-neutral execution. Use the native SDK path or delegate the paid call to Dexter, pay.sh, or a host-owned executor without losing governance value.
 
 ## Install
 
@@ -8,50 +20,133 @@ Node.js SDK for making paid requests through the 402flow control plane.
 npm install @402flow/sdk
 ```
 
-## Usage
+This is the normal install path. Use `@402flow/sdk` by itself when you want the native 402flow payment flow.
+
+Optional official adapters for third-party payers:
+
+```bash
+npm install @402flow/sdk @402flow/sdk-third-party-executors
+```
+
+Install `@402flow/sdk-third-party-executors` only when you want delegated execution through Dexter or pay.sh instead of the native 402flow path.
+
+The published package supports Node 20+.
+
+## Core Surface
+
+| API | Use it when | What it returns |
+| --- | --- | --- |
+| `fetchPaid(...)` | You already know the request shape | Probe the merchant when no challenge is supplied, then authorize, pay, and return the merchant response |
+| `preparePaidRequest(...)` | You want to inspect before paying | Payment terms, parameter hints, validation issues, and an authoritative `nextAction` |
+| `executePreparedRequest(...)` | You already prepared the request | Executes the exact prepared request without re-probing first |
+| `AgentHarness` | Your model host wants a `preparedId` tool contract | The same flow behind a process-local in-memory three-tool surface |
 
-### Runtime Token
+## Quick Start: Host-Controlled Request
+
+This first example shows the deterministic application path. Your code already knows which merchant route and request parameters it wants to send, and the SDK handles probing, policy, payment, and receipts around that request.
 
 ```ts
-import { AgentPayClient } from '@402flow/sdk';
+import {
+  AgentPayClient,
+  createJsonRequestBody,
+} from '@402flow/sdk';
 
 const client = new AgentPayClient({
-	controlPlaneBaseUrl: 'https://402flow.ai',
-	auth: {
-		type: 'runtimeToken',
-		runtimeToken: process.env.AGENT_PAY_RUNTIME_TOKEN ?? '',
-	},
+  controlPlaneBaseUrl:
+    process.env.X402FLOW_CONTROL_PLANE_BASE_URL ?? 'https://api-staging.402flow.ai',
+  organization: process.env.X402FLOW_ORGANIZATION ?? 'acme-labs',
+  agent: process.env.X402FLOW_AGENT ?? 'research-worker',
+  auth: {
+    type: 'bootstrapKey',
+    bootstrapKey: process.env.X402FLOW_BOOTSTRAP_KEY ?? '',
+  },
 });
+
+const result = await client.fetchPaid(
+  'https://demo-merchant-staging.402flow.ai/demo-merchant/research-brief/solana-devnet',
+  {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: createJsonRequestBody({
+      topic: 'sdk integration rollout',
+      audience: 'platform engineers',
+      format: 'bullets',
+    }),
+  },
+  {
+    description: 'generate a staged research brief',
+    idempotencyKey: 'sdk-readme-solana-devnet-brief',
+  },
+);
+
+console.log(await result.response.json());
+console.log(result.receiptId);
 ```
 
-### Bootstrap Key
+This is why the request body is filled in directly in code here. `fetchPaid(...)` is the simplest integration path when your application already knows the parameters.
+
+Important probe semantics: when you do not supply a merchant challenge, both `fetchPaid(...)` and `preparePaidRequest(...)` send the original request to the merchant first to discover whether payment is required. That initial merchant probe happens before any control-plane authorization or payment attempt. For non-idempotent `POST` routes, use this only against endpoints that are explicitly safe to probe or after you already have the merchant challenge from another step.
+
+Use `fetchPaid(...)` when the request is already shaped and you want the shortest path.
+Use `preparePaidRequest(...)` when the caller needs to inspect what the merchant published, construct the right request, and execute only when `nextAction === 'execute'`.
+
+## Quick Start: Agent-Driven Request Construction
+
+If you want the agent to decide which parameters to send, do not hardcode those decisions into the SDK call site. Instead, expose the SDK through `AgentHarness` or your own tool wrapper and let the agent react to `nextAction`, `validationIssues`, and `hints`.
+
+The typical loop is:
+
+1. the agent proposes a request
+2. the SDK returns `nextAction`, `validationIssues`, and merchant-published `hints`
+3. the agent revises the request until `nextAction === 'execute'`
+4. the host executes the prepared request and reads the stored result before summarizing the outcome
+
+That is the path to use when the model is supposed to fill request parameters properly instead of relying on host code that already knows the answer.
+
+## AgentHarness
+
+`AgentHarness` is the optional model-host wrapper for the same inspect-then-execute loop.
+
+It stores process-local in-memory prepared state behind a `preparedId`, exposes a canonical three-tool contract, and keeps the rule that matters most stable across hosts:
+
+`nextAction` is authoritative.
 
 ```ts
-import { AgentPayClient } from '@402flow/sdk';
+import {
+  AgentHarness,
+  defaultHarnessInstructions,
+  defaultHarnessToolSpecs,
+} from '@402flow/sdk';
 
-const client = new AgentPayClient({
-	controlPlaneBaseUrl: 'https://402flow.ai',
-	auth: {
-		type: 'bootstrapKey',
-		bootstrapKey: process.env.AGENT_PAY_BOOTSTRAP_KEY ?? '',
-	},
-});
-```
+const harness = new AgentHarness({ client });
 
-When you configure `bootstrapKey` auth, the SDK exchanges that credential for a runtime token and reuses the runtime token for subsequent control-plane calls until it needs refresh.
+console.log(defaultHarnessInstructions);
+console.log(defaultHarnessToolSpecs.map((spec) => spec.name));
+// [ 'prepare_paid_request', 'execute_prepared_request', 'get_execution_result' ]
+```
 
-## Runtime Requirements
+Use this path when you want the model to construct a correct request instead of guessing its way into a paid call.
 
-Use this SDK from modern Node.js environments with built-in `fetch` support.
+`AgentHarness` is a convenience wrapper for single-process hosts. It is not a durable cross-process orchestration store.
 
-That matters because the SDK uses the Fetch API directly, not only when it calls `fetchPaid()`, but also when it normalizes headers and constructs response objects while mapping control-plane decisions back into SDK results. In practice, the SDK expects `fetch`, `Headers`, and `Response` to be available in the runtime.
+## Governed Third-Party Execution
 
-The current target is modern Node.js with built-in Fetch API support.
+402flow can execute paid x402 requests natively, or you can delegate final payment execution to Dexter, pay.sh, or another executor. Once a payable challenge is already known, 402flow authorizes the paid attempt before execution and finalizes the normalized result afterward, keeping policy, approvals, receipts, and audit centralized.
 
-## Repository Layout
+Official adapters live in `@402flow/sdk-third-party-executors`, and the repo-local source for those adapters lives under `third-party-executors/`. Import the provider-specific subpath you actually use:
 
-This repository is a single-package npm repo. The public consumer surface is the package `@402flow/sdk`.
+```ts
+import { createDexterExecutor } from '@402flow/sdk-third-party-executors/dexter';
+// or:
+import { createPayShExecutor } from '@402flow/sdk-third-party-executors/pay-sh';
+```
 
-## Publish
+## Further Reading
 
-The package is published from the repository root.
+- [Detailed SDK guide](docs/sdk-guide.md)
+- [Evaluation harness](docs/evaluation-harness.md)
+- [Harness scenarios](docs/harness-scenarios.md)
+- [Dexter and pay.sh executors](third-party-executors/README.md)
+- [Publishing and release checks](docs/releasing.md)

package/dist/agent-harness.d.ts

@@ -0,0 +1,164 @@
+/**
+ * AgentHarness provides a small in-memory orchestration layer on top of
+ * AgentPayClient for hosts that prefer preparedId-based handoffs over holding
+ * full prepared request objects.
+ *
+ * The intended host-facing flow is:
+ *
+ * 1. prepare a candidate request and receive a preparedId plus the preparation summary
+ * 2. execute later by preparedId once nextAction is execute
+ * 3. read back the stored execution result by preparedId
+ *
+ * This is useful for tool-driven hosts such as OpenAI tools, MCP servers,
+ * Claude tools, LangGraph nodes, or custom orchestrators where passing a small
+ * opaque id between turns is easier than preserving the full prepared object.
+ *
+ * This file implements only a convenience layer. The core SDK contract remains
+ * AgentPayClient with preparePaidRequest() and executePreparedRequest().
+ *
+ * Important behavior:
+ * - State is kept only in memory inside this process.
+ * - Prepared requests expire after a TTL.
+ * - A newer active preparation for the same method + origin + pathname supersedes
+ *   the older one.
+ * - Execution is rejected locally unless the stored preparation is still active,
+ *   kind === 'ready', and nextAction === 'execute'.
+ */
+import type { PaidRequestChallenge, SdkExternalMetadata, SdkMerchantResponse, SdkPreparedChallengeDetails, SdkPreparedNextAction, SdkPreparedPaidRequest, SdkPreparedPaymentRequirement, SdkPreparedRequestHints, SdkPreparedValidationIssue } from './contracts.js';
+import type { AgentPayClient, ExecutePreparedRequest, FetchPaidFailureResponse, PaidResponse } from './index.js';
+export type AgentHarnessPreparedState = 'active' | 'consumed' | 'expired' | 'superseded';
+/** Local rejection reasons produced by the harness before the SDK is called. */
+export type AgentHarnessRejectionCode = 'missing_prepared_id' | 'unknown_prepared_id' | 'expired_prepared_id' | 'prepared_request_superseded' | 'prepared_request_consumed' | 'prepared_request_not_ready' | 'prepared_request_not_executable';
+/** Typed error used internally to convert local state failures into stable results. */
+export declare class AgentHarnessError extends Error {
+    readonly code: AgentHarnessRejectionCode;
+    readonly preparedId: string | undefined;
+    constructor(code: AgentHarnessRejectionCode, message: string, preparedId?: string);
+}
+/** Host-facing input for the harness prepare step. */
+export type AgentHarnessPrepareInput = {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    externalMetadata?: SdkExternalMetadata;
+};
+/** Host-facing input for the harness execute step. */
+export type AgentHarnessExecuteInput = {
+    preparedId: string;
+    executionContext?: ExecutePreparedRequest;
+};
+/** Exact immutable execution payload stored behind a preparedId. */
+export type AgentHarnessExecutionBinding = {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    bodyHash?: string;
+    challenge?: {
+        protocol: PaidRequestChallenge['protocol'];
+        headers: Record<string, string>;
+        body?: unknown;
+    };
+    merchantOrigin: string;
+};
+/** Summary returned to the host after preparation succeeds. */
+export type AgentHarnessPreparedSummary = {
+    preparedId: string;
+    state: 'active';
+    kind: SdkPreparedPaidRequest['kind'];
+    protocol: SdkPreparedPaidRequest['protocol'];
+    costSummary?: string;
+    challengeDetails?: SdkPreparedChallengeDetails;
+    paymentRequirement?: SdkPreparedPaymentRequirement;
+    hints: SdkPreparedRequestHints;
+    probe?: SdkPreparedPaidRequest['probe'];
+    validationIssues: SdkPreparedValidationIssue[];
+    nextAction: SdkPreparedNextAction;
+    expiresAt: string;
+};
+/** Stored summary for an SDK-backed paid execution outcome. */
+export type AgentHarnessExecutedResult = {
+    preparedId: string;
+    harnessDisposition: 'executed';
+    sdkOutcomeKind: PaidResponse['kind'] | FetchPaidFailureResponse['kind'];
+    status: number;
+    merchantResponse: SdkMerchantResponse;
+    receiptId?: string;
+    paidRequestId?: string;
+    paymentAttemptId?: string;
+    reason?: string;
+    policyReviewEventId?: string;
+};
+/** Stored summary for a harness-local rejection outcome. */
+export type AgentHarnessRejectedResult = {
+    preparedId: string;
+    harnessDisposition: 'rejected';
+    rejectionCode: AgentHarnessRejectionCode;
+    message: string;
+};
+export type AgentHarnessExecutionResult = AgentHarnessExecutedResult | AgentHarnessRejectedResult;
+/** Lookup shape returned when a host asks for the durable result of a preparedId. */
+export type AgentHarnessExecutionLookup = {
+    preparedId: string;
+    state: AgentHarnessPreparedState;
+    supersededByPreparedId?: string;
+    executionResult?: AgentHarnessExecutionResult;
+};
+/** Full internal record shape exposed for debugging and test inspection. */
+export type AgentHarnessPreparedRecord = {
+    preparedId: string;
+    state: AgentHarnessPreparedState;
+    createdAt: string;
+    expiresAt: string;
+    supersededByPreparedId?: string;
+    prepared: SdkPreparedPaidRequest;
+    executionBinding: AgentHarnessExecutionBinding;
+    executionResult?: AgentHarnessExecutionResult;
+};
+/** Minimal client surface AgentHarness needs from the core SDK. */
+export type AgentHarnessClient = Pick<AgentPayClient, 'preparePaidRequest' | 'executePreparedRequest'>;
+/** Configuration for the in-memory wrapper, including TTL and id generation hooks. */
+export type AgentHarnessOptions = {
+    client: AgentHarnessClient;
+    preparedTtlMs?: number;
+    now?: () => Date;
+    createPreparedId?: () => string;
+};
+/**
+ * Optional in-memory preparedId wrapper over AgentPayClient.
+ */
+export declare class AgentHarness {
+    private readonly client;
+    private readonly preparedTtlMs;
+    private readonly now;
+    private readonly createPreparedId;
+    private readonly preparedRecords;
+    constructor(options: AgentHarnessOptions);
+    /**
+     * Prepare a candidate request through the core SDK and store the immutable
+     * prepared result behind a generated preparedId for later execution.
+     */
+    preparePaidRequest(input: AgentHarnessPrepareInput): Promise<AgentHarnessPreparedSummary>;
+    /**
+     * Execute a previously stored ready preparation. Local state failures are
+     * converted into deterministic rejected results rather than thrown to the host.
+     */
+    executePreparedRequest(input: AgentHarnessExecuteInput): Promise<AgentHarnessExecutionResult>;
+    /**
+     * Return the stored in-memory outcome for a preparedId without re-running any
+     * merchant or control-plane call.
+     */
+    getExecutionResult(preparedId: string): AgentHarnessExecutionLookup;
+    /**
+     * Return the full stored record for debugging, tests, or host inspection.
+     */
+    getPreparedRecord(preparedId: string): AgentHarnessPreparedRecord;
+    private runExecution;
+    private createExecutionPromise;
+    private handleExecutionRejection;
+    private getRecordForExecution;
+    private getKnownRecord;
+    private refreshRecordState;
+    private supersedeActiveRecords;
+}