@xiashe/sdk 0.1.18 → 0.1.19

package/alipayWallet.mjs

@@ -17,9 +17,106 @@ const SAFE_OFFICIAL_FAILURE_CODES = new Set([
   'PAYMENT_NEEDED_REJECTED',
   'SYSTEM_ERROR',
   'BUYER_IDENTITY_REJECTED',
-  'WALLET_NOT_READY'
+  'WALLET_NOT_READY',
+  // AI收 payment.verify business errors. These can be returned after the
+  // wallet has paid and retries the protected resource with Payment-Proof.
+  'INVALID_PARAMETER',
+  'CLIENT_SESSION_IS_EMPTY',
+  'PAYMENT_PROOF_AGENT_MISMATCH',
+  'PAYMENT_PROOF_BUYER_MISMATCH',
+  'PAYMENT_PROOF_EMPTY',
+  'PAYMENT_PROOF_ID_MISMATCH',
+  'PAYMENT_PROOF_INVALID',
+  'PAYMENT_PROOF_NOT_FOUND',
+  'PAYMENT_PROOF_STATUS_INVALID',
+  'PAYMENT_PROOF_TRADE_NO_MISMATCH',
+  'TRADE_NOT_FOUND',
+  'TRADE_NO_EMPTY',
+  'TRADE_NO_INVALID',
+  'TRADE_STATUS_CLOSED',
+  'TRADE_STATUS_UNPAID',
+  // AI收 fulfillment.confirm business errors. These do not revoke a
+  // delivered entitlement, but do need an operator-visible diagnosis.
+  'SELLER_IDENTITY_MISMATCH',
+  'SELLER_ID_EMPTY',
+  'TRADE_STATUS_INVALID'
 ]);
 
