moltspay 1.6.0 → 2.4.0

package/schemas/moltspay.services.schema.json

@@ -32,21 +32,162 @@
         },
         "chain": {
           "type": "string",
-          "enum": ["base", "polygon", "base_sepolia", "tempo_moderato", "bnb", "bnb_testnet", "solana", "solana_devnet"],
+          "enum": ["base", "polygon", "base_sepolia", "tempo_moderato", "bnb", "bnb_testnet", "solana", "solana_devnet", "alipay", "wechat", "balance"],
           "default": "base",
-          "description": "Single chain mode (use 'chains' for multi-chain)"
+          "description": "Single chain mode (use 'chains' for multi-chain). 'alipay'/'wechat' are fiat rails (2.0+/2.1+), 'balance' is the custodial rail (2.2+), none are blockchains."
         },
         "chains": {
           "type": "array",
-          "description": "Supported chains. EVM chains use 'wallet', Solana chains use 'solana_wallet'.",
+          "description": "Supported chains/rails. EVM chains use 'wallet', Solana chains use 'solana_wallet', 'alipay' (2.0+) uses 'provider.alipay', 'wechat' (2.1+) uses 'provider.wechat'.",
           "items": {
             "type": "string",
-            "enum": ["base", "polygon", "base_sepolia", "tempo_moderato", "bnb", "bnb_testnet", "solana", "solana_devnet"]
+            "enum": ["base", "polygon", "base_sepolia", "tempo_moderato", "bnb", "bnb_testnet", "solana", "solana_devnet", "alipay", "wechat", "balance"]
           },
           "examples": [
             ["base", "polygon", "solana_devnet"],
-            ["base", "base_sepolia", "solana", "solana_devnet"]
+            ["base", "base_sepolia", "solana", "solana_devnet"],
+            ["base", "polygon", "alipay"]
           ]
+        },
+        "alipay": {
+          "type": "object",
+          "description": "Alipay AI 收 provider config (2.0+). Required when 'chains' contains 'alipay'.",
+          "required": ["seller_id", "app_id", "seller_name", "service_id_default", "private_key_path", "alipay_public_key_path"],
+          "properties": {
+            "seller_id": {
+              "type": "string",
+              "pattern": "^[0-9]{16}$",
+              "description": "Merchant Alipay ID (16 digits)"
+            },
+            "app_id": {
+              "type": "string",
+              "pattern": "^[0-9]{16}$",
+              "description": "Application ID from Alipay Open Platform"
+            },
+            "seller_name": {
+              "type": "string",
+              "description": "Merchant legal name (shown in 'method.seller_name' of the 402 challenge)"
+            },
+            "service_id_default": {
+              "type": "string",
+              "description": "Default service_id when a service entry doesn't override it (e.g. 'API_XXXXXXXXXXXXXXXX')"
+            },
+            "private_key_path": {
+              "type": "string",
+              "description": "Path to the RSA2 merchant private key PEM file (relative to moltspay.services.json)"
+            },
+            "alipay_public_key_path": {
+              "type": "string",
+              "description": "Path to the Alipay platform public key PEM file (relative to moltspay.services.json)"
+            },
+            "gateway_url": {
+              "type": "string",
+              "format": "uri",
+              "default": "https://openapi.alipay.com/gateway.do",
+              "description": "Open API gateway URL (use 'https://openapi.alipaydev.com/gateway.do' for sandbox)"
+            },
+            "sign_type": {
+              "type": "string",
+              "enum": ["RSA2"],
+              "default": "RSA2",
+              "description": "Signature algorithm. Only RSA2 is supported in 2.0."
+            }
+          }
+        },
+        "wechat": {
+          "type": "object",
+          "description": "WeChat Pay v3 Native provider config (2.1+). Required when 'chains' contains 'wechat'.",
+          "required": ["mchid", "appid", "serial_no", "private_key_path", "notify_url"],
+          "properties": {
+            "mchid": {
+              "type": "string",
+              "description": "Merchant id (商户号)"
+            },
+            "appid": {
+              "type": "string",
+              "description": "App id (official account / mini-program / app)"
+            },
+            "serial_no": {
+              "type": "string",
+              "description": "Merchant API certificate serial number"
+            },
+            "private_key_path": {
+              "type": "string",
+              "description": "Path to the merchant RSA private key PEM file (relative to moltspay.services.json)"
+            },
+            "platform_public_key_path": {
+              "type": "string",
+              "description": "Path to the WeChat platform certificate public key PEM (enables response verification)"
+            },
+            "apiv3_key": {
+              "type": "string",
+              "minLength": 32,
+              "maxLength": 32,
+              "description": "APIv3 key (32 bytes). Only needed for callback decryption (Phase 2)"
+            },
+            "notify_url": {
+              "type": "string",
+              "format": "uri",
+              "description": "Async result notify URL. Required by Native order create even when polling."
+            },
+            "api_base": {
+              "type": "string",
+              "format": "uri",
+              "default": "https://api.mch.weixin.qq.com",
+              "description": "Open API base URL"
+            }
+          }
+        },
+        "balance": {
+          "type": "object",
+          "description": "Custodial balance rail config (2.2+). Required when 'chains' contains 'balance'. Enabling requires Node.js >= 22.5.",
+          "required": ["db_path"],
+          "properties": {
+            "db_path": {
+              "type": "string",
+              "description": "SQLite ledger file path (relative to moltspay.services.json); created on first start"
+            },
+            "currency": {
+              "type": "string",
+              "enum": ["USD", "CNY"],
+              "default": "USD",
+              "description": "Ledger quote currency. Recorded once and enforced on reopen (a mismatch refuses to start). CNY funds 1:1 from WeChat (payer_total is fen)."
+            },
+            "single_limit": {
+              "type": "string",
+              "pattern": "^\\d+(\\.\\d{1,2})?$",
+              "default": "5.00",
+              "description": "Default per-transaction limit for new buyers (decimal string, ledger currency)"
+            },
+            "daily_limit": {
+              "type": "string",
+              "pattern": "^\\d+(\\.\\d{1,2})?$",
+              "default": "10.00",
+              "description": "Default daily limit for new buyers (decimal string, ledger currency)"
+            },
+            "topup_packs": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$" },
+              "description": "Offered recharge amounts in ledger currency (2.3+), e.g. [\"20.00\", \"50.00\"]"
+            },
+            "default_pack": {
+              "type": "string",
+              "pattern": "^\\d+(\\.\\d{1,2})?$",
+              "description": "Pack the client auto-selects when a 402 finds an insufficient balance (2.3+). Must be one of topup_packs."
+            },
+            "auto_topup_max": {
+              "type": "string",
+              "pattern": "^\\d+(\\.\\d{1,2})?$",
+              "description": "Ceiling on client auto-topup without explicit pack selection (2.3+). Must be >= the largest topup_pack."
+            },
+            "auth_mode": {
+              "type": "string",
+              "enum": ["off", "shadow", "enforce"],
+              "default": "off",
+              "description": "Balance spend authentication (2.4+). 'off': signature not checked (default, backward-compatible; buyer_id keeps bearer semantics). 'shadow': verify per-request signatures and log what would be denied, without blocking (use to confirm every client signs before tightening). 'enforce': reject unsigned/invalid/wrong-signer deductions with 401. The account's signer address is TOFU-bound on first signed use and anchored to the WeChat payer openid at top-up."
+            }
+          }
         }
       }
     },
