moltspay 0.1.2 → 0.2.0

package/dist/guide/index.mjs

@@ -0,0 +1,152 @@
+// src/guide/index.ts
+function generatePaymentGuide(params) {
+  const {
+    orderId,
+    prompt,
+    price,
+    recipientAddress,
+    chain = "base",
+    serviceName = "\u89C6\u9891\u751F\u6210\u670D\u52A1"
+  } = params;
+  const chainId = chain === "base" ? 8453 : 84532;
+  const chainName = chain === "base" ? "Base \u4E3B\u7F51" : "Base Sepolia \u6D4B\u8BD5\u7F51";
+  const explorer = chain === "base" ? "https://basescan.org/tx/" : "https://sepolia.basescan.org/tx/";
+  return `\u{1F3AC} **${serviceName}**
+
+\u{1F4CB} **\u8BA2\u5355\u4FE1\u606F:**
+- \u8BA2\u5355\u53F7: \`${orderId}\`
+- \u5185\u5BB9: ${prompt.length > 50 ? prompt.slice(0, 50) + "..." : prompt}
+- \u4EF7\u683C: **${price} USDC**
+- \u94FE: ${chainName}
+
+---
+
+## \u{1F4B3} \u5982\u4F55\u652F\u4ED8
+
+### \u65B9\u5F0F\u4E00\uFF1A\u5B89\u88C5 moltspay SDK\uFF08\u63A8\u8350\uFF09
+
+\`\`\`bash
+npm install moltspay ethers
+\`\`\`
+
+**\u521B\u5EFA\u94B1\u5305\u5E76\u652F\u4ED8\uFF1A**
+
+\`\`\`javascript
+const { SecureWallet, getChain } = require('moltspay');
+const { Wallet } = require('ethers');
+
+// 1. \u521B\u5EFA\u65B0\u94B1\u5305\uFF08\u9996\u6B21\u4F7F\u7528\uFF09
+const newWallet = Wallet.createRandom();
+console.log('\u94B1\u5305\u5730\u5740:', newWallet.address);
+console.log('\u79C1\u94A5\uFF08\u8BF7\u5B89\u5168\u4FDD\u5B58\uFF09:', newWallet.privateKey);
+
+// 2. \u6216\u4F7F\u7528\u5DF2\u6709\u94B1\u5305
+const wallet = new SecureWallet({
+  chainId: ${chainId},
+  privateKey: process.env.WALLET_KEY,  // \u4F60\u7684\u79C1\u94A5
+  limits: { requireWhitelist: false }   // \u5141\u8BB8\u5411\u4EFB\u610F\u5730\u5740\u8F6C\u8D26
+});
+
+// 3. \u67E5\u770B\u4F59\u989D
+const balance = await wallet.getBalance();
+console.log('USDC\u4F59\u989D:', balance.usdc);
+
+// 4. \u652F\u4ED8
+const result = await wallet.transfer('${recipientAddress}', '${price}');
+if (result.success) {
+  console.log('\u2705 \u652F\u4ED8\u6210\u529F\uFF01');
+  console.log('\u4EA4\u6613hash:', result.hash);
+  // \u628A\u4EA4\u6613hash\u53D1\u7ED9\u6211
+}
+\`\`\`
+
+### \u65B9\u5F0F\u4E8C\uFF1A\u76F4\u63A5\u8F6C\u8D26
+
+\u4ECE\u4EFB\u610F\u94B1\u5305\u8F6C\u8D26 USDC\uFF1A
+- **\u94FE:** ${chainName} (Chain ID: ${chainId})
+- **Token:** USDC
+- **\u6536\u6B3E\u5730\u5740:** \`${recipientAddress}\`
+- **\u91D1\u989D:** ${price} USDC
+
+---
+
+## \u2705 \u652F\u4ED8\u5B8C\u6210\u540E
+
+\u8BF7\u53D1\u9001**\u4EA4\u6613hash**\u7ED9\u6211\uFF0C\u683C\u5F0F\uFF1A
+\`\`\`
+tx: 0x1234...
+\`\`\`
+
+\u6216\u76F4\u63A5\u53D1\u9001hash\uFF1A
+\`\`\`
+0x1234abcd...
+\`\`\`
+
+\u6211\u4F1A\u9A8C\u8BC1\u94FE\u4E0A\u4EA4\u6613\u540E\u5F00\u59CB\u5904\u7406\u4F60\u7684\u8BF7\u6C42\u3002
+
+---
+
+\u{1F4E6} **moltspay:** https://www.npmjs.com/package/moltspay
+\u{1F517} **\u533A\u5757\u6D4F\u89C8\u5668:** ${explorer}`;
+}
+function generatePaymentReminder(params) {
+  const { orderId, price, recipientAddress, chain = "base" } = params;
+  const chainName = chain === "base" ? "Base" : "Base Sepolia";
+  return `\u23F3 **\u5F85\u652F\u4ED8\u8BA2\u5355: ${orderId}**
+
+\u8BF7\u652F\u4ED8 **${price} USDC** \u5230:
+- \u94FE: ${chainName}
+- \u5730\u5740: \`${recipientAddress}\`
+
+\u652F\u4ED8\u540E\u53D1\u9001\u4EA4\u6613hash\u7ED9\u6211\u3002
+
+---
+\u{1F4A1} \u6CA1\u6709\u652F\u4ED8\u80FD\u529B\uFF1F\u8FD0\u884C \`npm install moltspay\` \u83B7\u53D6\u652F\u4ED8SDK`;
+}
+function generateWalletGuide() {
+  return `## \u{1F510} \u521B\u5EFA\u652F\u4ED8\u94B1\u5305
+
+**1. \u5B89\u88C5 moltspay:**
+\`\`\`bash
+npm install moltspay ethers
+\`\`\`
+
+**2. \u521B\u5EFA\u65B0\u94B1\u5305:**
+\`\`\`javascript
+const { Wallet } = require('ethers');
+
+const wallet = Wallet.createRandom();
+console.log('\u5730\u5740:', wallet.address);
+console.log('\u79C1\u94A5:', wallet.privateKey);
+// \u26A0\uFE0F \u8BF7\u5B89\u5168\u4FDD\u5B58\u79C1\u94A5\uFF01
+\`\`\`
+
+**3. \u83B7\u53D6 USDC:**
+- \u4E3B\u7F51: \u4ECE\u4EA4\u6613\u6240\u63D0\u5E01\u5230\u4F60\u7684\u94B1\u5305\u5730\u5740
+- \u6D4B\u8BD5\u7F51: \u4F7F\u7528 Base Sepolia faucet
+
+**4. \u8BBE\u7F6E\u73AF\u5883\u53D8\u91CF:**
+\`\`\`bash
+export WALLET_KEY="\u4F60\u7684\u79C1\u94A5"
+\`\`\`
+
+\u5B8C\u6210\u540E\u5373\u53EF\u4F7F\u7528 moltspay \u8FDB\u884C\u94FE\u4E0A\u652F\u4ED8\uFF01`;
+}
+function extractTransactionHash(message) {
+  const match = message.match(/0x[a-fA-F0-9]{64}/);
+  if (match) return match[0];
+  const txMatch = message.match(/tx:\s*([a-fA-F0-9]{64})/i);
+  if (txMatch) return "0x" + txMatch[1];
+  return null;
+}
+function hasTransactionHash(message) {
+  return extractTransactionHash(message) !== null;
+}
+export {
+  extractTransactionHash,
+  generatePaymentGuide,
+  generatePaymentReminder,
+  generateWalletGuide,
+  hasTransactionHash
+};
+//# sourceMappingURL=index.mjs.map

