@keelcodes/sdk 0.0.0-stage → 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { PaymentAPI } from './payment';
+import { WalletAPI } from './wallet';
+import { DataAPI } from './data';
+import { AccountAPI } from './account';
+import type { KeelConfig } from './types';
+export { KeelApiError, isKeelApiError } from './errors';
+export type { KeelConfig, KeelModule, KeelErrorBody, KeelWalletAuth } from './types';
+export declare class Keel {
+    readonly payment: PaymentAPI;
+    readonly wallet: WalletAPI;
+    readonly data: DataAPI;
+    readonly account: AccountAPI;
+    constructor(config?: KeelConfig);
+}
+export default Keel;

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// @keelcodes/sdk — 聚合入口（单包，4 个 namespace）
+// ---------------------------------------------------------------------------
+// 用法：
+//   import { Keel } from '@keelcodes/sdk'                 // 全家桶
+//   import { PaymentAPI } from '@keelcodes/sdk/payment'    // 按域 tree-shaking
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Keel = exports.isKeelApiError = exports.KeelApiError = void 0;
+const http_1 = require("./http");
+const payment_1 = require("./payment");
+const wallet_1 = require("./wallet");
+const data_1 = require("./data");
+const account_1 = require("./account");
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "KeelApiError", { enumerable: true, get: function () { return errors_1.KeelApiError; } });
+Object.defineProperty(exports, "isKeelApiError", { enumerable: true, get: function () { return errors_1.isKeelApiError; } });
+class Keel {
+    constructor(config = {}) {
+        const http = new http_1.HttpClient(config);
+        this.payment = new payment_1.PaymentAPI(http);
+        this.wallet = new wallet_1.WalletAPI(http);
+        this.data = new data_1.DataAPI(http);
+        this.account = new account_1.AccountAPI(http);
+    }
+}
+exports.Keel = Keel;
+exports.default = Keel;

package/dist/payment.d.ts