@@ -74,7 +215,43 @@
           "price": { "type": "number", "minimum": 0, "description": "Price in currency units" },
           "currency": { "type": "string", "enum": ["USDC", "USDT"], "default": "USDC" },
           "input": { "type": "object", "description": "Input parameters schema" },
-          "output": { "type": "object", "description": "Output schema" }
+          "output": { "type": "object", "description": "Output schema" },
+          "alipay": {
+            "type": "object",
+            "description": "Alipay AI 收 per-service config (2.0+). Set when this service accepts CNY payments.",
+            "required": ["price_cny", "goods_name"],
+            "properties": {
+              "service_id": {
+                "type": "string",
+                "description": "Per-service service_id (defaults to provider.alipay.service_id_default)"
+              },
+              "price_cny": {
+                "type": "string",
+                "pattern": "^\\d+(\\.\\d{1,2})?$",
+                "description": "CNY price as decimal string in 元 (e.g. '7.00' = 7 CNY, NOT cents)"
+              },
+              "goods_name": {
+                "type": "string",
+                "description": "Goods name shown to the user in the Alipay app"
+              }
+            }
+          },
+          "wechat": {
+            "type": "object",
+            "description": "WeChat Pay Native per-service config (2.1+). Set when this service accepts CNY payments.",
+            "required": ["price_cny", "description"],
+            "properties": {
+              "price_cny": {
+                "type": "string",
+                "pattern": "^\\d+(\\.\\d{1,2})?$",
+                "description": "CNY price as decimal string in yuan (e.g. '10.00' = 10 CNY, NOT fen)"
+              },
+              "description": {
+                "type": "string",
+                "description": "Order description shown to the payer in the WeChat app"
+              }
+            }
+          }
         }
       }
     }
@@ -90,6 +267,34 @@
       "services": [
         { "id": "text-to-video", "function": "textToVideo", "price": 0.99, "currency": "USDC" }
       ]
