@nvwa-app/sdk-functions 6.46.0 → 6.48.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { drizzle } from 'drizzle-orm/postgres-js';
 import { CreatePaymentOrderRequest, ProjectPlatformType, PaymentOrderResult } from '@nvwa-app/sdk-shared';
-export { CreatePaymentOrderRequest, PaymentClientContext, PaymentOrderResult, ProjectPlatformType, toPaymentOrderResultFromGateway } from '@nvwa-app/sdk-shared';
+export { CreatePaymentOrderRequest, ParseCreatePaymentOrderRequestResult, PaymentClientContext, PaymentOrderResult, ProjectPlatformType, parseCreatePaymentOrderRequest, toPaymentOrderResultFromGateway } from '@nvwa-app/sdk-shared';
 
 declare function getDb(): ReturnType<typeof drizzle>;
 
@@ -20,6 +20,8 @@ interface AuthUser {
  */
 declare function getRequestUser(req: Request, baseUrlOverride?: string): Promise<AuthUser | null>;
 
+/** 解析失败时抛出 `Error(message)`，便于 `try/catch` 后直接 `buildCreateOrderParams`。 */
+declare function assertCreatePaymentOrderRequest(input: unknown): CreatePaymentOrderRequest;
 /** 支付端类型：与 integrations/payment 中的 supportedPlatforms 一致，用于按端过滤可用 provider。 */
 type PaymentPlatform = "web" | "uniapp" | "wechat-miniprogram" | "alipay-miniprogram";
 interface PaymentGatewayClientOptions {
@@ -62,6 +64,10 @@ interface GetOrderResult {
     raw: Record<string, unknown>;
 }
 declare const PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER = "X-Payment-Gateway-Signature";
+/** 与 `Request.headers` / `Headers` 兼容，仅需 `get(name)`。 */
+type PaymentNotifyHeaderSource = {
+    get(name: string): string | null | undefined;
+};
 interface PaymentSuccessNotifyPayload {
     platformOrderId: string;
     bizOrderId: string;
@@ -73,7 +79,18 @@ interface PaymentSuccessNotifyPayload {
     timestamp: string;
     paidAt: string;
 }
+/**
+ * 底层验签：对原始 UTF-8 body 做 HMAC-SHA256，与 Base64 签名做常量时间比较。
+ * 业务侧优先使用 {@link verifyPaymentNotifySignature}（从请求头取 `X-Payment-Gateway-Signature`）。
+ */
 declare function verifySuccessNotifySignature(rawBody: string, signature: string | null | undefined, secret: string): Promise<boolean>;
+/** 读取 Payment Gateway 回调签名头（去空白；缺失或空串返回 `null`）。 */
+declare function getPaymentGatewayNotifySignature(headers: PaymentNotifyHeaderSource): string | null;
+/**
+ * Payment Gateway 成功回调验签：与建单时 `successNotifySecret` 一致；
+ * 网关对 **原始 JSON 字符串** 计算 HMAC-SHA256，再以 Base64 写入 `X-Payment-Gateway-Signature`。
+ */
+declare function verifyPaymentNotifySignature(rawBody: string, headers: PaymentNotifyHeaderSource, secret: string): Promise<boolean>;
 declare function parseSuccessNotifyPayload(rawBody: string): PaymentSuccessNotifyPayload;
 declare function verifyAndParseSuccessNotifyRequest(request: Request, secret: string): Promise<PaymentSuccessNotifyPayload>;
 interface PaymentGatewayClient {
@@ -129,4 +146,4 @@ interface CapabilityExecuteResponse<Data = unknown> {
  */
 declare function executeCapability<Result = unknown>(capabilityName: string, param?: unknown, options?: ExecuteCapabilityOptions): Promise<Result | undefined>;
 
-export { type AuthUser, type CapabilityExecuteResponse, type CreateOrderParams, type CreateOrderResult, type CreatePaymentOrderServerOptions, type ExecuteCapabilityOptions, type GetAvailableProvidersOptions, type GetOrderResult, PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER, type PaymentGatewayClient, type PaymentGatewayClientOptions, type PaymentPlatform, type PaymentSuccessNotifyPayload, buildCreateOrderParams, createPaymentClient, createPaymentOrderForBusiness, executeCapability, filterProvidersByPlatform, getAvailableProviders, getConfiguredProviders, getDb, getPayment, getRequestUser, parseSuccessNotifyPayload, providerSupportedPlatforms, verifyAndParseSuccessNotifyRequest, verifySuccessNotifySignature };
+export { type AuthUser, type CapabilityExecuteResponse, type CreateOrderParams, type CreateOrderResult, type CreatePaymentOrderServerOptions, type ExecuteCapabilityOptions, type GetAvailableProvidersOptions, type GetOrderResult, PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER, type PaymentGatewayClient, type PaymentGatewayClientOptions, type PaymentNotifyHeaderSource, type PaymentPlatform, type PaymentSuccessNotifyPayload, assertCreatePaymentOrderRequest, buildCreateOrderParams, createPaymentClient, createPaymentOrderForBusiness, executeCapability, filterProvidersByPlatform, getAvailableProviders, getConfiguredProviders, getDb, getPayment, getPaymentGatewayNotifySignature, getRequestUser, parseSuccessNotifyPayload, providerSupportedPlatforms, verifyAndParseSuccessNotifyRequest, verifyPaymentNotifySignature, verifySuccessNotifySignature };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { drizzle } from 'drizzle-orm/postgres-js';
 import { CreatePaymentOrderRequest, ProjectPlatformType, PaymentOrderResult } from '@nvwa-app/sdk-shared';
-export { CreatePaymentOrderRequest, PaymentClientContext, PaymentOrderResult, ProjectPlatformType, toPaymentOrderResultFromGateway } from '@nvwa-app/sdk-shared';
+export { CreatePaymentOrderRequest, ParseCreatePaymentOrderRequestResult, PaymentClientContext, PaymentOrderResult, ProjectPlatformType, parseCreatePaymentOrderRequest, toPaymentOrderResultFromGateway } from '@nvwa-app/sdk-shared';
 
 declare function getDb(): ReturnType<typeof drizzle>;
 
@@ -20,6 +20,8 @@ interface AuthUser {
  */
 declare function getRequestUser(req: Request, baseUrlOverride?: string): Promise<AuthUser | null>;
 
+/** 解析失败时抛出 `Error(message)`，便于 `try/catch` 后直接 `buildCreateOrderParams`。 */
+declare function assertCreatePaymentOrderRequest(input: unknown): CreatePaymentOrderRequest;
 /** 支付端类型：与 integrations/payment 中的 supportedPlatforms 一致，用于按端过滤可用 provider。 */
 type PaymentPlatform = "web" | "uniapp" | "wechat-miniprogram" | "alipay-miniprogram";
 interface PaymentGatewayClientOptions {
@@ -62,6 +64,10 @@ interface GetOrderResult {
     raw: Record<string, unknown>;
 }
 declare const PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER = "X-Payment-Gateway-Signature";
+/** 与 `Request.headers` / `Headers` 兼容，仅需 `get(name)`。 */
+type PaymentNotifyHeaderSource = {
+    get(name: string): string | null | undefined;
+};
 interface PaymentSuccessNotifyPayload {
     platformOrderId: string;
     bizOrderId: string;
@@ -73,7 +79,18 @@ interface PaymentSuccessNotifyPayload {
     timestamp: string;
     paidAt: string;
 }
+/**
+ * 底层验签：对原始 UTF-8 body 做 HMAC-SHA256，与 Base64 签名做常量时间比较。
+ * 业务侧优先使用 {@link verifyPaymentNotifySignature}（从请求头取 `X-Payment-Gateway-Signature`）。
+ */
 declare function verifySuccessNotifySignature(rawBody: string, signature: string | null | undefined, secret: string): Promise<boolean>;
+/** 读取 Payment Gateway 回调签名头（去空白；缺失或空串返回 `null`）。 */
+declare function getPaymentGatewayNotifySignature(headers: PaymentNotifyHeaderSource): string | null;
+/**
+ * Payment Gateway 成功回调验签：与建单时 `successNotifySecret` 一致；
+ * 网关对 **原始 JSON 字符串** 计算 HMAC-SHA256，再以 Base64 写入 `X-Payment-Gateway-Signature`。
+ */
+declare function verifyPaymentNotifySignature(rawBody: string, headers: PaymentNotifyHeaderSource, secret: string): Promise<boolean>;
 declare function parseSuccessNotifyPayload(rawBody: string): PaymentSuccessNotifyPayload;
 declare function verifyAndParseSuccessNotifyRequest(request: Request, secret: string): Promise<PaymentSuccessNotifyPayload>;
 interface PaymentGatewayClient {
@@ -129,4 +146,4 @@ interface CapabilityExecuteResponse<Data = unknown> {
  */
 declare function executeCapability<Result = unknown>(capabilityName: string, param?: unknown, options?: ExecuteCapabilityOptions): Promise<Result | undefined>;
 
-export { type AuthUser, type CapabilityExecuteResponse, type CreateOrderParams, type CreateOrderResult, type CreatePaymentOrderServerOptions, type ExecuteCapabilityOptions, type GetAvailableProvidersOptions, type GetOrderResult, PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER, type PaymentGatewayClient, type PaymentGatewayClientOptions, type PaymentPlatform, type PaymentSuccessNotifyPayload, buildCreateOrderParams, createPaymentClient, createPaymentOrderForBusiness, executeCapability, filterProvidersByPlatform, getAvailableProviders, getConfiguredProviders, getDb, getPayment, getRequestUser, parseSuccessNotifyPayload, providerSupportedPlatforms, verifyAndParseSuccessNotifyRequest, verifySuccessNotifySignature };
+export { type AuthUser, type CapabilityExecuteResponse, type CreateOrderParams, type CreateOrderResult, type CreatePaymentOrderServerOptions, type ExecuteCapabilityOptions, type GetAvailableProvidersOptions, type GetOrderResult, PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER, type PaymentGatewayClient, type PaymentGatewayClientOptions, type PaymentNotifyHeaderSource, type PaymentPlatform, type PaymentSuccessNotifyPayload, assertCreatePaymentOrderRequest, buildCreateOrderParams, createPaymentClient, createPaymentOrderForBusiness, executeCapability, filterProvidersByPlatform, getAvailableProviders, getConfiguredProviders, getDb, getPayment, getPaymentGatewayNotifySignature, getRequestUser, parseSuccessNotifyPayload, providerSupportedPlatforms, verifyAndParseSuccessNotifyRequest, verifyPaymentNotifySignature, verifySuccessNotifySignature };

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER: () => PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER,
+  assertCreatePaymentOrderRequest: () => assertCreatePaymentOrderRequest,
   buildCreateOrderParams: () => buildCreateOrderParams,
   createPaymentClient: () => createPaymentClient,
   createPaymentOrderForBusiness: () => createPaymentOrderForBusiness,
@@ -40,11 +41,14 @@ __export(index_exports, {
   getConfiguredProviders: () => getConfiguredProviders,
   getDb: () => getDb,
   getPayment: () => getPayment,
+  getPaymentGatewayNotifySignature: () => getPaymentGatewayNotifySignature,
   getRequestUser: () => getRequestUser,
+  parseCreatePaymentOrderRequest: () => import_sdk_shared2.parseCreatePaymentOrderRequest,
   parseSuccessNotifyPayload: () => parseSuccessNotifyPayload,
   providerSupportedPlatforms: () => providerSupportedPlatforms,
   toPaymentOrderResultFromGateway: () => import_sdk_shared2.toPaymentOrderResultFromGateway,
   verifyAndParseSuccessNotifyRequest: () => verifyAndParseSuccessNotifyRequest,
+  verifyPaymentNotifySignature: () => verifyPaymentNotifySignature,
   verifySuccessNotifySignature: () => verifySuccessNotifySignature
 });
 module.exports = __toCommonJS(index_exports);
@@ -106,6 +110,11 @@ async function getRequestUser(req, baseUrlOverride) {
 // src/payment.ts
 var import_sdk_shared = require("@nvwa-app/sdk-shared");
 var import_sdk_shared2 = require("@nvwa-app/sdk-shared");
+function assertCreatePaymentOrderRequest(input) {
+  const r = (0, import_sdk_shared.parseCreatePaymentOrderRequest)(input);
+  if (!r.ok) throw new Error(r.error);
+  return r.request;
+}
 var PROVIDER_SUPPORTED_PLATFORMS = {
   "wechat-pay": ["web", "uniapp", "wechat-miniprogram"],
   "alipay-web": ["web", "uniapp"],
@@ -155,6 +164,18 @@ async function verifySuccessNotifySignature(rawBody, signature, secret) {
   const actual = decodeBase64ToBytes(signature);
   return timingSafeEqualBytes(expected, actual);
 }
+function getPaymentGatewayNotifySignature(headers) {
+  const v = headers.get(PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER);
+  const t = typeof v === "string" ? v.trim() : "";
+  return t.length > 0 ? t : null;
+}
+async function verifyPaymentNotifySignature(rawBody, headers, secret) {
+  return verifySuccessNotifySignature(
+    rawBody,
+    getPaymentGatewayNotifySignature(headers),
+    secret
+  );
+}
 function parseSuccessNotifyPayload(rawBody) {
   let parsed;
   try {
@@ -169,8 +190,7 @@ function parseSuccessNotifyPayload(rawBody) {
 }
 async function verifyAndParseSuccessNotifyRequest(request, secret) {
   const rawBody = await request.text();
-  const signature = request.headers.get(PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER);
-  const verified = await verifySuccessNotifySignature(rawBody, signature, secret);
+  const verified = await verifyPaymentNotifySignature(rawBody, request.headers, secret);
   if (!verified) {
     throw new Error("Invalid payment notify signature");
   }
@@ -409,6 +429,7 @@ ${projectCode}`;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER,
+  assertCreatePaymentOrderRequest,
   buildCreateOrderParams,
   createPaymentClient,
   createPaymentOrderForBusiness,
@@ -418,10 +439,13 @@ ${projectCode}`;
   getConfiguredProviders,
   getDb,
   getPayment,
+  getPaymentGatewayNotifySignature,
   getRequestUser,
+  parseCreatePaymentOrderRequest,
   parseSuccessNotifyPayload,
   providerSupportedPlatforms,
   toPaymentOrderResultFromGateway,
   verifyAndParseSuccessNotifyRequest,
+  verifyPaymentNotifySignature,
   verifySuccessNotifySignature
 });

package/dist/index.mjs

@@ -53,8 +53,19 @@ async function getRequestUser(req, baseUrlOverride) {
 }
 
 // src/payment.ts
-import { toPaymentOrderResultFromGateway } from "@nvwa-app/sdk-shared";
-import { toPaymentOrderResultFromGateway as toPaymentOrderResultFromGateway2 } from "@nvwa-app/sdk-shared";
+import {
+  parseCreatePaymentOrderRequest,
+  toPaymentOrderResultFromGateway
+} from "@nvwa-app/sdk-shared";
+import {
+  parseCreatePaymentOrderRequest as parseCreatePaymentOrderRequest2,
+  toPaymentOrderResultFromGateway as toPaymentOrderResultFromGateway2
+} from "@nvwa-app/sdk-shared";
+function assertCreatePaymentOrderRequest(input) {
+  const r = parseCreatePaymentOrderRequest(input);
+  if (!r.ok) throw new Error(r.error);
+  return r.request;
+}
 var PROVIDER_SUPPORTED_PLATFORMS = {
   "wechat-pay": ["web", "uniapp", "wechat-miniprogram"],
   "alipay-web": ["web", "uniapp"],
@@ -104,6 +115,18 @@ async function verifySuccessNotifySignature(rawBody, signature, secret) {
   const actual = decodeBase64ToBytes(signature);
   return timingSafeEqualBytes(expected, actual);
 }
+function getPaymentGatewayNotifySignature(headers) {
+  const v = headers.get(PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER);
+  const t = typeof v === "string" ? v.trim() : "";
+  return t.length > 0 ? t : null;
+}
+async function verifyPaymentNotifySignature(rawBody, headers, secret) {
+  return verifySuccessNotifySignature(
+    rawBody,
+    getPaymentGatewayNotifySignature(headers),
+    secret
+  );
+}
 function parseSuccessNotifyPayload(rawBody) {
   let parsed;
   try {
@@ -118,8 +141,7 @@ function parseSuccessNotifyPayload(rawBody) {
 }
 async function verifyAndParseSuccessNotifyRequest(request, secret) {
   const rawBody = await request.text();
-  const signature = request.headers.get(PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER);
-  const verified = await verifySuccessNotifySignature(rawBody, signature, secret);
+  const verified = await verifyPaymentNotifySignature(rawBody, request.headers, secret);
   if (!verified) {
     throw new Error("Invalid payment notify signature");
   }
@@ -357,6 +379,7 @@ ${projectCode}`;
 }
 export {
   PAYMENT_SUCCESS_NOTIFY_SIGNATURE_HEADER,
+  assertCreatePaymentOrderRequest,
   buildCreateOrderParams,
   createPaymentClient,
   createPaymentOrderForBusiness,
@@ -366,10 +389,13 @@ export {
   getConfiguredProviders,
   getDb,
   getPayment,
+  getPaymentGatewayNotifySignature,
   getRequestUser,
+  parseCreatePaymentOrderRequest2 as parseCreatePaymentOrderRequest,
   parseSuccessNotifyPayload,
   providerSupportedPlatforms,
   toPaymentOrderResultFromGateway2 as toPaymentOrderResultFromGateway,
   verifyAndParseSuccessNotifyRequest,
+  verifyPaymentNotifySignature,
   verifySuccessNotifySignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nvwa-app/sdk-functions",
-  "version": "6.46.0",
+  "version": "6.48.0",
   "description": "NVWA Edge Functions SDK: db, payment gateway, auth, provider list. Use in Deno: import from 'npm:@nvwa-app/sdk-functions'.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -24,7 +24,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@nvwa-app/sdk-shared": "^6.46.0",
+    "@nvwa-app/sdk-shared": "^6.48.0",
     "drizzle-orm": "^0.44.7",
     "postgres": "^3.4.8"
   },