+const OFFICIAL_ERROR_DIAGNOSES = {
+  PAYMENT_NEEDED_REJECTED: {
+    stage: 'alipay_bill_validation',
+    nextStep: '核对支付宝平台中该 APPID 的应用公钥、service_id、收款方 2088 seller_id 和线上接入状态；修复后必须创建新订单再测试。'
+  },
+  CLIENT_SESSION_IS_EMPTY: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '买方 CLI 未传回有效 client_session；升级官方支付宝支付组件后，用新订单重新发起付款。'
+  },
+  PAYMENT_PROOF_AGENT_MISMATCH: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付凭证与当前 Agent 商户身份不一致；确认付款与重试使用同一官方钱包运行时后，以新订单重试。'
+  },
+  PAYMENT_PROOF_BUYER_MISMATCH: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付买家与凭证买家不一致；不要复用凭证，请在同一支付宝买家身份下重新发起付款。'
+  },
+  PAYMENT_PROOF_ID_MISMATCH: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: 'Payment-Proof 中的卖家身份与本 Skill 配置不一致；核对 APPID、2088 seller_id 和 service_id。'
+  },
+  PAYMENT_PROOF_EMPTY: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '官方钱包没有返回支付凭证；请停止，不要手工补造凭证，并用受支持运行时重新发起。'
+  },
+  PAYMENT_PROOF_INVALID: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付宝返回的支付凭证格式无效；请使用最新官方买方组件，并创建新订单重试。'
+  },
+  PAYMENT_PROOF_NOT_FOUND: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付凭证不存在或已过期；不要重复提交旧凭证，创建新订单后重新付款。'
+  },
+  PAYMENT_PROOF_STATUS_INVALID: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付凭证已失效或已被使用；请创建新订单重新付款。'
+  },
+  PAYMENT_PROOF_TRADE_NO_MISMATCH: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付凭证与交易号不匹配；不要重放该凭证，创建新订单后重新付款。'
+  },
+  TRADE_NOT_FOUND: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付宝找不到该交易；先查询官方钱包本地状态，未创建交易时用新订单重新发起。'
+  },
+  TRADE_NO_EMPTY: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '官方钱包未返回交易号；当前交易不可继续，请创建新订单重新发起。'
+  },
+  TRADE_NO_INVALID: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '官方钱包返回的交易号格式无效；升级官方买方组件后以新订单重试。'
+  },
+  TRADE_STATUS_CLOSED: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '该交易已关闭；不要重试旧订单，请创建新订单重新付款。'
+  },
+  TRADE_STATUS_UNPAID: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '交易尚未完成付款；如本地有查询凭证则运行 status，否则创建新订单重新发起。'
+  },
+  SELLER_IDENTITY_MISMATCH: {
+    stage: 'merchant_fulfillment_confirmation',
+    nextStep: '已交付的 Skill 权益不会撤销；运营方应核对卖家 APPID、2088 seller_id 与交易卖方身份。'
+  },
+  SELLER_ID_EMPTY: {
+    stage: 'merchant_fulfillment_confirmation',
+    nextStep: '已交付的 Skill 权益不会撤销；运营方应检查商户应用签名与卖家身份配置。'
+  },
+  TRADE_STATUS_INVALID: {
+    stage: 'merchant_fulfillment_confirmation',
+    nextStep: '已交付的 Skill 权益不会撤销；运营方应查询支付宝交易状态后处理履约回执。'
+  }
+};
+
 export class AlipayWalletError extends Error {
   constructor(code, message, options = {}) {
     super(message);
@@ -244,17 +341,48 @@ function walletFailureCode(stdout, stderr, exitCode) {
  */
 function safeOfficialFailureCode(stdout, stderr) {
   const output = `${stdout}\n${stderr}`;
-  const candidate = output.match(/(?:"(?:errorCode|code)"|\b(?:errorCode|code)\b)\s*[:=]\s*["']?([A-Z][A-Z0-9_]{2,80})/i)?.[1]?.toUpperCase() || '';
-  return SAFE_OFFICIAL_FAILURE_CODES.has(candidate) ? candidate : null;
+  const candidates = [
+    ...output.matchAll(/(?:"(?:errorCode|code|sub_code|previous_error)"|\b(?:errorCode|code|sub_code|previous_error)\b)\s*[:=]\s*["']?([A-Z][A-Z0-9_]{2,80})/ig)
+  ].map((match) => match[1].toUpperCase());
+  return candidates.find((candidate) => SAFE_OFFICIAL_FAILURE_CODES.has(candidate)) || null;
+}
+
+/** Codes generated by XiaShe from the signed merchant verification response. */
+function safeMerchantDiagnosticCode(stdout, stderr) {
+  const output = `${stdout}\n${stderr}`;
+  const candidates = [...output.matchAll(/\b(ALIPAY_(?:VERIFY|FULFILLMENT)_[A-Z0-9_]{2,180})\b/g)]
+    .map((match) => match[1]);
+  return candidates.find((candidate) =>
+    /^ALIPAY_(?:VERIFY|FULFILLMENT)_(?:PAYMENT_PROOF_INACTIVE|(?:SYSTEM_ERROR|INVALID_PARAMETER|CLIENT_SESSION_IS_EMPTY|PAYMENT_PROOF_AGENT_MISMATCH|PAYMENT_PROOF_BUYER_MISMATCH|PAYMENT_PROOF_EMPTY|PAYMENT_PROOF_ID_MISMATCH|PAYMENT_PROOF_INVALID|PAYMENT_PROOF_NOT_FOUND|PAYMENT_PROOF_STATUS_INVALID|PAYMENT_PROOF_TRADE_NO_MISMATCH|SELLER_IDENTITY_MISMATCH|SELLER_ID_EMPTY|TRADE_NOT_FOUND|TRADE_NO_EMPTY|TRADE_NO_INVALID|TRADE_STATUS_CLOSED|TRADE_STATUS_UNPAID|TRADE_STATUS_INVALID)|GATEWAY_(?:20000|20001|40001|40002|40003|40004|40005|40006)(?:_[A-Z0-9_]{2,100})?)$/.test(candidate)
+  ) || null;
 }
 
 function paymentFailureDiagnosis(failureCode, stdout, stderr) {
   const officialCode = safeOfficialFailureCode(stdout, stderr);
+  const merchantDiagnostic = safeMerchantDiagnosticCode(stdout, stderr);
   const base = {
     code: failureCode,
     stage: 'official_wallet_trade_creation',
     nextStep: '不要重复付款；保留诊断代码和本次 attemptId 以便定位。'
   };
+  if (officialCode && OFFICIAL_ERROR_DIAGNOSES[officialCode]) {
+    return {
+      ...base,
+      ...OFFICIAL_ERROR_DIAGNOSES[officialCode],
+      officialCode
+    };
+  }
+  if (merchantDiagnostic) {
+    const fulfillment = merchantDiagnostic.startsWith('ALIPAY_FULFILLMENT_');
+    return {
+      ...base,
+      stage: fulfillment ? 'merchant_fulfillment_confirmation' : 'merchant_payment_proof_verification',
+      merchantDiagnostic,
+      nextStep: fulfillment
+        ? 'Skill 权益已交付；运营方应按商家验证诊断处理履约回执，买家无需重复付款。'
+        : '商家已返回支付宝验凭证诊断；不要手工补造凭证，按诊断修复后创建新订单重新付款。'
+    };
+  }
   if (failureCode === 'payment_needed_rejected') {
     return {
       ...base,
@@ -307,6 +435,7 @@ function paymentFailureUserVisible(diagnosis) {
     `诊断代码：${diagnosis.code}`,
     `失败阶段：${diagnosis.stage}`,
     ...(diagnosis.officialCode ? [`官方返回代码：${diagnosis.officialCode}`] : []),
+    ...(diagnosis.merchantDiagnostic ? [`商家验证诊断：${diagnosis.merchantDiagnostic}`] : []),
     `下一步：${diagnosis.nextStep}`
   ];
   return lines.join('\n');
@@ -467,16 +596,21 @@ export async function payAlipay402Resource(input, options = {}) {
   const result = paymentStatusFromOutput(walletInvocation.stdout, walletInvocation.stderr);
   const commandFailed = walletInvocation.exitCode !== 0 && result.status === 'unknown';
   const status = commandFailed ? 'wallet_command_failed' : result.status;
+  const failed = commandFailed || status === 'failed';
   const officialMedia = ['pending_confirmation', 'completed'].includes(status)
     ? await officialWalletMedia(walletInvocation.stdout, walletInvocation.stderr)
     : null;
   state.status = status;
   state.queryCredential = result.credential;
+  state.lastFailureCode = failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : null;
+  state.lastDiagnosis = failed
+    ? paymentFailureDiagnosis(state.lastFailureCode, walletInvocation.stdout, walletInvocation.stderr)
+    : null;
+  state.lastWalletDiagnostic = result.diagnostic;
   state.updatedAt = new Date().toISOString();
   await writePaymentState(state, options);
   if (status === 'completed') await rm(paths.paymentNeededPath, { force: true });
-  const failed = commandFailed || status === 'failed';
-  const failureCode = failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : undefined;
+  const failureCode = failed ? state.lastFailureCode : undefined;
   return publicPaymentResult(state, status, result.diagnostic, {
     commandFailed: failed,
     failureCode,
@@ -514,19 +648,24 @@ export async function queryAlipay402Resource(input, options = {}) {
   const result = paymentStatusFromOutput(walletInvocation.stdout, walletInvocation.stderr);
   const commandFailed = walletInvocation.exitCode !== 0 && result.status === 'unknown';
   const status = commandFailed ? 'wallet_command_failed' : result.status;
+  const failed = commandFailed || status === 'failed';
   const officialMedia = ['pending_confirmation', 'completed'].includes(status)
     ? await officialWalletMedia(walletInvocation.stdout, walletInvocation.stderr)
     : null;
   state.status = status;
   state.queryCredential = result.credential || state.queryCredential;
+  state.lastFailureCode = failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : null;
+  state.lastDiagnosis = failed
+    ? paymentFailureDiagnosis(state.lastFailureCode, walletInvocation.stdout, walletInvocation.stderr)
+    : null;
+  state.lastWalletDiagnostic = result.diagnostic;
   state.updatedAt = new Date().toISOString();
   await writePaymentState(state, options);
   if (status === 'completed') {
     const { paymentNeededPath } = statePaths(resourceUrl, options);
     await rm(paymentNeededPath, { force: true });
   }
-  const failed = commandFailed || status === 'failed';
-  const failureCode = failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : undefined;
+  const failureCode = failed ? state.lastFailureCode : undefined;
   return publicPaymentResult(state, status, result.diagnostic, {
     commandFailed: failed,
     failureCode,
@@ -537,3 +676,36 @@ export async function queryAlipay402Resource(input, options = {}) {
     officialMedia
   });
 }
+
+/**
+ * Read-only support output. It never invokes the wallet, replays a 402
+ * request, exposes a query credential, or returns the private protocol file.
+ */
+export async function diagnoseAlipay402Resource(input, options = {}) {
+  const resourceUrl = normalizeResourceUrl(input?.resourceUrl);
+  const state = await readPaymentState(resourceUrl, options);
+  if (!state) {
+    return {
+      ok: false,
+      status: 'no_local_attempt',
+      provider: 'alipay-agent-payment',
+      walletInvoked: false,
+      message: '没有找到本地付款尝试；请不要因此重复付款。'
+    };
+  }
+  return {
+    ok: state.status !== 'failed' && state.status !== 'wallet_command_failed',
+    status: state.status || 'unknown',
+    provider: 'alipay-agent-payment',
+    attemptId: `alipay-402:${state.resourceDigest.slice(0, 16)}`,
+    walletInvoked: state.status !== 'started',
+    queryAvailable: Boolean(state.queryCredential?.value),
+    diagnostic: state.lastWalletDiagnostic || 'payment_state_recorded',
+    ...(state.lastFailureCode ? { failureCode: state.lastFailureCode } : {}),
+    ...(state.lastDiagnosis ? {
+      diagnosis: state.lastDiagnosis,
+      userVisible: paymentFailureUserVisible(state.lastDiagnosis)
+    } : {}),
+    updatedAt: state.updatedAt || null
+  };
+}

package/index.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { ConvexHttpClient } from 'convex/browser';
 import { anyApi as api } from 'convex/server';
 
-export const VERSION = '0.1.18';
+export const VERSION = '0.1.19';
 
 export const DEFAULTS = {
   cn: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/sdk",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "type": "module",
   "main": "index.mjs",
   "exports": {