+    },
+    {
+      "provider": {
+        "name": "My Shop",
+        "wallet": "0x0000000000000000000000000000000000000000",
+        "chains": ["base", "polygon", "alipay"],
+        "alipay": {
+          "seller_id": "2088000000000000",
+          "app_id": "2021000000000000",
+          "seller_name": "Example Merchant Co., Ltd.",
+          "service_id_default": "API_XXXXXXXXXXXXXXXX",
+          "private_key_path": "./cert/ALIPAY_PRIVATE_KEY.txt",
+          "alipay_public_key_path": "./cert/ALIPAY_PUBLIC_KEY.txt"
+        }
+      },
+      "services": [
+        {
+          "id": "text-to-video",
+          "function": "textToVideo",
+          "price": 0.99,
+          "currency": "USDC",
+          "alipay": {
+            "service_id": "API_XXXXXXXXXXXXXXXX",
+            "price_cny": "7.00",
+            "goods_name": "Demo Video"
+          }
+        }
+      ]
     }
   ]
 }

package/scripts/postinstall.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/*
+ * postinstall — greet, then provision the alipay-bot CLI.
+ *
+ * alipay-bot is a runtime dependency of the Alipay payment rail. It is NOT on
+ * npm (Alipay distributes it from their own CDN) and is licensed UNLICENSED, so
+ * it can neither be a package.json dependency nor be bundled into this package.
+ * Instead, installing moltspay provisions it automatically by invoking the
+ * @alipay/agent-payment helper's `install-cli`, which downloads the CLI directly
+ * from Alipay's CDN onto THIS machine — we never redistribute it ourselves.
+ *
+ * The user opted into this by installing moltspay (alipay-bot is a declared
+ * dependency of the Alipay rail), so provisioning it is part of that install.
+ *
+ * Best-effort by design: provisioning failure (offline / CDN unreachable) prints
+ * an actionable notice but NEVER fails `npm install`. The runtime `ensureCli`
+ * gate is the real enforcement point and re-states the one command to run.
+ *
+ * Opt out with MOLTSPAY_SKIP_CLI_INSTALL=1 (e.g. CI / sandboxes).
+ */
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const banner = `
+╔══════════════════════════════════════════════════════════════╗
+║                                                              ║
+║   🎉  Thanks for installing MoltsPay!                        ║
+║                                                              ║
+║   Quick Start:                                               ║
+║     npx moltspay init          # Setup wallet                ║
+║     npx moltspay status        # Check balance               ║
+║     npx moltspay validate .    # Validate service config     ║
+║                                                              ║
+║   📖 Docs: https://moltspay.com/docs                         ║
+║   💬 Support: https://discord.gg/QwCJgVBxVK                  ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+`;
+console.log(banner);
+
+const PROVISION_HINT = 'npx -y @alipay/agent-payment install-cli';
+
+function warnManual(reason) {
+  console.warn(
+    `\n[moltspay] alipay-bot CLI 未能自动安装（${reason}）。\n` +
+      `           Alipay 支付轨在使用前需手动安装：\n` +
+      `             ${PROVISION_HINT}\n`,
+  );
+}
+
+if (process.env.MOLTSPAY_SKIP_CLI_INSTALL === '1') {
+  console.log('[moltspay] MOLTSPAY_SKIP_CLI_INSTALL=1 — 跳过 alipay-bot 自动安装。');
+  console.log(`[moltspay] 需要时手动安装：${PROVISION_HINT}`);
+  process.exit(0);
+}
+
+console.log('[moltspay] 正在从支付宝官方 CDN 安装 alipay-bot CLI（Alipay 支付轨所需）…');
+
+// Prefer the helper we already pulled in as a declared dependency (no extra
+// network for the helper itself). Fall back to `npx` if it isn't resolvable
+// (odd layout / installed with --ignore-scripts on the dep).
+let result;
+let helperCli = null;
+try {
+  const helperPkgJson = require.resolve('@alipay/agent-payment/package.json');
+  const helperDir = path.dirname(helperPkgJson);
+  const bin = JSON.parse(fs.readFileSync(helperPkgJson, 'utf8')).bin;
+  const rel = typeof bin === 'string' ? bin : bin && bin['agent-payment'];
+  if (rel) helperCli = path.join(helperDir, rel);
+} catch {
+  helperCli = null;
+}
+
+if (helperCli && fs.existsSync(helperCli)) {
+  result = spawnSync(process.execPath, [helperCli, 'install-cli'], { stdio: 'inherit' });
+} else {
+  const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+  result = spawnSync(npx, ['-y', '@alipay/agent-payment', 'install-cli'], { stdio: 'inherit' });
+}
+
+if (!result || result.error || result.status !== 0) {
+  warnManual(result && result.error ? result.error.message : '离线或无法访问 *.alipay.com');
+} else {
+  console.log('[moltspay] alipay-bot CLI 安装完成。');
+}
+
+// Never block the install over an optional rail's provisioning.
+process.exit(0);