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

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { type ParsedChallenge } from './challenge-detection.js';
-import { type PaidRequestContext, type PaidRequestTarget, type SdkPaymentDecisionResponse, type SdkReceipt, type SdkReceiptResponse } from './contracts.js';
+import { type DetectedChallenge } from './challenge-detection.js';
+import { type SdkExternalMetadata, type SdkPreparedPaidRequest, type SdkPreparedPaidRequestReady, type PaidRequestContext, type SdkPaymentDecisionResponse, type SdkReceipt, type SdkReceiptResponse } from './contracts.js';
+/** Supported authentication modes for an SDK client. */
 export type AgentPayAuth = {
     type: 'bootstrapKey';
     bootstrapKey: string;
@@ -7,18 +8,34 @@ export type AgentPayAuth = {
     type: 'runtimeToken';
     runtimeToken: string;
 };
+/** Identity bound to a client instance and applied to every paid request. */
+export type AgentPayClientIdentity = Pick<PaidRequestContext, 'organization' | 'agent'>;
+/** Configuration for a client connected to one control plane and one agent identity. */
 export type AgentPayClientOptions = {
     controlPlaneBaseUrl: string;
     auth: AgentPayAuth;
+    organization: string;
+    agent: string;
     fetch?: typeof fetch;
     headers?: Record<string, string>;
 };
+/** Request-scoped options for the fast fetchPaid() path. */
 export type FetchPaidOptions = {
-    target: PaidRequestTarget;
-    challenge?: ParsedChallenge;
+    challenge?: DetectedChallenge;
     idempotencyKey?: string;
 };
-type PaidProtocol = ParsedChallenge['protocol'];
+/** Optional context for the preparation flow. */
+export type PreparePaidRequestOptions = {
+    challenge?: DetectedChallenge;
+    externalMetadata?: SdkExternalMetadata;
+};
+/** Execution context accepted when paying a previously prepared request. */
+export type ExecutePreparedRequest = Omit<FetchPaidRequest, 'challenge'>;
+/** Request-scoped control-plane context accepted by fetchPaid(). */
+export type FetchPaidRequest = Omit<PaidRequestContext, keyof AgentPayClientIdentity> & FetchPaidOptions;
+/** Body types the SDK can safely replay through paid prepare/execute flows. */
+export type ReplayableRequestBody = string | URLSearchParams;
+type PaidProtocol = DetectedChallenge['protocol'];
 type DenyDecision = Extract<SdkPaymentDecisionResponse, {
     outcome: 'deny';
 }>;
@@ -37,14 +54,22 @@ type PreflightFailedDecision = Extract<SdkPaymentDecisionResponse, {
 type PaidFulfillmentFailedDecision = Extract<SdkPaymentDecisionResponse, {
     outcome: 'paid_fulfillment_failed';
 }>;
+type RequestFailedDecision = {
+    outcome: 'request_failed';
+    status: number;
+    message: string;
+    body?: unknown;
+};
 type PaidResponseBase = {
     protocol: PaidProtocol | 'none';
     response: Response;
 };
+/** Returned when the merchant did not require payment for the request. */
 export type PassthroughPaidResponse = PaidResponseBase & {
     kind: 'passthrough';
     protocol: 'none';
 };
+/** Returned when the paid request succeeded and a durable receipt exists. */
 export type SuccessPaidResponse = PaidResponseBase & {
     kind: 'success';
     protocol: PaidProtocol;
@@ -53,6 +78,7 @@ export type SuccessPaidResponse = PaidResponseBase & {
     receiptId: string;
     receipt: SdkReceipt;
 };
+/** Failure result for paid requests that settled but did not fulfill successfully. */
 export type PaidFulfillmentFailedResponse = PaidResponseBase & {
     kind: 'paid_fulfillment_failed';
     protocol: PaidProtocol;
@@ -63,6 +89,7 @@ export type PaidFulfillmentFailedResponse = PaidResponseBase & {
     reason: string;
     decision: PaidFulfillmentFailedDecision;
 };
+/** Failure result for policy denials before paid execution is allowed. */
 export type DeniedPaidResponse = PaidResponseBase & {
     kind: 'denied';
     protocol: PaidProtocol;
@@ -71,6 +98,7 @@ export type DeniedPaidResponse = PaidResponseBase & {
     decision: DenyDecision;
     policyReviewEventId?: string;
 };
+/** Failure result for idempotent retries that are still executing. */
 export type ExecutionPendingPaidResponse = PaidResponseBase & {
     kind: 'execution_pending';
     protocol: PaidProtocol;
@@ -79,6 +107,7 @@ export type ExecutionPendingPaidResponse = PaidResponseBase & {
     reason: string;
     decision: ExecutingDecision;
 };
+/** Failure result when the merchant/control plane could not prove a final outcome. */
 export type ExecutionInconclusivePaidResponse = PaidResponseBase & {
     kind: 'execution_inconclusive';
     protocol: PaidProtocol;
@@ -87,6 +116,7 @@ export type ExecutionInconclusivePaidResponse = PaidResponseBase & {
     reason: string;
     decision: InconclusiveDecision;
 };
+/** Failure result when paid execution started but ended in a hard failure. */
 export type ExecutionFailedPaidResponse = PaidResponseBase & {
     kind: 'execution_failed';
     protocol: PaidProtocol;
@@ -95,6 +125,7 @@ export type ExecutionFailedPaidResponse = PaidResponseBase & {
     reason: string;
     decision: ExecutionFailedDecision;
 };
+/** Failure result when the request could not proceed on the selected payment rail. */
 export type PreflightFailedPaidResponse = PaidResponseBase & {
     kind: 'preflight_failed';
     protocol: PaidProtocol;
@@ -103,16 +134,77 @@ export type PreflightFailedPaidResponse = PaidResponseBase & {
     reason: string;
     decision: PreflightFailedDecision;
 };
-export type PaidResponse = PassthroughPaidResponse | SuccessPaidResponse | PaidFulfillmentFailedResponse | DeniedPaidResponse | ExecutionPendingPaidResponse | ExecutionInconclusivePaidResponse | ExecutionFailedPaidResponse | PreflightFailedPaidResponse;
+/** Failure result when the control-plane response itself could not be trusted as valid SDK output. */
+export type RequestFailedPaidResponse = PaidResponseBase & {
+    kind: 'request_failed';
+    protocol: PaidProtocol;
+    reason: string;
+    decision: RequestFailedDecision;
+};
+export type FetchPaidFailureResponse = PaidFulfillmentFailedResponse | DeniedPaidResponse | ExecutionPendingPaidResponse | ExecutionInconclusivePaidResponse | ExecutionFailedPaidResponse | PreflightFailedPaidResponse | RequestFailedPaidResponse;
+export type PaidResponse = PassthroughPaidResponse | SuccessPaidResponse;
+/**
+ * Thrown for all non-success paid outcomes. The original typed failure payload is
+ * preserved on details so callers can branch on kind without reparsing responses.
+ */
+export declare class FetchPaidError<TResponse extends FetchPaidFailureResponse = FetchPaidFailureResponse> extends Error {
+    readonly details: TResponse;
+    readonly kind: TResponse['kind'];
+    readonly protocol: TResponse['protocol'];
+    readonly response: Response;
+    readonly reason: string;
+    readonly decision: TResponse['decision'];
+    readonly paidRequestId: string | undefined;
+    readonly paymentAttemptId: string | undefined;
+    readonly receiptId: string | undefined;
+    readonly receipt: SdkReceipt | undefined;
+    readonly policyReviewEventId: string | undefined;
+    constructor(details: TResponse);
+}
+/** Type guard for callers that catch unknown errors around fetchPaid flows. */
+export declare function isFetchPaidError(error: unknown): error is FetchPaidError;
+/** Returns true when a request body can be replayed exactly across paid flows. */
+export declare function isReplayableRequestBody(body: RequestInit['body']): body is ReplayableRequestBody;
+/** Serialize a paid-flow request body into the exact replayable wire representation. */
+export declare function toReplayableRequestBody(body: RequestInit['body']): string | undefined;
+/** Helper for callers that want an explicit JSON-string body for paid flows. */
+export declare function createJsonRequestBody(payload: unknown): string;
+type FormUrlEncodedValue = string | number | boolean;
+type FormUrlEncodedBodyInit = Record<string, FormUrlEncodedValue | readonly FormUrlEncodedValue[]>;
+/** Helper for callers that want a replayable form body for paid flows. */
+export declare function createFormUrlEncodedBody(values: FormUrlEncodedBodyInit): URLSearchParams;
+/**
+ * Client bound to one organization/agent identity and one 402flow control plane.
+ *
+ * Most integrations either call fetchPaid() directly or use the explicit
+ * preparePaidRequest() -> executePreparedRequest() flow.
+ */
 export declare class AgentPayClient {
     private readonly controlPlaneBaseUrl;
     private readonly auth;
+    private readonly identity;
     private readonly fetchImpl;
     private readonly headers;
     private cachedRuntimeToken;
     private pendingRuntimeToken;
     constructor(options: AgentPayClientOptions);
-    fetchPaid(input: string, init: RequestInit | undefined, context: PaidRequestContext, options: FetchPaidOptions): Promise<PaidResponse>;
+    /**
+     * Probe or reuse a merchant challenge and return a normalized preparation
+     * result the caller can inspect before paying.
+     */
+    preparePaidRequest(input: string, init?: RequestInit, options?: PreparePaidRequestOptions): Promise<SdkPreparedPaidRequest>;
+    /**
+     * Execute the exact request that was previously prepared, without re-probing
+     * the merchant first.
+     */
+    executePreparedRequest(prepared: SdkPreparedPaidRequestReady, request?: ExecutePreparedRequest): Promise<PaidResponse>;
+    /**
+     * Fast-path helper that probes when needed, asks the control plane for a paid
+     * execution decision, and returns either passthrough or success. All non-success
+     * paid outcomes are thrown as FetchPaidError.
+     */
+    fetchPaid(input: string, init: RequestInit | undefined, request: FetchPaidRequest): Promise<PaidResponse>;
+    /** Lookup a durable receipt by id through the control plane. */
     lookupReceipt(receiptId: string): Promise<SdkReceiptResponse>;
     private createDecisionRequest;
     private requestPaymentDecision;
@@ -122,5 +214,10 @@ export declare class AgentPayClient {
     private requestRuntimeToken;
     private controlPlaneFetch;
 }
+/** Small factory wrapper for callers that prefer a function export. */
 export declare function createAgentPayClient(options: AgentPayClientOptions): AgentPayClient;
-export {};
+export * from './agent-harness.js';
+export * from './contracts.js';
+export * from './harness-instructions.js';
+export { detectChallengeFromResponse, type DetectedChallenge } from './challenge-detection.js';
+export { sdkClientVersion, sdkClientVersionHeaderName } from './version.js';