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

package/README.md

@@ -1,6 +1,8 @@
 # @402flow/sdk
 
-Node.js SDK for making paid requests through the 402flow control plane.
+Paid HTTP SDK for AI agents with an inspectable prepare/execute flow.
+
+It uses the 402flow control plane as the governance and execution backend, but the main developer surface is a small client for preparing and executing paid HTTP requests.
 
 ## Install
 
@@ -8,50 +10,393 @@ Node.js SDK for making paid requests through the 402flow control plane.
 npm install @402flow/sdk
 ```
 
-## Usage
+The published package supports Node 20+.
+
+## Overview
+
+`@402flow/sdk` is built for AI agents and other callers that need to inspect, prepare, and execute paid HTTP requests without embedding payment-protocol or governance logic in the host.
+
+The SDK has one core client, `AgentPayClient`, and three main calls:
+
+| API | Use when | What it does |
+| --- | --- | --- |
+| `fetchPaid(...)` | You already know the request shape | Probes if needed, resolves payment through the control plane, and returns passthrough or success |
+| `preparePaidRequest(...)` | You want to inspect before paying | Returns normalized payment terms, request hints, validation issues, and `nextAction` |
+| `executePreparedRequest(...)` | You already prepared the request | Executes the exact prepared request without re-probing first |
+
+Use `fetchPaid(...)` for the simplest direct path.
+Use `preparePaidRequest(...)` plus `executePreparedRequest(...)` when the caller needs an explicit inspect, revise, then execute loop.
+
+The package also includes `AgentHarness`, an optional preparedId-based wrapper for tool hosts. That host-facing wrapper adds a human-readable `costSummary` on prepared results and ships canonical `defaultHarnessInstructions` plus `defaultHarnessToolSpecs` exports so adapters can reuse the same orchestration contract.
 
-### Runtime Token
+## Runtime Notes
+
+Two constraints matter early in real integrations:
+
+1. paid prepare and execute flows require replayable request bodies
+2. the current replayable body types are `string` and `URLSearchParams`
+
+That means JSON payloads should be sent as strings, and form-style payloads should be sent as `URLSearchParams`.
+
+The SDK exports small helpers for that:
 
 ```ts
