test-gstable-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,737 @@
+/**
+ * Default private API origin for this SDK (see `GStableHttpOptions.baseUrl` to override).
+ * Trailing slashes are normalized when building request URLs.
+ */
+declare const DEFAULT_BASE_URL = "https://api.gstable.io/api/v1/";
+/**
+ * Default public API origin (no `Authorization`; see `GStableHttpOptions.publicBaseUrl`).
+ */
+declare const DEFAULT_PUBLIC_BASE_URL = "https://api.gstable.io/public/api/v1";
+type HttpMethod = 'GET' | 'POST';
+interface GStableHttpOptions {
+    /** API Key，无需带 `Bearer ` 前缀 */
+    apiKey: string;
+    /** 未设置时使用 {@link DEFAULT_BASE_URL} */
+    baseUrl?: string;
+    /** 公共 API 根路径，未设置时使用 {@link DEFAULT_PUBLIC_BASE_URL} */
+    publicBaseUrl?: string;
+    /** 可注入 fetch（测试或自定义环境） */
+    fetchImpl?: typeof fetch;
+}
+declare class GStableHttp {
+    private readonly baseUrl;
+    private readonly publicBaseUrl;
+    private readonly authHeader;
+    private readonly fetchFn;
+    constructor(options: GStableHttpOptions);
+    private extractEnvelopeData;
+    /**
+     * 调用公共 API（不携带 Authorization），响应格式与私有 API 相同。
+     */
+    requestPublicJson<T>(method: HttpMethod, path: string, body?: unknown): Promise<T>;
+    requestJson<T>(method: HttpMethod, path: string, body?: unknown): Promise<T>;
+}
+
+/** 账户类型（文档当前仅支持 EVM 地址） */
+type AccountType = 'EVM::ADDR';
+/** 账户状态 */
+type AccountStatus = 'normal';
+/**
+ * 收款账户对象（文档字段）
+ * @see https://docs.gstable.io/zh-Hans/docs/api/core-api/account
+ */
+interface Account {
+    accountId: string;
+    accountName: string;
+    accountAddress: string;
+    accountType: AccountType;
+    settlementCurrencies: string[];
+    version: string;
+    status: AccountStatus;
+    createAt?: string;
+    updateAt?: string;
+}
+
+/**
+ * 账户模块 API（只读；创建/修改须在 Dashboard 完成）
+ * @see https://docs.gstable.io/zh-Hans/docs/api/core-api/account
+ */
+declare class AccountResource {
+    private readonly http;
+    constructor(http: GStableHttp);
+    /** GET /account/detail/:accountId */
+    detail(accountId: string): Promise<Account>;
+    /** GET /account/list — 全量返回，无分页（单商户最多 20 个账户） */
+    list(): Promise<Account[]>;
+}
+
+/**
+ * 支持的结算/支付代币条目
+ * @see https://docs.gstable.io/zh-Hans/docs/api/overview/supported-assets#%E6%9F%A5%E8%AF%A2%E8%83%BD%E5%8A%9B-api
+ */
+interface SupportedToken {
+    tokenId: string;
+    symbol: string;
+    chainId: string;
+    decimals: number;
+}
+/** 单条支付路径（费率与限额） */
+interface PaymentCapabilityRoute {
+    tokenId: string;
+    crosschain: boolean;
+    feeRatePPM: number;
+    minPaymentValue: number;
+    maxPaymentValue: number;
+}
+/**
+ * 支付能力矩阵：结算 tokenId -> 路由分组键（如 POL、ARB、ETH）-> 可选支付路径
+ */
+type PaymentCapabilitiesMatrix = Record<string, Record<string, PaymentCapabilityRoute[]>>;
+/** GET /capabilities/all 返回的 data */
+interface PaymentCapabilities {
+    supportedTokens: SupportedToken[];
+    paymentCapabilities: PaymentCapabilitiesMatrix;
+}
+
+/**
+ * 公共「支付能力」查询（无需鉴权，使用 public Base URL）
+ * @see https://docs.gstable.io/zh-Hans/docs/api/overview/supported-assets#%E6%9F%A5%E8%AF%A2%E8%83%BD%E5%8A%9B-api
+ */
+declare class CapabilityResource {
+    private readonly http;
+    constructor(http: GStableHttp);
+    /** GET /capabilities/all */
+    all(): Promise<PaymentCapabilities>;
+}
+
+/** 商品状态 */
+type ProductStatus = 'active' | 'archived';
+/** 自定义属性（如尺码、颜色） */
+interface ProductAttribute {
+    name: string;
+    value: string;
+}
+/** 商品对象（文档字段） */
+interface Product {
+    productId: string;
+    name: string;
+    description?: string;
+    imageUrl?: string;
+    status: ProductStatus;
+    /** Micro-USD，如 1000000 = $1.00 */
+    commonPrices: number[];
+    attributes?: ProductAttribute[];
+    /** 列表接口可能返回 */
+    createAt?: string;
+}
+/** POST /product/create */
+interface CreateProductBody {
+    name: string;
+    commonPrices: number[];
+    description?: string;
+    imageUrl?: string;
+    attributes?: ProductAttribute[];
+}
+/** POST /product/update（全量替换） */
+interface UpdateProductBody {
+    productId: string;
+    name: string;
+    description?: string;
+    imageUrl?: string;
+    attributes?: ProductAttribute[];
+    commonPrices: number[];
+}
+/** GET /product/list/:page/:size */
+interface ProductListData {
+    total: number;
+    page: string;
+    size: string;
+    products: Product[];
+}
+/** POST /product/list/by/ids */
+interface ProductListByIdsBody {
+    productIds: string[];
+}
+/** 仅含 success 的 data */
+interface OperationSuccess {
+    success: boolean;
+}
+
+/** 链接类型：固定金额 / 自定义金额（捐赠等） */
+type PaymentLinkType = 'fixed' | 'custom';
+/** 手续费模型：1 收款方承担，2 付款方承担 */
+type PaymentLinkFeeModel = 1 | 2;
+/** 链接状态（文档示例含 active） */
+type PaymentLinkStatus = 'active' | string;
+/** 请求体中的行项目 */
+type PaymentLinkLineItemInput = {
+    itemType: 'product';
+    productId: string;
+    quantity: number;
+    /** Micro 单位，须 > 0 */
+    unitPrice: number;
+} | {
+    itemType: 'user_priced';
+    productId: string;
+    quantity: number;
+    /** 可不传或 0 */
+    unitPrice?: number;
+};
+/** POST /payment/link/create */
+interface CreatePaymentLinkBody {
+    linkType: PaymentLinkType;
+    linkName: string;
+    accountId: string;
+    settlementToken: string;
+    feeModel: PaymentLinkFeeModel;
+    lineItems: PaymentLinkLineItemInput[];
+    /** 1 需要邮箱，0 不需要 */
+    payerEmailRequired?: number;
+    successUrl?: string;
+    customSuccessText?: string;
+    customDisabledText?: string;
+}
+/** POST /payment/link/update（全量替换） */
+interface UpdatePaymentLinkBody extends CreatePaymentLinkBody {
+    linkId: string;
+}
+/** 行项目中的商品快照（详情/创建响应；列表不含 productData） */
+interface PaymentLinkLineItemProductData {
+    productName: string;
+    productDescription?: string;
+    imageUrl?: string;
+    attributes?: ProductAttribute[];
+    status?: ProductStatus | string;
+}
+/** 响应中的单行项目 */
+interface PaymentLinkLineItem {
+    lineItemId?: string;
+    itemType: string;
+    productId: string;
+    quantity: number;
+    unitPrice?: number;
+    productData?: PaymentLinkLineItemProductData;
+}
+/**
+ * 响应中的 lineItems 区块。
+ * 列表/详情多为 `{ items }`；创建接口文档示例为外层含 `lineItems.items` 与 amount。
+ */
+interface PaymentLinkLineItemsSection {
+    items?: PaymentLinkLineItem[];
+    lineItems?: {
+        items?: PaymentLinkLineItem[];
+    };
+    amount?: number;
+}
+interface SettlementTokenInfo {
+    tokenId: string;
+    contractAddress: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    chainId: string;
+}
+/**
+ * 支付链接对象
+ * @see https://docs.gstable.io/zh-Hans/docs/api/core-api/payment-link
+ */
+interface PaymentLink {
+    linkId: string;
+    linkType: PaymentLinkType;
+    linkName: string;
+    lineItems: PaymentLinkLineItemsSection;
+    accountId: string;
+    settlementToken: string;
+    feeModel: PaymentLinkFeeModel;
+    amount: number;
+    payerEmailRequired?: number;
+    successUrl?: string;
+    customSuccessText?: string;
+    customDisabledText?: string;
+    linkUrl: string;
+    status: PaymentLinkStatus;
+    versionCode: string;
+    createAt?: string;
+    updateAt?: string;
+    accountName?: string;
+    accountAddress?: string;
+    settlementTokenInfo?: SettlementTokenInfo;
+}
+/** GET /payment/link/list/:page/:size */
+interface PaymentLinkListData {
+    links: PaymentLink[];
+    total: number;
+    page: string;
+    size: string;
+}
+
+/** 手续费：1 商户承担（默认），2 用户承担 */
+type CheckoutSessionFeeModel = 1 | 2;
+/** 会话生命周期状态 */
+type CheckoutSessionStatus = 'initialized' | 'paid' | 'settling' | 'completed' | 'settlement_pending' | 'expired' | 'cancelled' | string;
+/** one_time 行项目在请求中的商品描述 */
+interface OneTimeProductDataInput {
+    productName: string;
+    productDescription?: string;
+    imageUrl?: string;
+    attributes?: ProductAttribute[];
+}
+/** POST /session/checkout/create 的 lineItems 元素 */
+type CheckoutLineItemInput = {
+    itemType: 'product';
+    productId: string;
+    quantity: number;
+    unitPrice: number;
+} | {
+    itemType: 'one_time';
+    quantity: number;
+    unitPrice: number;
+    productData: OneTimeProductDataInput;
+};
+/** POST /session/checkout/create */
+interface CreateCheckoutSessionBody {
+    accountId: string;
+    settlementToken: string;
+    lineItems: CheckoutLineItemInput[];
+    successUrl?: string;
+    /** 1 必填邮箱，0 选填 */
+    payerEmailRequired?: number;
+    feeModel?: CheckoutSessionFeeModel;
+    /** 过期 Unix 时间戳（秒）；默认约当前 +30 分钟，最小间隔 1800 秒 */
+    expirationTime?: number;
+    metadata?: Record<string, unknown>;
+}
+/** 响应中的单行项目 */
+interface CheckoutLineItem {
+    lineItemId?: string;
+    itemType: string;
+    productId: string;
+    quantity: number;
+    unitPrice: number;
+    productData?: PaymentLinkLineItemProductData;
+}
+interface CheckoutLineItemsSection {
+    items: CheckoutLineItem[];
+}
+/**
+ * Checkout Session（创建接口返回或嵌于查询结果 session 内）
+ * @see https://docs.gstable.io/zh-Hans/docs/api/core-api/checkout-session
+ */
+interface CheckoutSession {
+    sessionId: string;
+    sessionType: string;
+    businessId: string;
+    businessType: string;
+    clientCode: string;
+    payer: string;
+    payerEmail: string;
+    payerEmailRequired: number;
+    paidToken: string;
+    receiptId: string;
+    recipient: string;
+    settlementToken: string;
+    feeModel: CheckoutSessionFeeModel;
+    amount: number;
+    lineItems: CheckoutLineItemsSection;
+    expirationTime: number;
+    successUrl?: string;
+    paymentUrl: string;
+    signedOnce: number;
+    initiateTx: string;
+    completeTx: string;
+    paymentSucceededTime: string | null;
+    settlementSucceededTime: string | null;
+    createAt: string;
+    status: CheckoutSessionStatus;
+    metadata?: Record<string, unknown>;
+}
+/** GET /session/:sessionId 等接口中的链上交易摘要 */
+interface SessionTransaction {
+    orderId: string;
+    channelId: string;
+    orderType: number;
+    from: string;
+    to: string;
+    metaData: string;
+    totalValue: number;
+    paymentValue: number;
+    feeValue: number;
+    netValue: number;
+    sourceTx: string;
+    targetTx: string;
+    executeTime: string;
+    finalizeTime: string;
+}
+/** GET /session/:sessionId 的 data */
+interface SessionDetail {
+    session: CheckoutSession;
+    transaction?: SessionTransaction;
+}
+/** 会话列表单项 */
+interface SessionListEntry {
+    session: CheckoutSession;
+    transaction?: SessionTransaction;
+}
+/** GET /session/list/... 的 data（文档示例中 page/size 为数字） */
+interface CheckoutSessionListData {
+    total: number;
+    page: number;
+    size: number;
+    sessions: SessionListEntry[];
+}
+
+/**
+ * 支付会话（Checkout Session）API
+ */
+declare class CheckoutSessionResource {
+    private readonly http;
+    constructor(http: GStableHttp);
+    /** POST /session/checkout/create */
+    create(body: CreateCheckoutSessionBody): Promise<CheckoutSession>;
+    /** POST /session/checkout/cancel（仅 initialized 且 signedOnce = 0） */
+    cancel(sessionId: string): Promise<OperationSuccess>;
+    /** GET /session/:sessionId — Checkout 与 Payment Link 会话均可查 */
+    detail(sessionId: string): Promise<SessionDetail>;
+    private listByPath;
+    /** GET /session/list/all/:page/:size */
+    listAll(page: number, size: number): Promise<CheckoutSessionListData>;
+    /** GET /session/list/paid/:page/:size */
+    listPaid(page: number, size: number): Promise<CheckoutSessionListData>;
+    /** GET /session/list/settling/:page/:size */
+    listSettling(page: number, size: number): Promise<CheckoutSessionListData>;
+    /** GET /session/list/completed/:page/:size */
+    listCompleted(page: number, size: number): Promise<CheckoutSessionListData>;
+    /** GET /session/list/cancelled/:page/:size */
+    listCancelled(page: number, size: number): Promise<CheckoutSessionListData>;
+    /** GET /session/list/settlement/pending/:page/:size */
+    listSettlementPending(page: number, size: number): Promise<CheckoutSessionListData>;
+}
+
+/**
+ * 支付链接模块 API
+ * @see https://docs.gstable.io/zh-Hans/docs/api/core-api/payment-link
+ */
+declare class PaymentLinkResource {
+    private readonly http;
+    constructor(http: GStableHttp);
+    /** POST /payment/link/create */
+    create(body: CreatePaymentLinkBody): Promise<PaymentLink>;
+    /** POST /payment/link/update（全量替换） */
+    update(body: UpdatePaymentLinkBody): Promise<OperationSuccess>;
+    /** POST /payment/link/disable */
+    disable(linkId: string): Promise<OperationSuccess>;
+    /** POST /payment/link/enable */
+    enable(linkId: string): Promise<OperationSuccess>;
+    /** GET /payment/link/:linkId */
+    detail(linkId: string): Promise<PaymentLink>;
+    /**
+     * GET /payment/link/list/:page/:size
+     * @param page 从 1 开始
+     */
+    list(page: number, size: number): Promise<PaymentLinkListData>;
+}
+
+/**
+ * 商品模块 API
+ * @see https://docs.gstable.io/zh-Hans/docs/api/core-api/product
+ *
+ * 商品业务错误码 100301–100306 会抛出 `GStableProductError`（仍为 `GStableError` 子类），
+ * @see https://docs.gstable.io/zh-Hans/docs/api/overview/errors#%E5%95%86%E5%93%81%E7%AE%A1%E7%90%86-1003xx
+ */
+declare class ProductResource {
+    private readonly http;
+    constructor(http: GStableHttp);
+    private invoke;
+    /** POST /product/create */
+    create(body: CreateProductBody): Promise<Product>;
+    /** POST /product/update（全量替换） */
+    update(body: UpdateProductBody): Promise<OperationSuccess>;
+    /**
+     * GET /product/list/:page/:size
+     * @param page 从 1 开始
+     * @param size 每页条数，最大 100
+     */
+    list(page: number, size: number): Promise<ProductListData>;
+    /** POST /product/list/by/ids — 不存在的 id 会被静默忽略 */
+    listByIds(body: ProductListByIdsBody): Promise<Product[]>;
+    /** POST /product/archive */
+    archive(productId: string): Promise<OperationSuccess>;
+    /** POST /product/unarchive */
+    unarchive(productId: string): Promise<OperationSuccess>;
+    /** POST /product/remove — 仅未被任何 Payment Link 引用过的商品可删 */
+    remove(productId: string): Promise<OperationSuccess>;
+}
+
+/** Webhook 状态：活跃 / 用户禁用 / 投递失败自动暂停 */
+type WebhookStatus = 'active' | 'inactive' | 'paused' | string;
+/**
+ * Webhook 对象
+ * @see https://docs.gstable.io/zh-Hans/docs/api/core-api/webhook-management
+ */
+interface Webhook {
+    webhookId: string;
+    webhookName: string;
+    webhookUrl: string;
+    webhookDescription?: string;
+    subscribedEvents: string[];
+    /** 签名密钥，创建后返回；验签见 Webhook 事件文档 */
+    key: string;
+    status: WebhookStatus;
+    createAt?: string;
+    updateAt?: string;
+}
+/** POST /webhook/create */
+interface CreateWebhookBody {
+    webhookName: string;
+    webhookUrl: string;
+    subscribedEvents: string[];
+    webhookDescription?: string;
+}
+/** POST /webhook/update（全量替换） */
+interface UpdateWebhookBody {
+    webhookId: string;
+    webhookName: string;
+    webhookUrl: string;
+    subscribedEvents: string[];
+    webhookDescription?: string;
+}
+/** GET /webhook/list 的 data */
+interface WebhookListData {
+    webhooks: Webhook[];
+}
+
+/**
+ * Webhook 管理 API（单账户最多 10 个端点）
+ */
+declare class WebhookResource {
+    private readonly http;
+    constructor(http: GStableHttp);
+    /** POST /webhook/create */
+    create(body: CreateWebhookBody): Promise<Webhook>;
+    /** POST /webhook/update（全量替换） */
+    update(body: UpdateWebhookBody): Promise<OperationSuccess>;
+    /** GET /webhook/list — 全量，无分页 */
+    list(): Promise<WebhookListData>;
+    /** GET /webhook/detail/:webhookId */
+    detail(webhookId: string): Promise<Webhook>;
+    /** POST /webhook/disable */
+    disable(webhookId: string): Promise<OperationSuccess>;
+    /** POST /webhook/enable（含从 paused 恢复） */
+    enable(webhookId: string): Promise<OperationSuccess>;
+    /** POST /webhook/key/refresh — 旧 key 立即失效 */
+    refreshKey(webhookId: string): Promise<OperationSuccess>;
+    /** POST /webhook/remove */
+    remove(webhookId: string): Promise<OperationSuccess>;
+}
+
+interface GStableClientOptions extends GStableHttpOptions {
+}
+declare class GStableClient {
+    private readonly http;
+    readonly product: ProductResource;
+    readonly account: AccountResource;
+    readonly paymentLink: PaymentLinkResource;
+    readonly capability: CapabilityResource;
+    readonly checkoutSession: CheckoutSessionResource;
+    /** AI Payment Protocol（创建会话 / 查询 / 准备支付） */
+    readonly webhook: WebhookResource;
+    constructor(options: GStableClientOptions);
+}
+
+declare class GStableError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+declare function isGStableError(e: unknown): e is GStableError;
+
+/**
+ * 根据官方错误码构造对应的 {@link GStableError} 子类（商品 / 通用与验证 / 平台），供 HTTP 层与各资源统一使用。
+ * @see https://docs.gstable.io/zh-Hans/docs/api/overview/errors
+ */
+declare function createTypedApiError(code: number, message: string): GStableError;
+
+/**
+ * 通用与验证错误（400XXX）
+ * @see https://docs.gstable.io/zh-Hans/docs/api/overview/errors#4-%E9%80%9A%E7%94%A8%E4%B8%8E%E9%AA%8C%E8%AF%81%E9%94%99%E8%AF%AF-common
+ */
+declare const CommonErrorCodes: {
+    readonly INVALID_FIELD_FORMAT: 400101;
+    readonly UNSUPPORTED_CURRENCY: 400201;
+    readonly UNSUPPORTED_CHANNEL: 400202;
+    readonly SETTLEMENT_CAPABILITIES_NOT_FOUND: 400203;
+    readonly STAT_NOT_FOUND: 400301;
+};
+type CommonErrorCode = (typeof CommonErrorCodes)[keyof typeof CommonErrorCodes];
+declare const CommonErrorMessages: Record<CommonErrorCode, string>;
+declare function isCommonErrorCode(code: number): code is CommonErrorCode;
+declare class GStableCommonError extends GStableError {
+    readonly commonErrorCode: CommonErrorCode;
+    constructor(code: CommonErrorCode, message: string);
+}
+declare function isGStableCommonError(e: unknown): e is GStableCommonError;
+/**
+ * 平台系统错误（900XXX / 999999）
+ * @see https://docs.gstable.io/zh-Hans/docs/api/overview/errors#5-%E5%B9%B3%E5%8F%B0%E7%B3%BB%E7%BB%9F%E9%94%99%E8%AF%AF-platform
+ */
+declare const PlatformErrorCodes: {
+    readonly TOO_MANY_REQUESTS: 900101;
+    readonly FAILED_TO_CREATE_RECORD: 900201;
+    readonly FAILED_TO_UPDATE_RECORD: 900202;
+    readonly FAILED_TO_QUERY_RECORD: 900203;
+    readonly IMAGE_PROCESSING_FAILED: 900301;
+    readonly INTERNAL_SYSTEM_ERROR: 999999;
+};
+type PlatformErrorCode = (typeof PlatformErrorCodes)[keyof typeof PlatformErrorCodes];
+declare const PlatformErrorMessages: Record<PlatformErrorCode, string>;
+declare function isPlatformErrorCode(code: number): code is PlatformErrorCode;
+declare class GStablePlatformError extends GStableError {
+    readonly platformErrorCode: PlatformErrorCode;
+    constructor(code: PlatformErrorCode, message: string);
+}
+declare function isGStablePlatformError(e: unknown): e is GStablePlatformError;
+
+/**
+ * 商品管理业务错误码（1003XX）
+ * @see https://docs.gstable.io/zh-Hans/docs/api/overview/errors#%E5%95%86%E5%93%81%E7%AE%A1%E7%90%86-1003xx
+ */
+declare const ProductErrorCodes: {
+    /** 指定的 Product ID 不存在 */
+    readonly NOT_FOUND: 100301;
+    /** 批量操作中部分商品 ID 不存在 */
+    readonly PARTIAL_MISSING: 100302;
+    /** 批量操作中部分商品状态不可用 */
+    readonly PARTIALLY_UNAVAILABLE: 100303;
+    /** 商品未处于激活状态，无法用于创建链接或会话 */
+    readonly NOT_ACTIVE: 100304;
+    /** 商品已被关联使用，无法执行某些特定修改 */
+    readonly HAS_BEEN_USED: 100305;
+    /** 商品已被逻辑删除 */
+    readonly HAS_BEEN_REMOVED: 100306;
+};
+type ProductErrorCode = (typeof ProductErrorCodes)[keyof typeof ProductErrorCodes];
+/** 文档中的英文 message，仅作展示参考；业务判断请使用 {@link ProductErrorCodes} */
+declare const ProductErrorMessages: Record<ProductErrorCode, string>;
+declare function isProductErrorCode(code: number): code is ProductErrorCode;
+/**
+ * 商品模块 API 返回 1003XX 时的专用异常，可通过 `instanceof` 与 `productErrorCode` 分支处理。
+ * 请依据 `code` / `productErrorCode` 编写逻辑，勿依赖 `message` 文案。
+ */
+declare class GStableProductError extends GStableError {
+    readonly productErrorCode: ProductErrorCode;
+    constructor(code: ProductErrorCode, message: string);
+}
+declare function isGStableProductError(e: unknown): e is GStableProductError;
+/** 将 {@link GStableError} 中属于商品业务码的异常转为 {@link GStableProductError}，其它值原样返回 */
+declare function rewriteProductBusinessError(error: unknown): unknown;
+
+/**
+ * 与 GStable API 标准响应包络一致：https://docs.gstable.io/zh-Hans/docs/api/overview/introduction/
+ */
+interface ApiEnvelope<T> {
+    code: number;
+    message: string;
+    data: T;
+}
+
+/**
+ * AI Payment Protocol — 支付会话 / 准备支付
+ * @see https://docs.gstable.io/zh-Hans/docs/api/ai-payment/create-session
+ * @see https://docs.gstable.io/zh-Hans/docs/api/ai-payment/get-session
+ * @see https://docs.gstable.io/zh-Hans/docs/api/ai-payment/prepare-payment
+ */
+/** EIP-712 消息：创建支付会话 */
+interface CreatePaymentSessionMessage {
+    purpose: 'create_payment_session';
+    linkId: string;
+    linkVersion: string;
+    merchantId: string;
+    payer: string;
+    paymentChainId: string;
+    paymentToken: string;
+    amount: string;
+    authorizationNonce: string;
+    authorizationExpiresAt: string;
+}
+/** POST /payment/session/create */
+interface CreatePaymentSessionBody {
+    message: CreatePaymentSessionMessage;
+    signature: string;
+}
+/** AI 视图（文档结构可能随协议扩展，字段按需收窄） */
+interface AiPaymentView {
+    pricingModel?: {
+        type: string;
+    };
+    workflow?: {
+        stage: string;
+        nextAction?: {
+            action: string;
+            authorizationRequired?: boolean;
+            description?: string;
+        };
+    };
+    preparePaymentRequirement?: unknown;
+    paymentExecutionGuide?: unknown;
+    completePaymentSessionGuide?: unknown;
+}
+/** POST /payment/session/create 返回的 data */
+interface CreatePaymentSessionResult {
+    sessionId: string;
+    sessionType: string;
+    sessionExpiresAt: number;
+    aiView: AiPaymentView;
+}
+/**
+ * GET /session/:sessionId — AI 流程下的会话详情（扁平结构，含 aiView）。
+ * 与核心 API 会话查询共用路径；若需 `session`/`transaction` 对账结构请使用 `checkoutSession.detail`。
+ */
+interface AiPaymentSession {
+    sessionId: string;
+    sessionType: string;
+    lineItems?: unknown[];
+    aiView: AiPaymentView;
+}
+/** EIP-712 消息：准备支付 */
+interface PreparePaymentMessage {
+    purpose: 'prepare_payment';
+    sessionId: string;
+    merchantId: string;
+    payer: string;
+    payerEmail: string;
+    paymentChainId: string;
+    paymentToken: string;
+    authorizationNonce: string;
+    authorizationExpiresAt: string;
+}
+/** POST /payment/prepare */
+interface PreparePaymentBody {
+    message: PreparePaymentMessage;
+    signature: string;
+}
+/** POST /payment/prepare 返回的 data */
+interface PreparePaymentResult {
+    calldata: string;
+    aiView: AiPaymentView;
+}
+
+/**
+ * AI Payment Protocol（EIP-712 签名由调用方生成后传入）
+ * @see https://docs.gstable.io/zh-Hans/docs/api/ai-payment/create-session
+ * @see https://docs.gstable.io/zh-Hans/docs/api/ai-payment/get-session
+ * @see https://docs.gstable.io/zh-Hans/docs/api/ai-payment/prepare-payment
+ */
+declare class AiPaymentResource {
+    private readonly http;
+    constructor(http: GStableHttp);
+    /** POST /payment/session/create */
+    createSession(body: CreatePaymentSessionBody): Promise<CreatePaymentSessionResult>;
+    /**
+     * GET /session/:sessionId
+     * 与核心 `checkoutSession.detail` 同路径；本方法按 AI 文档将 data 解析为含 `aiView` 的扁平结构。
+     */
+    getSession(sessionId: string): Promise<AiPaymentSession>;
+    /** POST /payment/prepare */
+    preparePayment(body: PreparePaymentBody): Promise<PreparePaymentResult>;
+}
+
+export { type Account, AccountResource, type AccountStatus, type AccountType, AiPaymentResource, type AiPaymentSession, type AiPaymentView, type ApiEnvelope, CapabilityResource, type CheckoutLineItem, type CheckoutLineItemInput, type CheckoutLineItemsSection, type CheckoutSession, type CheckoutSessionFeeModel, type CheckoutSessionListData, CheckoutSessionResource, type CheckoutSessionStatus, type CommonErrorCode, CommonErrorCodes, CommonErrorMessages, type CreateCheckoutSessionBody, type CreatePaymentLinkBody, type CreatePaymentSessionBody, type CreatePaymentSessionMessage, type CreatePaymentSessionResult, type CreateProductBody, type CreateWebhookBody, DEFAULT_BASE_URL, DEFAULT_PUBLIC_BASE_URL, GStableClient, type GStableClientOptions, GStableCommonError, GStableError, GStableHttp, type GStableHttpOptions, GStablePlatformError, GStableProductError, type HttpMethod, type OneTimeProductDataInput, type OperationSuccess, type PaymentCapabilities, type PaymentCapabilitiesMatrix, type PaymentCapabilityRoute, type PaymentLink, type PaymentLinkFeeModel, type PaymentLinkLineItem, type PaymentLinkLineItemInput, type PaymentLinkLineItemProductData, type PaymentLinkLineItemsSection, type PaymentLinkListData, PaymentLinkResource, type PaymentLinkStatus, type PaymentLinkType, type PlatformErrorCode, PlatformErrorCodes, PlatformErrorMessages, type PreparePaymentBody, type PreparePaymentMessage, type PreparePaymentResult, type Product, type ProductAttribute, type ProductErrorCode, ProductErrorCodes, ProductErrorMessages, type ProductListByIdsBody, type ProductListData, ProductResource, type ProductStatus, type SessionDetail, type SessionListEntry, type SessionTransaction, type SettlementTokenInfo, type SupportedToken, type UpdatePaymentLinkBody, type UpdateProductBody, type UpdateWebhookBody, type Webhook, type WebhookListData, WebhookResource, type WebhookStatus, createTypedApiError, isCommonErrorCode, isGStableCommonError, isGStableError, isGStablePlatformError, isGStableProductError, isPlatformErrorCode, isProductErrorCode, rewriteProductBusinessError };