@acedatacloud/sdk 2026.418.3 → 2026.420.0

package/README.md

@@ -120,6 +120,49 @@ const client = new AceDataCloud({
 
 The token can also be set via the `ACEDATACLOUD_API_TOKEN` environment variable.
 
+## Paying with X402 Instead of a Bearer Token
+
+The SDK supports a pluggable `paymentHandler` that is invoked when the
+API returns `402 Payment Required`. Combine it with
+[`@acedatacloud/x402-client`](https://github.com/AceDataCloud/X402Client)
+to pay for requests on-chain (Base, Solana, SKALE) instead of using a
+Bearer token:
+
+```bash
+npm install @acedatacloud/sdk @acedatacloud/x402-client
+```
+
+```typescript
+import { AceDataCloud } from '@acedatacloud/sdk';
+import { createX402PaymentHandler } from '@acedatacloud/x402-client';
+
+const client = new AceDataCloud({
+  // No apiToken needed — the x402 handler pays per request.
+  paymentHandler: createX402PaymentHandler({
+    network: 'base',               // or 'solana' | 'skale'
+    evmProvider: window.ethereum,
+    evmAddress: '0xYourAddress...',
+  }),
+});
+
+const result = await client.openai.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Say hi in 3 words' }],
+  max_tokens: 10,
+});
+```
+
+On each API call, the SDK first sends the request unauthenticated. If
+the server replies with `402`, the SDK passes the `accepts` list to
+the handler, which signs and returns an `X-Payment` header. The SDK
+retries the request once with that header. Everything else — task
+polling, streaming, retries, error mapping — keeps working exactly the
+same.
+
+You can still pass a Bearer token alongside the handler if you want a
+mixed mode (some endpoints via subscription, others via x402) — the
+SDK only invokes the handler when it actually sees a `402`.
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,4 +1,92 @@
+/**
+ * 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. */
+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. */
+interface PaymentRequiredBody {
+    x402Version?: number;
+    accepts: PaymentRequirement[];
+    error?: string;
+}
+/** Context passed to a payment handler when a 402 is observed. */
+interface PaymentHandlerContext {
+    url: string;
+    method: string;
+    body?: unknown;
+    accepts: PaymentRequirement[];
+}
+/** Result a payment handler must return. */
+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. */
+type PaymentHandler = (ctx: PaymentHandlerContext) => Promise<PaymentHandlerResult> | PaymentHandlerResult;
+
+/** AceDataCloud SDK errors. */
+declare class AceDataCloudError extends Error {
+    constructor(message: string);
+}
+declare class TransportError extends AceDataCloudError {
+    constructor(message: string);
+}
+declare class APIError extends AceDataCloudError {
+    statusCode: number;
+    code: string;
+    traceId?: string;
+    body: Record<string, unknown>;
+    constructor(opts: {
+        message: string;
+        statusCode: number;
+        code: string;
+        traceId?: string;
+        body?: Record<string, unknown>;
+    });
+}
+declare class AuthenticationError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class TokenMismatchError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class RateLimitError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class ValidationError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class InsufficientBalanceError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class ResourceDisabledError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class ModerationError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class TimeoutError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+
 /** HTTP transport for AceDataCloud SDK. Uses native fetch (Node 18+). */
+
 interface TransportOptions {
     apiToken?: string;
     baseURL?: string;
@@ -6,6 +94,14 @@ 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;
 }
 declare class Transport {
     private baseURL;
@@ -13,6 +109,7 @@ declare class Transport {
     private timeout;
     private maxRetries;
     private headers;
+    private paymentHandler?;
     constructor(opts?: TransportOptions);
     request(method: string, path: string, opts?: {
         json?: Record<string, unknown>;
@@ -273,6 +370,12 @@ interface AceDataCloudOptions {
     timeout?: number;
     maxRetries?: number;
     headers?: Record<string, string>;
+    /**
+     * Optional payment handler invoked when the API returns `402 Payment
+     * Required`. Use `createX402PaymentHandler` from
+     * `@acedatacloud/x402-client` to enable on-chain payments via X402.
+     */
+    paymentHandler?: PaymentHandler;
 }
 declare class AceDataCloud {
     readonly chat: Chat;
@@ -288,49 +391,4 @@ declare class AceDataCloud {
     constructor(opts?: AceDataCloudOptions);
 }
 
-/** AceDataCloud SDK errors. */
-declare class AceDataCloudError extends Error {
-    constructor(message: string);
-}
-declare class TransportError extends AceDataCloudError {
-    constructor(message: string);
-}
-declare class APIError extends AceDataCloudError {
-    statusCode: number;
-    code: string;
-    traceId?: string;
-    body: Record<string, unknown>;
-    constructor(opts: {
-        message: string;
-        statusCode: number;
-        code: string;
-        traceId?: string;
-        body?: Record<string, unknown>;
-    });
-}
-declare class AuthenticationError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class TokenMismatchError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class RateLimitError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class ValidationError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class InsufficientBalanceError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class ResourceDisabledError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class ModerationError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class TimeoutError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-
-export { APIError, AceDataCloud, AceDataCloudError, type AceDataCloudOptions, type AudioProvider, AuthenticationError, type ImageProvider, InsufficientBalanceError, ModerationError, RateLimitError, ResourceDisabledError, TaskHandle, type TaskHandleOptions, TimeoutError, TokenMismatchError, TransportError, ValidationError, type VideoProvider };
+export { APIError, AceDataCloud, AceDataCloudError, type AceDataCloudOptions, type AudioProvider, AuthenticationError, type ImageProvider, InsufficientBalanceError, ModerationError, type PaymentHandler, type PaymentHandlerContext, type PaymentHandlerResult, type PaymentRequiredBody, type PaymentRequirement, RateLimitError, ResourceDisabledError, TaskHandle, type TaskHandleOptions, TimeoutError, TokenMismatchError, TransportError, ValidationError, type VideoProvider };

package/dist/index.d.ts

@@ -1,4 +1,92 @@
+/**
+ * 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. */
+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. */
+interface PaymentRequiredBody {
+    x402Version?: number;
+    accepts: PaymentRequirement[];
+    error?: string;
+}
+/** Context passed to a payment handler when a 402 is observed. */
+interface PaymentHandlerContext {
+    url: string;
+    method: string;
+    body?: unknown;
+    accepts: PaymentRequirement[];
+}
+/** Result a payment handler must return. */
+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. */
+type PaymentHandler = (ctx: PaymentHandlerContext) => Promise<PaymentHandlerResult> | PaymentHandlerResult;
+
+/** AceDataCloud SDK errors. */
+declare class AceDataCloudError extends Error {
+    constructor(message: string);
+}
+declare class TransportError extends AceDataCloudError {
+    constructor(message: string);
+}
+declare class APIError extends AceDataCloudError {
+    statusCode: number;
+    code: string;
+    traceId?: string;
+    body: Record<string, unknown>;
+    constructor(opts: {
+        message: string;
+        statusCode: number;
+        code: string;
+        traceId?: string;
+        body?: Record<string, unknown>;
+    });
+}
+declare class AuthenticationError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class TokenMismatchError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class RateLimitError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class ValidationError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class InsufficientBalanceError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class ResourceDisabledError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class ModerationError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+declare class TimeoutError extends APIError {
+    constructor(opts: ConstructorParameters<typeof APIError>[0]);
+}
+
 /** HTTP transport for AceDataCloud SDK. Uses native fetch (Node 18+). */
+
 interface TransportOptions {
     apiToken?: string;
     baseURL?: string;
@@ -6,6 +94,14 @@ 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;
 }
 declare class Transport {
     private baseURL;
@@ -13,6 +109,7 @@ declare class Transport {
     private timeout;
     private maxRetries;
     private headers;
+    private paymentHandler?;
     constructor(opts?: TransportOptions);
     request(method: string, path: string, opts?: {
         json?: Record<string, unknown>;
@@ -273,6 +370,12 @@ interface AceDataCloudOptions {
     timeout?: number;
     maxRetries?: number;
     headers?: Record<string, string>;
+    /**
+     * Optional payment handler invoked when the API returns `402 Payment
+     * Required`. Use `createX402PaymentHandler` from
+     * `@acedatacloud/x402-client` to enable on-chain payments via X402.
+     */
+    paymentHandler?: PaymentHandler;
 }
 declare class AceDataCloud {
     readonly chat: Chat;
@@ -288,49 +391,4 @@ declare class AceDataCloud {
     constructor(opts?: AceDataCloudOptions);
 }
 
-/** AceDataCloud SDK errors. */
-declare class AceDataCloudError extends Error {
-    constructor(message: string);
-}
-declare class TransportError extends AceDataCloudError {
-    constructor(message: string);
-}
-declare class APIError extends AceDataCloudError {
-    statusCode: number;
-    code: string;
-    traceId?: string;
-    body: Record<string, unknown>;
-    constructor(opts: {
-        message: string;
-        statusCode: number;
-        code: string;
-        traceId?: string;
-        body?: Record<string, unknown>;
-    });
-}
-declare class AuthenticationError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class TokenMismatchError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class RateLimitError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class ValidationError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class InsufficientBalanceError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class ResourceDisabledError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class ModerationError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-declare class TimeoutError extends APIError {
-    constructor(opts: ConstructorParameters<typeof APIError>[0]);
-}
-
-export { APIError, AceDataCloud, AceDataCloudError, type AceDataCloudOptions, type AudioProvider, AuthenticationError, type ImageProvider, InsufficientBalanceError, ModerationError, RateLimitError, ResourceDisabledError, TaskHandle, type TaskHandleOptions, TimeoutError, TokenMismatchError, TransportError, ValidationError, type VideoProvider };
+export { APIError, AceDataCloud, AceDataCloudError, type AceDataCloudOptions, type AudioProvider, AuthenticationError, type ImageProvider, InsufficientBalanceError, ModerationError, type PaymentHandler, type PaymentHandlerContext, type PaymentHandlerResult, type PaymentRequiredBody, type PaymentRequirement, RateLimitError, ResourceDisabledError, TaskHandle, type TaskHandleOptions, TimeoutError, TokenMismatchError, TransportError, ValidationError, type VideoProvider };

package/dist/index.js

@@ -135,10 +135,10 @@ var ERROR_CODE_MAP = {
 };
 var RETRY_STATUS_CODES = /* @__PURE__ */ new Set([408, 409, 429, 500, 502, 503, 504]);
 function mapError(statusCode, body) {
-  const errorData = body.error ?? {};
+  const errorData = body && typeof body === "object" ? body.error ?? {} : {};
   const code = errorData.code ?? "";
   const message = errorData.message ?? "";
-  const traceId = body.trace_id;
+  const traceId = body && typeof body === "object" ? body.trace_id : void 0;
   let ErrorClass = ERROR_CODE_MAP[code];
   if (!ErrorClass) {
     if (statusCode === 403) ErrorClass = ModerationError;
@@ -162,11 +162,12 @@ var Transport = class {
   timeout;
   maxRetries;
   headers;
+  paymentHandler;
   constructor(opts = {}) {
     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"
       });
@@ -175,13 +176,17 @@ var Transport = class {
     this.platformBaseURL = (opts.platformBaseURL ?? "https://platform.acedata.cloud").replace(/\/+$/, "");
     this.timeout = opts.timeout ?? 3e5;
     this.maxRetries = opts.maxRetries ?? 2;
-    this.headers = {
+    this.paymentHandler = opts.paymentHandler;
+    const baseHeaders = {
       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(method, path2, opts = {}) {
     const base = opts.platform ? this.platformBaseURL : this.baseURL;
@@ -193,17 +198,40 @@ var Transport = class {
     const headers = { ...this.headers, ...opts.headers ?? {} };
     const timeoutMs = opts.timeout ?? this.timeout;
     let lastError = null;
+    let paymentAttempted = false;
+    let extraHeaders = {};
     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) : void 0,
           signal: controller.signal
         });
         clearTimeout(timer);
+        if (resp.status === 402 && this.paymentHandler && !paymentAttempted) {
+          const text = await resp.text();
+          let body;
+          try {
+            body = JSON.parse(text);
+          } 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;
@@ -683,7 +711,8 @@ var AceDataCloud = class {
       platformBaseURL: opts.platformBaseURL,
       timeout: opts.timeout,
       maxRetries: opts.maxRetries,
-      headers: opts.headers
+      headers: opts.headers,
+      paymentHandler: opts.paymentHandler
     });
     this.chat = new Chat(this.transport);
     this.images = new Images(this.transport);