-import { AgentPayClient } from '@402flow/sdk';
+import {
+  createFormUrlEncodedBody,
+  createJsonRequestBody,
+} from '@402flow/sdk';
+
+const jsonBody = createJsonRequestBody({
+  prompt: 'foggy coastline',
+});
+
+const formBody = createFormUrlEncodedBody({
+  prompt: 'foggy coastline',
+  style: 'noir',
+  tags: ['coast', 'mist'],
+});
+```
+
+`FormData`, `Blob`, streams, and framework-specific body wrappers are not currently accepted in paid flows because the SDK has to replay the exact request body through preparation and execution. Convert those upstream into a stable string or `URLSearchParams` first.
+
+## Create A Client
+
+Create one `AgentPayClient` per agent identity. The client binds the 402flow control-plane location and the organization plus agent selectors up front, and each request only carries request-specific context.
+
+### Bootstrap key
+
+For most SDK integrations, bootstrap-key auth is the recommended mode. The SDK exchanges it for a short-lived runtime token, caches that token, and refreshes it automatically before expiry.
+
+```ts
+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: 'https://402flow.ai',
+  organization: 'acme-labs',
+  agent: 'reporting-worker',
+  auth: {
+    type: 'bootstrapKey',
+    bootstrapKey: process.env.X402FLOW_BOOTSTRAP_KEY ?? '',
+  },
 });
 ```
 
-### Bootstrap Key
+### Runtime token
 
 ```ts
 import { AgentPayClient } from '@402flow/sdk';
 
 const client = new AgentPayClient({
-	controlPlaneBaseUrl: 'https://402flow.ai',
-	auth: {
-		type: 'bootstrapKey',
-		bootstrapKey: process.env.AGENT_PAY_BOOTSTRAP_KEY ?? '',
-	},
+  controlPlaneBaseUrl: 'https://402flow.ai',
+  organization: 'acme-labs',
+  agent: 'reporting-worker',
+  auth: {
+    type: 'runtimeToken',
+    runtimeToken: process.env.X402FLOW_RUNTIME_TOKEN ?? '',
+  },
 });
 ```
 
-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.
+## Fast Path: `fetchPaid()`
+
+Call `fetchPaid()` when you already know the merchant URL, method, headers, and body.
+
+```ts
+try {
+  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',
+      idempotencyKey: 'daily-report-2026-03-25',
+    },
+  );
+
+  const merchantBody = await result.response.json();
+  console.log('merchant response body:', merchantBody);
+} catch (error) {
+  console.error('paid request failed', error);
+  throw error;
+}
+```
+
+If the merchant does not require payment for that exact request, the SDK returns a passthrough response. If the merchant returns a payable challenge, the SDK resolves payment through the control plane and returns a durable paid outcome.
+
+`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.
+
+### 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.
+
+In practice:
+
+1. the SDK result carries durable payment metadata such as `receiptId` and `receipt`
+2. `result.response` carries the merchant fulfillment payload
+3. the merchant contract decides where the useful paid content lives inside that payload
+
+If you need request-shape guidance before execution, use `preparePaidRequest()` and inspect:
+
+1. `prepared.hints` for authoritative request fields, examples, notes, and query/body guidance when the challenge publishes them
+2. `prepared.challengeDetails` for raw merchant challenge data such as resource metadata, accepted payment candidates, and extensions like Bazaar discovery metadata
+3. optional caller-supplied `externalMetadata` as advisory context only
+
+If you do not have enough contract information to interpret a merchant response safely, return the raw merchant body and explain what is still missing instead of inventing a payload shape.
+
+## Preparation Flow
+
+Use `preparePaidRequest()` when the caller needs a first-class pre-execution result before paying.
+
+```ts
+import { createJsonRequestBody } from '@402flow/sdk';
+
+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 === 'passthrough') {
+  console.log('merchant did not require payment', prepared.probe?.responseStatus);
+} else {
+  console.log('protocol:', prepared.protocol);
+  console.log('payment requirement:', prepared.paymentRequirement);
+  console.log('request hints:', prepared.hints);
+}
+
+console.log('next action:', prepared.nextAction);
+console.log('validation issues:', prepared.validationIssues);
+```
+
+This flow is useful when:
+
+1. an agent needs request-shape hints before attempting execution
+2. the caller wants normalized payment terms before paying
+3. the caller wants to merge optional `externalMetadata` it already has from another system
+
+The common loop is:
+
+1. prepare the request
+2. inspect `kind`, `paymentRequirement`, `hints`, `validationIssues`, and `nextAction`
+3. revise if needed
+4. execute only once the request is understood
+
+If your system already has endpoint metadata, you can pass it in as optional context:
+
+```ts
+import { createJsonRequestBody } from '@402flow/sdk';
+
+const prepared = await client.preparePaidRequest(
+  'https://merchant.example.com/images/generate',
+  {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: createJsonRequestBody({
+      prompt: 'foggy coastline',
+    }),
+  },
+  {
+    externalMetadata: {
+      requestBodyType: 'json',
+      requestBodyFields: [
+        {
+          name: 'prompt',
+          type: 'string',
+          required: true,
+        },
+      ],
+    },
+  },
+);
+```
+
+`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.
+
+### 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.
+
+That distinction matters:
+
+1. `ready` is about protocol and payment executability
+2. `validationIssues` and `hints` are about request-shape guidance
+3. choosing semantically correct task parameters still belongs to the caller or agent
+
+### Execute A Prepared Request
+
+If preparation returns `kind === 'ready'`, execute that exact prepared request with `executePreparedRequest(prepared, ...)`.
+
+```ts
+import { createJsonRequestBody } from '@402flow/sdk';
+
+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',
+    idempotencyKey: 'image-generate-foggy-coastline',
+  });
+
+  console.log('paid response status:', result.response.status);
+}
+```
+
+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.
 
-## Runtime Requirements
+## Prepared Result Semantics
 
-Use this SDK from modern Node.js environments with built-in `fetch` support.
+`preparePaidRequest()` separates request checking from paid execution.
 
-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.
+The preparation result distinguishes four important things:
 
-The current target is modern Node.js with built-in Fetch API support.
+1. `paymentRequirement`: normalized payment terms derived from the merchant challenge when available
+2. `hints`: request-shape hints such as body fields, query params, path params, descriptions, examples, and notes
+3. `validationIssues`: structured remediation diagnostics derived from the current request and defensible preparation inputs
+4. `nextAction`: the authoritative machine contract for what to do next, such as `execute`, `revise_request`, or `treat_as_passthrough`
+
+Each prepared hint carries `attribution` so callers can distinguish live merchant-authoritative data from advisory caller-supplied metadata.
+
+In this model, payment terms come from the merchant challenge, optional request-shape enrichment comes from `externalMetadata`, and live confirmation is represented by the prepared `probe` result.
+
+## Result And Error Semantics
+
+`fetchPaid()` and `executePreparedRequest()` either:
+
+1. return a passthrough response when the request did not require payment
+2. return `success` with a receipt when the paid request completed successfully
+3. throw `FetchPaidError` for all non-success paid outcomes
+
+`FetchPaidError` kinds are:
+
+1. `denied`
+2. `preflight_failed`
+3. `execution_pending`
+4. `execution_failed`
+5. `paid_fulfillment_failed`
+6. `execution_inconclusive`
+7. `request_failed`
+
+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
+
+## Receipt Lookup
+
+```ts
+const receipt = await client.lookupReceipt('receipt-id');
+
+console.log(receipt.receipt.status);
+```
 
-## Repository Layout
+## Canonical Host Metadata
 
-This repository is a single-package npm repo. The public consumer surface is the package `@402flow/sdk`.
+If you are building a tool host, do not copy orchestration rules into ad hoc prompts. Import the canonical host-agnostic metadata from the SDK and adapt it to your model provider.
+
+```ts
+import {
+  defaultHarnessInstructions,
+  defaultHarnessToolSpecs,
+} from '@402flow/sdk';
+
+console.log(defaultHarnessInstructions);
+console.log(defaultHarnessToolSpecs);
+```
+
+`defaultHarnessToolSpecs` defines the canonical three-tool contract:
+
+1. `prepare_paid_request`
+2. `execute_prepared_request`
+3. `get_execution_result`
+
+Those descriptions encode the orchestration rules, including:
+
+1. `nextAction` is authoritative
+2. execute only after `nextAction === 'execute'`
+3. read the stored execution result before summarizing the outcome
+
+Keep provider-specific tool objects in your host adapter, not in the SDK core package.
+
+## Tiny OpenAI Tools Host
+
+If you want a minimal real host integration instead of the larger evaluation harness, use the tiny OpenAI Responses example in `examples/openai-tools-quickstart.mjs`.
+
+For repo-local example runs, create `.env` from `.env.example` in the SDK root. The SDK examples load that file directly, so scenario runs stay self-contained in this repo whether they point at a local control plane or a hosted environment.
+
+It keeps the host story narrow:
+
+1. create an `AgentPayClient`
+2. wrap it with optional `AgentHarness` so tool calls can pass `preparedId`
+3. build provider-specific tool objects from `defaultHarnessToolSpecs`
+4. expose `prepare_paid_request`, `execute_prepared_request`, and `get_execution_result`
+
+Run it with one prompt. Either populate `.env` from `.env.example`, or export the same values in your shell for a one-off run:
+
+```bash
+cp .env.example .env
+export OPENAI_API_KEY="..."
+export X402FLOW_CONTROL_PLANE_BASE_URL="https://402flow.ai"
+export X402FLOW_ORGANIZATION="acme-labs"
+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\"}"
+```
+
+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.
+
+## Optional `AgentHarness`
+
+`AgentHarness` is an optional preparedId-based wrapper for tool hosts that do not want to manage in-flight prepared request objects themselves. It is a convenience layer on top of `AgentPayClient`, not a required abstraction.
+
+Key behavior:
+
+1. preparations are stored in memory behind a `preparedId`
+2. a newer active preparation for the same method plus origin plus pathname supersedes the older one
+3. duplicate execute calls for the same consumed `preparedId` are rejected locally as already consumed
+4. hosts should call `getExecutionResult(preparedId)` after execution to read the durable stored outcome
+5. host-facing prepare results include `costSummary`, for example `Costs 0.001000 USDC on Base Sepolia (exact).`
+
+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)
 
 ## Publish
 
-The package is published from the repository root.
+```bash
+npm install
+npm run check
+npm run pack:check
+npm publish --access public
+```

package/dist/agent-harness.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 durable stored 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 handleExecutionRejection;
+    private getRecordForExecution;
+    private getKnownRecord;
+    private refreshRecordState;
+    private supersedeActiveRecords;
+}