@@ -0,0 +1,230 @@
+import { HttpClient } from './http';
+import type { Reference } from './types';
+export interface ChargeParams {
+    payer: string;
+    amountWei: string;
+    /** 收费 rail（内部路由，对外仅暴露语义）。 */
+    method: 'x402' | 'a2a' | 'batch' | 'invite';
+    asset?: string;
+    chain?: string;
+    reference: Reference;
+    metadata?: Record<string, unknown>;
+}
+/** 链上收费返回收款地址 / 价格 / 网络。 */
+export type ChargeResult = {
+    reference: string;
+    payTo: string;
+    priceWei: string;
+    network: string;
+};
+export interface PayParams {
+    payee: string;
+    amountWei: string;
+    asset?: string;
+    reference: Reference;
+    metadata?: Record<string, unknown>;
+}
+export interface PayResult {
+    reference: string;
+    settled: boolean;
+    transferId: string;
+}
+/** x402 v2 支付凭证校验结果（规范 §5.4 VerifyResponse）。 */
+export interface X402VerifyResult {
+    isValid: boolean;
+    invalidReason?: string;
+    payer?: string;
+}
+/** x402 v2 `PaymentRequirements`（PaymentRequired.accepts 单项）。 */
+export interface X402PaymentRequirements {
+    scheme: 'exact' | 'upto';
+    network: string;
+    asset: string;
+    payTo: string;
+    amount: string;
+    maxTimeoutSeconds?: number;
+    extra?: Record<string, unknown>;
+}
+/** x402 v2 facilitator 发现（规范 §7.3）。 */
+export interface X402Supported {
+    kinds: Array<{
+        x402Version: 2;
+        scheme: 'exact' | 'upto';
+        network: string;
+    }>;
+}
+export interface BalanceResult {
+    address: string;
+    balanceWei: string;
+}
+export interface PaymentOrder {
+    intentId: string;
+    method: string;
+    subscriber: string | null;
+    asset: string | null;
+    amountWei: string | null;
+    status: string;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface OrdersParams {
+    limit?: number;
+    offset?: number;
+    status?: string;
+    subscriber?: string;
+}
+export interface OrdersResult {
+    orders: PaymentOrder[];
+}
+/** 单笔结算可核验读取（PC-4）。 */
+export interface SettlementRecord {
+    reference: string;
+    payer: string;
+    amountWei: string;
+    asset: string;
+    chainId: number;
+    method?: string;
+    settledAt: string;
+    metadata?: Record<string, unknown>;
+}
+/** 402 待付款结构化（PC-3）。 */
+export interface PaymentRequiredBody {
+    priceWei: string;
+    payTo: string;
+    resource: string;
+    resumeRef: string;
+    mode: 'topup' | 'subscribe';
+    network: string;
+    asset: string;
+}
+export declare class PaymentAPI {
+    private http;
+    constructor(http: HttpClient);
+    /** 发起收费（内部路由 x402/a2a/batch/invite）。 */
+    charge(params: ChargeParams): Promise<ChargeResult>;
+    /** 主动付费。 */
+    pay(params: PayParams): Promise<PayResult>;
+    /** 校验 x402 v2 支付凭证（base64 PAYMENT-SIGNATURE）——facilitator verify。 */
+    verifyPayment(paymentPayload: string, paymentRequirements?: X402PaymentRequirements): Promise<X402VerifyResult>;
+    /** x402 v2 facilitator 发现（支持的 scheme / network）。 */
+    supported(): Promise<X402Supported>;
+    /** 查余额。 */
+    balance(address: string, asset?: string): Promise<BalanceResult>;
+    /** 查交易记录。 */
+    orders(params?: OrdersParams): Promise<OrdersResult>;
+    /** 核验单笔结算（按幂等键 reference）。 */
+    settlement(reference: Reference): Promise<SettlementRecord>;
+    /** 访问判定/按次扣费（返回 active，或 402 抛 KeelApiError）。 */
+    access(subscriber: string, resource: unknown): Promise<{
+        active: boolean;
+    }>;
+    /** 按量套餐价目（公开；canonical `/v1/payment/plans`，由 mpc 承载）。 */
+    plans(): Promise<Record<string, unknown>>;
+    /** 预付费账本余额（canonical `/v1/payment/ledger-balance`，由 mpc 承载）。 */
+    ledgerBalance(params: {
+        token: string;
+    }): Promise<Record<string, unknown>>;
+    /** 支付通道发现：启用的 rail、各链收款钱包 / 价格 / 托管、各链可接受的稳定币。 */
+    info(chain?: string): Promise<Record<string, unknown>>;
+    /** 读取链上订阅详情（active / payToken / amountPaid / 周期 / 试用）。 */
+    subscriptionDetail(chain: string, subscriber: string, resourceId: number): Promise<Record<string, unknown>>;
+    /** 读取链上套餐定价（price / period / active）。 */
+    price(planId: number, chain?: string): Promise<Record<string, unknown>>;
+    /**
+     * 创建 a2a 支付意图（phase 1）。
+     * `settlementMode: 'direct'` 时 `payee` 必填，settle 只核验 payer → payee 的链上转账。
+     */
+    a2aCreate(params: {
+        subscriber: string;
+        valueWei: string;
+        asset?: string;
+        chain?: string;
+        payee?: string;
+        settlementMode?: 'collector' | 'direct';
+        expiresIn?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** 确认 a2a 支付意图（phase 2）：mode=tx 校验链上交易；mode=balance 走账本扣减。 */
+    a2aSettle(params: {
+        paymentId: string;
+        mode?: 'tx' | 'balance';
+        txHash?: string;
+        chain?: string;
+        subscriber?: string;
+        amountWei?: string;
+        asset?: string;
+        ref?: string;
+    }): Promise<Record<string, unknown>>;
+    /** 结算 direct 意图（phase 2）：按 intent 绑定的 payee/asset/精确金额核验，并按链确认数判定终局。 */
+    a2aDirectSettle(paymentId: string, txHash: string): Promise<Record<string, unknown>>;
+    /** 取消未结算的 direct 意图（幂等）。 */
+    a2aCancel(paymentId: string): Promise<Record<string, unknown>>;
+    /** 创建批量收款意图（一付款人对多收款人）。 */
+    batchCreate(params: {
+        subscriber: string;
+        items: Array<Record<string, unknown>>;
+        chain?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** 结算批量收款中的一项（提交链上 txHash）。 */
+    batchSettle(params: {
+        batchId: string;
+        itemId: string;
+        txHash: string;
+        chain?: string;
+    }): Promise<Record<string, unknown>>;
+    /** 读取批量收款状态。 */
+    batchGet(batchId: string): Promise<Record<string, unknown>>;
+    /** 取消批量收款。 */
+    batchCancel(batchId: string): Promise<Record<string, unknown>>;
+    /** 创建账单邀请（payer → payee）。 */
+    inviteCreate(params: {
+        payer: string;
+        payee: string;
+        valueWei: string;
+        asset?: string;
+        chain?: string;
+        dueAt?: string;
+        memo?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** 按地址 + 角色（payer|payee）列出邀请。 */
+    inviteList(p: {
+        address: string;
+        role: 'payer' | 'payee';
+        status?: string;
+    }): Promise<Record<string, unknown>>;
+    /** 读取单个邀请详情。 */
+    inviteGet(inviteId: string): Promise<Record<string, unknown>>;
+    /** 取消未结算的邀请。 */
+    inviteCancel(inviteId: string): Promise<Record<string, unknown>>;
+    /** 链上结算邀请（提交 payer txHash）。 */
+    inviteSettle(p: {
+        inviteId: string;
+        txHash: string;
+        chain?: string;
+    }): Promise<Record<string, unknown>>;
+    /** 用 payer 账本余额支付邀请（无链上交易）。 */
+    invitePay(inviteId: string): Promise<Record<string, unknown>>;
+    /** 请求一笔账本内转账（from → to）。 */
+    transferCreate(params: {
+        from: string;
+        to: string;
+        valueWei: string;
+        asset?: string;
+        reference?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** 按地址 + 角色（from|to）列出转账。 */
+    transferList(p: {
+        address: string;
+        role: 'from' | 'to';
+    }): Promise<Record<string, unknown>>;
+    /** 读取单笔转账详情。 */
+    transferGet(transferId: string): Promise<Record<string, unknown>>;
+    /** 确认并原子执行转账。 */
+    transferConfirm(transferId: string): Promise<Record<string, unknown>>;
+    /** 取消未执行的转账。 */
+    transferCancel(transferId: string): Promise<Record<string, unknown>>;
+}

package/dist/payment.js

@@ -0,0 +1,160 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// @keelcodes/sdk — payment 模块（7 动作）
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentAPI = void 0;
+class PaymentAPI {
+    constructor(http) {
+        this.http = http;
+    }
+    /** 发起收费（内部路由 x402/a2a/batch/invite）。 */
+    charge(params) {
+        return this.http.post('/v1/payment/charge', params);
+    }
+    /** 主动付费。 */
+    pay(params) {
+        return this.http.post('/v1/payment/pay', params);
+    }
+    /** 校验 x402 v2 支付凭证（base64 PAYMENT-SIGNATURE）——facilitator verify。 */
+    verifyPayment(paymentPayload, paymentRequirements) {
+        return this.http.post('/v1/payment/x402/verify', { x402Version: 2, paymentPayload, paymentRequirements });
+    }
+    /** x402 v2 facilitator 发现（支持的 scheme / network）。 */
+    supported() {
+        return this.http.get('/v1/payment/x402/supported');
+    }
+    /** 查余额。 */
+    balance(address, asset) {
+        const q = new URLSearchParams({ address });
+        if (asset)
+            q.set('asset', asset);
+        return this.http.get('/v1/payment/balance?' + q.toString());
+    }
+    /** 查交易记录。 */
+    orders(params = {}) {
+        const q = new URLSearchParams();
+        if (params.limit !== undefined)
+            q.set('limit', String(params.limit));
+        if (params.offset !== undefined)
+            q.set('offset', String(params.offset));
+        if (params.status !== undefined)
+            q.set('status', params.status);
+        if (params.subscriber !== undefined)
+            q.set('subscriber', params.subscriber);
+        const qs = q.toString();
+        return this.http.get('/v1/payment/orders' + (qs ? '?' + qs : ''));
+    }
+    /** 核验单笔结算（按幂等键 reference）。 */
+    settlement(reference) {
+        return this.http.get('/v1/payment/settlement/' + encodeURIComponent(reference));
+    }
+    /** 访问判定/按次扣费（返回 active，或 402 抛 KeelApiError）。 */
+    access(subscriber, resource) {
+        return this.http.post('/v1/payment/access', { subscriber, resource });
+    }
+    /** 按量套餐价目（公开；canonical `/v1/payment/plans`，由 mpc 承载）。 */
+    plans() {
+        return this.http.get('/v1/payment/plans');
+    }
+    /** 预付费账本余额（canonical `/v1/payment/ledger-balance`，由 mpc 承载）。 */
+    ledgerBalance(params) {
+        return this.http.post('/v1/payment/ledger-balance', params);
+    }
+    // ── 旧 index MCP 能力补齐：通道发现 / 链上意图 / 批量 / 邀请 / 转账 ──
+    /** 支付通道发现：启用的 rail、各链收款钱包 / 价格 / 托管、各链可接受的稳定币。 */
+    info(chain) {
+        return this.http.get('/v1/payment/info' + (chain ? '?chain=' + encodeURIComponent(chain) : ''));
+    }
+    /** 读取链上订阅详情（active / payToken / amountPaid / 周期 / 试用）。 */
+    subscriptionDetail(chain, subscriber, resourceId) {
+        return this.http.get('/v1/payment/subscription-detail/' + encodeURIComponent(chain) + '/' + encodeURIComponent(subscriber) + '/' + encodeURIComponent(String(resourceId)));
+    }
+    /** 读取链上套餐定价（price / period / active）。 */
+    price(planId, chain) {
+        return this.http.get('/v1/payment/price?chain=' + encodeURIComponent(chain || 'bsc') + '&planId=' + encodeURIComponent(String(planId)));
+    }
+    /**
+     * 创建 a2a 支付意图（phase 1）。
+     * `settlementMode: 'direct'` 时 `payee` 必填，settle 只核验 payer → payee 的链上转账。
+     */
+    a2aCreate(params) {
+        return this.http.post('/v1/payment/a2a', params);
+    }
+    /** 确认 a2a 支付意图（phase 2）：mode=tx 校验链上交易；mode=balance 走账本扣减。 */
+    a2aSettle(params) {
+        return this.http.post('/v1/payment/a2a/settle', params);
+    }
+    /** 结算 direct 意图（phase 2）：按 intent 绑定的 payee/asset/精确金额核验，并按链确认数判定终局。 */
+    a2aDirectSettle(paymentId, txHash) {
+        return this.http.post('/v1/payment/a2a/' + encodeURIComponent(paymentId) + '/settle', { txHash });
+    }
+    /** 取消未结算的 direct 意图（幂等）。 */
+    a2aCancel(paymentId) {
+        return this.http.post('/v1/payment/a2a/' + encodeURIComponent(paymentId) + '/cancel', {});
+    }
+    /** 创建批量收款意图（一付款人对多收款人）。 */
+    batchCreate(params) {
+        return this.http.post('/v1/payment/batch', params);
+    }
+    /** 结算批量收款中的一项（提交链上 txHash）。 */
+    batchSettle(params) {
+        return this.http.post('/v1/payment/batch/settle', params);
+    }
+    /** 读取批量收款状态。 */
+    batchGet(batchId) {
+        return this.http.get('/v1/payment/batch?batchId=' + encodeURIComponent(batchId));
+    }
+    /** 取消批量收款。 */
+    batchCancel(batchId) {
+        return this.http.post('/v1/payment/batch/cancel', { batchId });
+    }
+    /** 创建账单邀请（payer → payee）。 */
+    inviteCreate(params) {
+        return this.http.post('/v1/payment/invites', params);
+    }
+    /** 按地址 + 角色（payer|payee）列出邀请。 */
+    inviteList(p) {
+        const q = new URLSearchParams({ address: p.address, role: p.role });
+        if (p.status)
+            q.set('status', p.status);
+        return this.http.get('/v1/payment/invites?' + q.toString());
+    }
+    /** 读取单个邀请详情。 */
+    inviteGet(inviteId) {
+        return this.http.get('/v1/payment/invites/' + encodeURIComponent(inviteId));
+    }
+    /** 取消未结算的邀请。 */
+    inviteCancel(inviteId) {
+        return this.http.post('/v1/payment/invites/' + encodeURIComponent(inviteId) + '/cancel');
+    }
+    /** 链上结算邀请（提交 payer txHash）。 */
+    inviteSettle(p) {
+        return this.http.post('/v1/payment/invites/' + encodeURIComponent(p.inviteId) + '/settle', { txHash: p.txHash, chain: p.chain });
+    }
+    /** 用 payer 账本余额支付邀请（无链上交易）。 */
+    invitePay(inviteId) {
+        return this.http.post('/v1/payment/invites/' + encodeURIComponent(inviteId) + '/pay');
+    }
+    /** 请求一笔账本内转账（from → to）。 */
+    transferCreate(params) {
+        return this.http.post('/v1/payment/transfers', params);
+    }
+    /** 按地址 + 角色（from|to）列出转账。 */
+    transferList(p) {
+        return this.http.get('/v1/payment/transfers?' + new URLSearchParams({ address: p.address, role: p.role }).toString());
+    }
+    /** 读取单笔转账详情。 */
+    transferGet(transferId) {
+        return this.http.get('/v1/payment/transfers/' + encodeURIComponent(transferId));
+    }
+    /** 确认并原子执行转账。 */
+    transferConfirm(transferId) {
+        return this.http.post('/v1/payment/transfers/' + encodeURIComponent(transferId) + '/confirm');
+    }
+    /** 取消未执行的转账。 */
+    transferCancel(transferId) {
+        return this.http.post('/v1/payment/transfers/' + encodeURIComponent(transferId) + '/cancel');
+    }
+}
+exports.PaymentAPI = PaymentAPI;

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/** 对外四模块。 */
+export type KeelModule = 'payment' | 'wallet' | 'data' | 'account';
+/** 钱包签名鉴权（account/wallet 自助面需要；服务端按 EIP-191 校验）。 */
+export interface KeelWalletAuth {
+    /** 钱包地址（0x...） */
+    address: string;
+    /** EIP-191 签名函数：入参为待签消息，返回签名 hex（可异步）。 */
+    sign: (message: string) => Promise<string> | string;
+}
+/** SDK 配置。 */
+export interface KeelConfig {
+    /** baseUrl，默认 https://keel.codes */
+    baseUrl?: string;
+    /** Bearer API key（按模块订阅签发，`sk_<module>_*`） */
+    apiKey?: string;
+    /** 内部服务鉴权 key（`X-Service-Key`）；供网关服务级旁路放行可信内部组件（如 keel-mcp）。 */
+    serviceKey?: string;
+    /** 请求超时（ms），默认 30000 */
+    timeout?: number;
+    /** 钱包签名鉴权；设置后自动附加 x-wallet-address/signature/timestamp 请求头。 */
+    wallet?: KeelWalletAuth;
+}
+/** 统一错误体（契约 §3）。 */
+export interface KeelErrorBody {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/** 幂等键：写操作由调用方生成，相同 reference 不重复入账/扣费。 */
+export type Reference = string;

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// @keelcodes/sdk — 公共类型（对齐 KEEL_CONTRACT_V1.md）
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });