@acedatacloud/sdk 2026.418.3 → 2026.420.0

package/src/index.ts

@@ -18,6 +18,14 @@ export {
 
 export { TaskHandle, TaskHandleOptions } from './runtime/tasks';
 
+export type {
+  PaymentHandler,
+  PaymentHandlerContext,
+  PaymentHandlerResult,
+  PaymentRequirement,
+  PaymentRequiredBody,
+} from './runtime/payment';
+
 export type { ImageProvider } from './resources/images';
 export type { VideoProvider } from './resources/video';
 export type { AudioProvider } from './resources/audio';

package/src/runtime/index.ts

@@ -1,5 +1,12 @@
 export { Transport, TransportOptions } from './transport';
 export { TaskHandle, TaskHandleOptions } from './tasks';
+export type {
+  PaymentHandler,
+  PaymentHandlerContext,
+  PaymentHandlerResult,
+  PaymentRequirement,
+  PaymentRequiredBody,
+} from './payment';
 export {
   AceDataCloudError,
   APIError,

package/src/runtime/payment.ts

@@ -0,0 +1,48 @@
+/**
+ * Pluggable payment handler hook for the SDK transport.
+ *
+ * When the API returns `402 Payment Required`, the transport calls the
+ * configured `PaymentHandler` to produce the extra headers (typically
+ * `X-Payment`) to attach to the retry. This keeps the SDK free of any
+ * chain-specific signing logic, and lets callers plug in a real x402
+ * implementation such as `@acedatacloud/x402-client`.
+ */
+
+/** Payment requirement as returned by the server in a 402 response. */
+export interface PaymentRequirement {
+  scheme: string;
+  network: string;
+  maxAmountRequired: string;
+  maxTimeoutSeconds?: number;
+  resource?: string;
+  description?: string;
+  payTo: string;
+  asset: string;
+  extra?: Record<string, unknown>;
+}
+
+/** Shape of a 402 response body. */
+export interface PaymentRequiredBody {
+  x402Version?: number;
+  accepts: PaymentRequirement[];
+  error?: string;
+}
+
+/** Context passed to a payment handler when a 402 is observed. */
+export interface PaymentHandlerContext {
+  url: string;
+  method: string;
+  body?: unknown;
+  accepts: PaymentRequirement[];
+}
+
+/** Result a payment handler must return. */
+export interface PaymentHandlerResult {
+  /** Extra headers to attach to the retry (must include `X-Payment`). */
+  headers: Record<string, string>;
+}
+
+/** A callable that signs/settles a payment and returns retry headers. */
+export type PaymentHandler = (
+  ctx: PaymentHandlerContext
+) => Promise<PaymentHandlerResult> | PaymentHandlerResult;

package/src/runtime/transport.ts

@@ -12,6 +12,10 @@ import {
   TransportError,
   ValidationError,
 } from './errors';
+import type {
+  PaymentHandler,
+  PaymentRequiredBody,
+} from './payment';
 
 const ERROR_CODE_MAP: Record<string, typeof APIError> = {
   invalid_token: AuthenticationError,
@@ -26,11 +30,11 @@ const ERROR_CODE_MAP: Record<string, typeof APIError> = {
 
 const RETRY_STATUS_CODES = new Set([408, 409, 429, 500, 502, 503, 504]);
 
-function mapError(statusCode: number, body: Record<string, unknown>): APIError {
-  const errorData = (body.error ?? {}) as Record<string, unknown>;
+export function mapError(statusCode: number, body: any): APIError {
+  const errorData = (body && typeof body === "object" ? (body.error ?? {}) : {}) as Record<string, unknown>;
   const code = (errorData.code ?? '') as string;
   const message = (errorData.message ?? '') as string;
-  const traceId = body.trace_id as string | undefined;
+  const traceId = (body && typeof body === "object" ? body.trace_id : undefined) as string | undefined;
 
   let ErrorClass = ERROR_CODE_MAP[code];
   if (!ErrorClass) {
@@ -60,6 +64,14 @@ export interface TransportOptions {
   timeout?: number;
   maxRetries?: number;
   headers?: Record<string, string>;
+  /**
+   * Optional handler invoked when a request returns `402 Payment Required`.
+   * The handler receives the parsed `accepts` list and must return the extra
+   * headers (typically `X-Payment`) to attach to the automatic retry.
+   *
+   * See `@acedatacloud/x402-client` for a drop-in implementation.
+   */
+  paymentHandler?: PaymentHandler;
 }
 
 export class Transport {
@@ -68,12 +80,15 @@ export class Transport {
   private timeout: number;
   private maxRetries: number;
   private headers: Record<string, string>;
+  private paymentHandler?: PaymentHandler;
 
   constructor(opts: TransportOptions = {}) {
     const token = opts.apiToken ?? process.env.ACEDATACLOUD_API_TOKEN ?? '';
-    if (!token) {
+    if (!token && !opts.paymentHandler) {
       throw new AuthenticationError({
-        message: 'apiToken is required. Pass it to the client or set ACEDATACLOUD_API_TOKEN.',
+        message:
+          'apiToken is required (or provide a paymentHandler, e.g. from @acedatacloud/x402-client). ' +
+          'Pass it to the client or set ACEDATACLOUD_API_TOKEN.',
         statusCode: 0,
         code: 'no_token',
       });
@@ -82,13 +97,17 @@ export class Transport {
     this.platformBaseURL = (opts.platformBaseURL ?? 'https://platform.acedata.cloud').replace(/\/+$/, '');
     this.timeout = opts.timeout ?? 300_000;
     this.maxRetries = opts.maxRetries ?? 2;
-    this.headers = {
+    this.paymentHandler = opts.paymentHandler;
+    const baseHeaders: Record<string, string> = {
       accept: 'application/json',
-      authorization: `Bearer ${token}`,
       'content-type': 'application/json',
       'user-agent': 'acedatacloud-node/0.1.0',
       ...(opts.headers ?? {}),
     };
+    if (token) {
+      baseHeaders.authorization = `Bearer ${token}`;
+    }
+    this.headers = baseHeaders;
   }
 
   async request(
@@ -112,18 +131,42 @@ export class Transport {
     const timeoutMs = opts.timeout ?? this.timeout;
 
     let lastError: Error | null = null;
+    let paymentAttempted = false;
+    let extraHeaders: Record<string, string> = {};
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), timeoutMs);
       try {
         const resp = await fetch(url, {
           method,
-          headers,
+          headers: { ...headers, ...extraHeaders },
           body: opts.json ? JSON.stringify(opts.json) : undefined,
           signal: controller.signal,
         });
         clearTimeout(timer);
 
+        if (resp.status === 402 && this.paymentHandler && !paymentAttempted) {
+          const text = await resp.text();
+          let body: PaymentRequiredBody;
+          try {
+            body = JSON.parse(text) as PaymentRequiredBody;
+          } catch {
+            throw mapError(402, { error: { code: 'invalid_402', message: text } });
+          }
+          if (!body.accepts?.length) {
+            throw mapError(402, { error: { code: 'invalid_402', message: 'No payment requirements' } });
+          }
+          const result = await this.paymentHandler({
+            url,
+            method,
+            body: opts.json,
+            accepts: body.accepts,
+          });
+          extraHeaders = { ...extraHeaders, ...result.headers };
+          paymentAttempted = true;
+          continue;
+        }
+
         if (resp.status >= 400) {
           const text = await resp.text();
           let body: Record<string, unknown>;