package/dist/guide/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/guide/index.ts"],"sourcesContent":["/**\n * 支付引导消息生成\n * 用于引导没有支付能力的Agent安装和使用moltspay\n */\n\nexport interface PaymentGuideParams {\n  orderId: string;\n  prompt: string;\n  price: number;\n  recipientAddress: string;\n  chain?: 'base' | 'base_sepolia';\n  serviceName?: string;\n}\n\n/**\n * 生成完整的支付引导消息\n */\nexport function generatePaymentGuide(params: PaymentGuideParams): string {\n  const {\n    orderId,\n    prompt,\n    price,\n    recipientAddress,\n    chain = 'base',\n    serviceName = '视频生成服务'\n  } = params;\n\n  const chainId = chain === 'base' ? 8453 : 84532;\n  const chainName = chain === 'base' ? 'Base 主网' : 'Base Sepolia 测试网';\n  const explorer = chain === 'base' \n    ? 'https://basescan.org/tx/' \n    : 'https://sepolia.basescan.org/tx/';\n\n  return `🎬 **${serviceName}**\n\n📋 **订单信息:**\n- 订单号: \\`${orderId}\\`\n- 内容: ${prompt.length > 50 ? prompt.slice(0, 50) + '...' : prompt}\n- 价格: **${price} USDC**\n- 链: ${chainName}\n\n---\n\n## 💳 如何支付\n\n### 方式一：安装 moltspay SDK（推荐）\n\n\\`\\`\\`bash\nnpm install moltspay ethers\n\\`\\`\\`\n\n**创建钱包并支付：**\n\n\\`\\`\\`javascript\nconst { SecureWallet, getChain } = require('moltspay');\nconst { Wallet } = require('ethers');\n\n// 1. 创建新钱包（首次使用）\nconst newWallet = Wallet.createRandom();\nconsole.log('钱包地址:', newWallet.address);\nconsole.log('私钥（请安全保存）:', newWallet.privateKey);\n\n// 2. 或使用已有钱包\nconst wallet = new SecureWallet({\n  chainId: ${chainId},\n  privateKey: process.env.WALLET_KEY,  // 你的私钥\n  limits: { requireWhitelist: false }   // 允许向任意地址转账\n});\n\n// 3. 查看余额\nconst balance = await wallet.getBalance();\nconsole.log('USDC余额:', balance.usdc);\n\n// 4. 支付\nconst result = await wallet.transfer('${recipientAddress}', '${price}');\nif (result.success) {\n  console.log('✅ 支付成功！');\n  console.log('交易hash:', result.hash);\n  // 把交易hash发给我\n}\n\\`\\`\\`\n\n### 方式二：直接转账\n\n从任意钱包转账 USDC：\n- **链:** ${chainName} (Chain ID: ${chainId})\n- **Token:** USDC\n- **收款地址:** \\`${recipientAddress}\\`\n- **金额:** ${price} USDC\n\n---\n\n## ✅ 支付完成后\n\n请发送**交易hash**给我，格式：\n\\`\\`\\`\ntx: 0x1234...\n\\`\\`\\`\n\n或直接发送hash：\n\\`\\`\\`\n0x1234abcd...\n\\`\\`\\`\n\n我会验证链上交易后开始处理你的请求。\n\n---\n\n📦 **moltspay:** https://www.npmjs.com/package/moltspay\n🔗 **区块浏览器:** ${explorer}`;\n}\n\n/**\n * 生成简短的支付提醒\n */\nexport function generatePaymentReminder(params: {\n  orderId: string;\n  price: number;\n  recipientAddress: string;\n  chain?: 'base' | 'base_sepolia';\n}): string {\n  const { orderId, price, recipientAddress, chain = 'base' } = params;\n  const chainName = chain === 'base' ? 'Base' : 'Base Sepolia';\n\n  return `⏳ **待支付订单: ${orderId}**\n\n请支付 **${price} USDC** 到:\n- 链: ${chainName}\n- 地址: \\`${recipientAddress}\\`\n\n支付后发送交易hash给我。\n\n---\n💡 没有支付能力？运行 \\`npm install moltspay\\` 获取支付SDK`;\n}\n\n/**\n * 生成钱包创建指南\n */\nexport function generateWalletGuide(): string {\n  return `## 🔐 创建支付钱包\n\n**1. 安装 moltspay:**\n\\`\\`\\`bash\nnpm install moltspay ethers\n\\`\\`\\`\n\n**2. 创建新钱包:**\n\\`\\`\\`javascript\nconst { Wallet } = require('ethers');\n\nconst wallet = Wallet.createRandom();\nconsole.log('地址:', wallet.address);\nconsole.log('私钥:', wallet.privateKey);\n// ⚠️ 请安全保存私钥！\n\\`\\`\\`\n\n**3. 获取 USDC:**\n- 主网: 从交易所提币到你的钱包地址\n- 测试网: 使用 Base Sepolia faucet\n\n**4. 设置环境变量:**\n\\`\\`\\`bash\nexport WALLET_KEY=\"你的私钥\"\n\\`\\`\\`\n\n完成后即可使用 moltspay 进行链上支付！`;\n}\n\n/**\n * 解析用户消息中的交易hash\n */\nexport function extractTransactionHash(message: string): string | null {\n  // 匹配 0x 开头的64位hex\n  const match = message.match(/0x[a-fA-F0-9]{64}/);\n  if (match) return match[0];\n\n  // 匹配 tx: 后面的内容\n  const txMatch = message.match(/tx:\\s*([a-fA-F0-9]{64})/i);\n  if (txMatch) return '0x' + txMatch[1];\n\n  return null;\n}\n\n/**\n * 判断消息是否包含交易hash\n */\nexport function hasTransactionHash(message: string): boolean {\n  return extractTransactionHash(message) !== null;\n}\n"],"mappings":";AAiBO,SAAS,qBAAqB,QAAoC;AACvE,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,QAAQ;AAAA,IACR,cAAc;AAAA,EAChB,IAAI;AAEJ,QAAM,UAAU,UAAU,SAAS,OAAO;AAC1C,QAAM,YAAY,UAAU,SAAS,sBAAY;AACjD,QAAM,WAAW,UAAU,SACvB,6BACA;AAEJ,SAAO,eAAQ,WAAW;AAAA;AAAA;AAAA,0BAGjB,OAAO;AAAA,kBACV,OAAO,SAAS,KAAK,OAAO,MAAM,GAAG,EAAE,IAAI,QAAQ,MAAM;AAAA,oBACvD,KAAK;AAAA,YACR,SAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,aAyBH,OAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,wCAUoB,gBAAgB,OAAO,KAAK;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gBAWzD,SAAS,eAAe,OAAO;AAAA;AAAA,oCAE1B,gBAAgB;AAAA,sBACpB,KAAK;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gDAqBD,QAAQ;AACxB;AAKO,SAAS,wBAAwB,QAK7B;AACT,QAAM,EAAE,SAAS,OAAO,kBAAkB,QAAQ,OAAO,IAAI;AAC7D,QAAM,YAAY,UAAU,SAAS,SAAS;AAE9C,SAAO,4CAAc,OAAO;AAAA;AAAA,uBAEtB,KAAK;AAAA,YACN,SAAS;AAAA,oBACN,gBAAgB;AAAA;AAAA;AAAA;AAAA;AAAA;AAM1B;AAKO,SAAS,sBAA8B;AAC5C,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BT;AAKO,SAAS,uBAAuB,SAAgC;AAErE,QAAM,QAAQ,QAAQ,MAAM,mBAAmB;AAC/C,MAAI,MAAO,QAAO,MAAM,CAAC;AAGzB,QAAM,UAAU,QAAQ,MAAM,0BAA0B;AACxD,MAAI,QAAS,QAAO,OAAO,QAAQ,CAAC;AAEpC,SAAO;AACT;AAKO,SAAS,mBAAmB,SAA0B;AAC3D,SAAO,uBAAuB,OAAO,MAAM;AAC7C;","names":[]}

package/dist/index.d.mts

@@ -1,9 +1,10 @@
 import { C as ChainName, a as ChainConfig, P as PaymentAgentConfig, b as CreateInvoiceParams, I as Invoice, V as VerifyOptions, c as VerifyResult, W as WalletBalance, A as AuditAction, d as AuditEntry } from './index-CZzgdtin.mjs';
 export { E as EIP712TypedData, e as PendingTransfer, f as PermitExecuteResult, g as PermitRequest, h as PermitSignature, S as SecureWalletConfig, i as SecurityLimits, T as TransferParams, j as TransferResult } from './index-CZzgdtin.mjs';
-export { SecureWallet, Wallet } from './wallet/index.mjs';
+export { CreateWalletOptions, CreateWalletResult, PermitData, PermitWallet, PermitWalletConfig, SecureWallet, TransferWithPermitParams, TransferWithPermitResult, Wallet, WalletData, createWallet, formatPermitRequest, getWalletAddress, loadWallet, walletExists } from './wallet/index.mjs';
 export { PermitPayment } from './permit/index.mjs';
 export { CreateOrderParams, MemoryOrderStore, Order, OrderManager, OrderStatus, OrderStore } from './orders/index.mjs';
 export { VerifyPaymentParams, VerifyPaymentResult, getTransactionStatus, verifyPayment, waitForTransaction } from './verify/index.mjs';
+export { PaymentGuideParams, extractTransactionHash, generatePaymentGuide, generatePaymentReminder, generateWalletGuide, hasTransactionHash } from './guide/index.mjs';
 export { CHAINS, ERC20_ABI, getChain, getChainById, listChains } from './chains/index.mjs';
 
 /**
@@ -117,4 +118,251 @@ declare class AuditLog {
     private ensureDir;
 }
 
-export { AuditAction, AuditEntry, AuditLog, ChainConfig, ChainName, CreateInvoiceParams, Invoice, PaymentAgent, PaymentAgentConfig, VerifyOptions, VerifyResult, WalletBalance };
+/**
+ * Receipt - 交易收据生成
+ *
+ * 用于生成标准化的交易收据，便于对账/报销/审计
+ */
+
+interface ReceiptParams {
+    /** 发票号（自动生成或指定） */
+    invoiceId?: string;
+    /** 订单号 */
+    orderId: string;
+    /** 服务名称 */
+    service: string;
+    /** 服务描述 */
+    description?: string;
+    /** 金额 */
+    amount: number;
+    /** Token */
+    token?: 'USDC' | 'USDT' | 'ETH';
+    /** 链 */
+    chain: ChainName;
+    /** 交易 hash */
+    txHash: string;
+    /** 付款方地址 */
+    payerAddress: string;
+    /** 收款方地址 */
+    recipientAddress: string;
+    /** 交付信息 */
+    delivery?: {
+        /** 交付物 URL */
+        url?: string;
+        /** 文件 hash */
+        fileHash?: string;
+        /** 交付时间 */
+        deliveredAt?: string;
+    };
+    /** 额外元数据 */
+    metadata?: Record<string, unknown>;
+}
+interface Receipt {
+    type: 'receipt';
+    version: '1.0';
+    /** 发票号 */
+    invoiceId: string;
+    /** 订单号 */
+    orderId: string;
+    /** 服务 */
+    service: string;
+    description?: string;
+    /** 金额 */
+    amount: string;
+    token: string;
+    /** 链信息 */
+    chain: string;
+    chainId: number;
+    /** 交易信息 */
+    txHash: string;
+    txUrl: string;
+    /** 参与方 */
+    payer: string;
+    recipient: string;
+    /** 时间 */
+    paidAt: string;
+    issuedAt: string;
+    /** 交付信息 */
+    delivery?: {
+        url?: string;
+        fileHash?: string;
+        deliveredAt?: string;
+    };
+    /** 额外元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 生成交易收据
+ */
+declare function generateReceipt(params: ReceiptParams): Receipt;
+/**
+ * 从 Invoice + VerifyResult 生成收据
+ */
+declare function generateReceiptFromInvoice(invoice: Invoice, verifyResult: VerifyResult, delivery?: ReceiptParams['delivery']): Receipt;
+/**
+ * 格式化收据为人类可读消息
+ */
+declare function formatReceiptMessage(receipt: Receipt): string;
+/**
+ * 格式化收据为纯文本（适合飞书/WhatsApp）
+ */
+declare function formatReceiptText(receipt: Receipt): string;
+/**
+ * 格式化收据为 JSON（适合 Agent 解析）
+ */
+declare function formatReceiptJson(receipt: Receipt): string;
+
+/**
+ * Agent 对话模板
+ *
+ * 标准化的 Agent-to-Agent 支付对话模板
+ * 可直接嵌入 prompt 或用于生成对话
+ */
+
+declare const SellerTemplates: {
+    /**
+     * 1. 能力识别 - 询问买方是否有支付能力
+     */
+    askPaymentCapability(): string;
+    /**
+     * 2. 能力协商 - 说明结算方式
+     */
+    explainSettlement(chain?: ChainName): string;
+    /**
+     * 3.1 引导安装 - 第一步安装 SDK
+     */
+    guideInstall(): string;
+    /**
+     * 3.2 确认钱包地址
+     */
+    confirmWalletAddress(address: string): string;
+    /**
+     * 3.3 引导获取资金 - 选择方式
+     */
+    guideFunding(): string;
+    /**
+     * 3.4 引导 Permit 授权
+     */
+    guidePermit(agentAddress: string, suggestedAmount?: number): string;
+    /**
+     * 3.5 确认能力就绪
+     */
+    confirmCapabilityReady(): string;
+    /**
+     * 4. 询问服务需求
+     */
+    askServiceRequirements(serviceName?: string): string;
+    /**
+     * 5. 报价
+     */
+    quote(params: {
+        service: string;
+        price: number;
+        recipientAddress: string;
+        chain?: ChainName;
+    }): string;
+    /**
+     * 7. 验证中
+     */
+    verifying(): string;
+    /**
+     * 7. 验证通过
+     */
+    verificationPassed(amount: string): string;
+    /**
+     * 7. 验证失败
+     */
+    verificationFailed(error: string): string;
+    /**
+     * 8. 交付
+     */
+    deliver(params: {
+        downloadUrl: string;
+        fileHash?: string;
+    }): string;
+    /**
+     * 9. 收据
+     */
+    receipt(receipt: Receipt): string;
+    /**
+     * 10. 结束
+     */
+    end(): string;
+};
+declare const BuyerTemplates: {
+    /**
+     * 0. 发起请求
+     */
+    requestService(service: string): string;
+    /**
+     * 1. 回复无能力
+     */
+    noCapability(): string;
+    /**
+     * 1. 回复有能力
+     */
+    hasCapability(balance?: string): string;
+    /**
+     * 2. 同意引导
+     */
+    agreeToGuide(): string;
+    /**
+     * 3.1 报告钱包创建完成
+     */
+    walletCreated(address: string): string;
+    /**
+     * 3.3 选择 Permit 方式
+     */
+    choosePermit(): string;
+    /**
+     * 3.3 选择直接转账方式
+     */
+    chooseDirectTransfer(): string;
+    /**
+     * 3.4 报告获得授权
+     */
+    permitReceived(amount: number): string;
+    /**
+     * 4. 提交需求
+     */
+    submitRequirements(requirements: string): string;
+    /**
+     * 5. 确认购买
+     */
+    confirmPurchase(): string;
+    /**
+     * 6. 报告已支付
+     */
+    paymentSent(txHash: string, amount: number): string;
+    /**
+     * 8. 确认收到交付
+     */
+    deliveryReceived(): string;
+    /**
+     * 9. 确认收据
+     */
+    receiptReceived(): string;
+    /**
+     * 向 Boss 请求 Permit
+     */
+    requestPermitFromBoss(params: {
+        amount: number;
+        agentAddress: string;
+        deadlineHours?: number;
+        reason?: string;
+    }): string;
+};
+declare const StatusMarkers: {
+    walletReady: string;
+    permitReady: (amount: number) => string;
+    paymentSent: (txHash: string, amount: number) => string;
+    paymentConfirmed: (txHash: string) => string;
+    delivered: (url: string, hash?: string) => string;
+    receiptIssued: (invoiceId: string, txHash: string) => string;
+};
+declare function parseStatusMarker(message: string): {
+    type: string;
+    data: Record<string, string>;
+} | null;
+
+export { AuditAction, AuditEntry, AuditLog, BuyerTemplates, ChainConfig, ChainName, CreateInvoiceParams, Invoice, PaymentAgent, PaymentAgentConfig, type Receipt, type ReceiptParams, SellerTemplates, StatusMarkers, VerifyOptions, VerifyResult, WalletBalance, formatReceiptJson, formatReceiptMessage, formatReceiptText, generateReceipt, generateReceiptFromInvoice, parseStatusMarker };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { C as ChainName, a as ChainConfig, P as PaymentAgentConfig, b as CreateInvoiceParams, I as Invoice, V as VerifyOptions, c as VerifyResult, W as WalletBalance, A as AuditAction, d as AuditEntry } from './index-CZzgdtin.js';
 export { E as EIP712TypedData, e as PendingTransfer, f as PermitExecuteResult, g as PermitRequest, h as PermitSignature, S as SecureWalletConfig, i as SecurityLimits, T as TransferParams, j as TransferResult } from './index-CZzgdtin.js';
-export { SecureWallet, Wallet } from './wallet/index.js';
+export { CreateWalletOptions, CreateWalletResult, PermitData, PermitWallet, PermitWalletConfig, SecureWallet, TransferWithPermitParams, TransferWithPermitResult, Wallet, WalletData, createWallet, formatPermitRequest, getWalletAddress, loadWallet, walletExists } from './wallet/index.js';
 export { PermitPayment } from './permit/index.js';
 export { CreateOrderParams, MemoryOrderStore, Order, OrderManager, OrderStatus, OrderStore } from './orders/index.js';
 export { VerifyPaymentParams, VerifyPaymentResult, getTransactionStatus, verifyPayment, waitForTransaction } from './verify/index.js';
+export { PaymentGuideParams, extractTransactionHash, generatePaymentGuide, generatePaymentReminder, generateWalletGuide, hasTransactionHash } from './guide/index.js';
 export { CHAINS, ERC20_ABI, getChain, getChainById, listChains } from './chains/index.js';
 
 /**
@@ -117,4 +118,251 @@ declare class AuditLog {
     private ensureDir;
 }
 
-export { AuditAction, AuditEntry, AuditLog, ChainConfig, ChainName, CreateInvoiceParams, Invoice, PaymentAgent, PaymentAgentConfig, VerifyOptions, VerifyResult, WalletBalance };
+/**
+ * Receipt - 交易收据生成
+ *
+ * 用于生成标准化的交易收据，便于对账/报销/审计
+ */
+
+interface ReceiptParams {
+    /** 发票号（自动生成或指定） */
+    invoiceId?: string;
+    /** 订单号 */
+    orderId: string;
+    /** 服务名称 */
+    service: string;
+    /** 服务描述 */
+    description?: string;
+    /** 金额 */
+    amount: number;
+    /** Token */
+    token?: 'USDC' | 'USDT' | 'ETH';
+    /** 链 */
+    chain: ChainName;
+    /** 交易 hash */
+    txHash: string;
+    /** 付款方地址 */
+    payerAddress: string;
+    /** 收款方地址 */
+    recipientAddress: string;
+    /** 交付信息 */
+    delivery?: {
+        /** 交付物 URL */
+        url?: string;
+        /** 文件 hash */
+        fileHash?: string;
+        /** 交付时间 */
+        deliveredAt?: string;
+    };
+    /** 额外元数据 */
+    metadata?: Record<string, unknown>;
+}
+interface Receipt {
+    type: 'receipt';
+    version: '1.0';
+    /** 发票号 */
+    invoiceId: string;
+    /** 订单号 */
+    orderId: string;
+    /** 服务 */
+    service: string;
+    description?: string;
+    /** 金额 */
+    amount: string;
+    token: string;
+    /** 链信息 */
+    chain: string;
+    chainId: number;
+    /** 交易信息 */
+    txHash: string;
+    txUrl: string;
+    /** 参与方 */
+    payer: string;
+    recipient: string;
+    /** 时间 */
+    paidAt: string;
+    issuedAt: string;
+    /** 交付信息 */
+    delivery?: {
+        url?: string;
+        fileHash?: string;
+        deliveredAt?: string;
+    };
+    /** 额外元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 生成交易收据
+ */
+declare function generateReceipt(params: ReceiptParams): Receipt;
+/**
+ * 从 Invoice + VerifyResult 生成收据
+ */
+declare function generateReceiptFromInvoice(invoice: Invoice, verifyResult: VerifyResult, delivery?: ReceiptParams['delivery']): Receipt;
+/**
+ * 格式化收据为人类可读消息
+ */
+declare function formatReceiptMessage(receipt: Receipt): string;
+/**
+ * 格式化收据为纯文本（适合飞书/WhatsApp）
+ */
+declare function formatReceiptText(receipt: Receipt): string;
+/**
+ * 格式化收据为 JSON（适合 Agent 解析）
+ */
+declare function formatReceiptJson(receipt: Receipt): string;
+
+/**
+ * Agent 对话模板
+ *
+ * 标准化的 Agent-to-Agent 支付对话模板
+ * 可直接嵌入 prompt 或用于生成对话
+ */
+
+declare const SellerTemplates: {
+    /**
+     * 1. 能力识别 - 询问买方是否有支付能力
+     */
+    askPaymentCapability(): string;
+    /**
+     * 2. 能力协商 - 说明结算方式
+     */
+    explainSettlement(chain?: ChainName): string;
+    /**
+     * 3.1 引导安装 - 第一步安装 SDK
+     */
+    guideInstall(): string;
+    /**
+     * 3.2 确认钱包地址
+     */
+    confirmWalletAddress(address: string): string;
+    /**
+     * 3.3 引导获取资金 - 选择方式
+     */
+    guideFunding(): string;
+    /**
+     * 3.4 引导 Permit 授权
+     */
+    guidePermit(agentAddress: string, suggestedAmount?: number): string;
+    /**
+     * 3.5 确认能力就绪
+     */
+    confirmCapabilityReady(): string;
+    /**
+     * 4. 询问服务需求
+     */
+    askServiceRequirements(serviceName?: string): string;
+    /**
+     * 5. 报价
+     */
+    quote(params: {
+        service: string;
+        price: number;
+        recipientAddress: string;
+        chain?: ChainName;
+    }): string;
+    /**
+     * 7. 验证中
+     */
+    verifying(): string;
+    /**
+     * 7. 验证通过
+     */
+    verificationPassed(amount: string): string;
+    /**
+     * 7. 验证失败
+     */
+    verificationFailed(error: string): string;
+    /**
+     * 8. 交付
+     */
+    deliver(params: {
+        downloadUrl: string;
+        fileHash?: string;
+    }): string;
+    /**
+     * 9. 收据
+     */
+    receipt(receipt: Receipt): string;
+    /**
+     * 10. 结束
+     */
+    end(): string;
+};
+declare const BuyerTemplates: {
+    /**
+     * 0. 发起请求
+     */
+    requestService(service: string): string;
+    /**
+     * 1. 回复无能力
+     */
+    noCapability(): string;
+    /**
+     * 1. 回复有能力
+     */
+    hasCapability(balance?: string): string;
+    /**
+     * 2. 同意引导
+     */
+    agreeToGuide(): string;
+    /**
+     * 3.1 报告钱包创建完成
+     */
+    walletCreated(address: string): string;
+    /**
+     * 3.3 选择 Permit 方式
+     */
+    choosePermit(): string;
+    /**
+     * 3.3 选择直接转账方式
+     */
+    chooseDirectTransfer(): string;
+    /**
+     * 3.4 报告获得授权
+     */
+    permitReceived(amount: number): string;
+    /**
+     * 4. 提交需求
+     */
+    submitRequirements(requirements: string): string;
+    /**
+     * 5. 确认购买
+     */
+    confirmPurchase(): string;
+    /**
+     * 6. 报告已支付
+     */
+    paymentSent(txHash: string, amount: number): string;
+    /**
+     * 8. 确认收到交付
+     */
+    deliveryReceived(): string;
+    /**
+     * 9. 确认收据
+     */
+    receiptReceived(): string;
+    /**
+     * 向 Boss 请求 Permit
+     */
+    requestPermitFromBoss(params: {
+        amount: number;
+        agentAddress: string;
+        deadlineHours?: number;
+        reason?: string;
+    }): string;
+};
+declare const StatusMarkers: {
+    walletReady: string;
+    permitReady: (amount: number) => string;
+    paymentSent: (txHash: string, amount: number) => string;
+    paymentConfirmed: (txHash: string) => string;
+    delivered: (url: string, hash?: string) => string;
+    receiptIssued: (invoiceId: string, txHash: string) => string;
+};
+declare function parseStatusMarker(message: string): {
+    type: string;
+    data: Record<string, string>;
+} | null;
+
+export { AuditAction, AuditEntry, AuditLog, BuyerTemplates, ChainConfig, ChainName, CreateInvoiceParams, Invoice, PaymentAgent, PaymentAgentConfig, type Receipt, type ReceiptParams, SellerTemplates, StatusMarkers, VerifyOptions, VerifyResult, WalletBalance, formatReceiptJson, formatReceiptMessage, formatReceiptText, generateReceipt, generateReceiptFromInvoice, parseStatusMarker };