@vobs/payment 0.1.0

package/dist/jeepay.js

@@ -0,0 +1,205 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * Jeepay (Jiquan Payment) aggregator driver — open-source aggregator payment system (LGPL-3.0).
+ *
+ * Integration shape: merchant business system → Jeepay payment gateway (self-hosted or official cloud pay.jeepay.vip).
+ * Docs: docs.jeequan.com/docs/jeepay/payment_api (refer to the latest official docs for field details).
+ *
+ * Scene mapping (wayCode → OrderInit):
+ *  - `pc` (no openid) → `WX_NATIVE` / `ALI_QR` → payDataType=codeUrl → `{kind:'qr'}`
+ *  - `h5` + openid (official account) → `WX_JSAPI` → payDataType=wxpay → `{kind:'jsapi'}`
+ *  - `h5` (no openid) → `ALI_WAP` / `WX_H5` → payDataType=payUrl → `{kind:'redirect'}`
+ *  - `miniapp` (webview) → `WX_LITE` → payDataType=wxpay → `{kind:'jsapi'}`
+ *  - extras.wayCode can be set explicitly (the business decides WeChat/Alipay channel)
+ *
+ * Security:
+ *  - Request/callback signing: MD5 (non-empty params in ASCII lexicographic order + &key=appSecret → uppercase MD5)
+ *  - Callbacks use the channel self-verification path; Jeepay notifications have no unique ID,
+ *    so anti-replay relies on signature verification + HTTPS + state-machine idempotency
+ *    (duplicate notifications for an already-paid order return success without re-booking)
+ *
+ * Dependencies: node:crypto (MD5). Zero third-party.
+ */
+import { createHash } from 'node:crypto';
+/** Primitive value → string (params only allow primitives; objects/functions excluded). */
+function primitiveString(v) {
+    return String(v);
+}
+/** Parse form-encoded / object payloads → string param table. */
+function toParams(payload) {
+    const out = {};
+    if (typeof payload === 'string') {
+        for (const pair of payload.split('&')) {
+            const eq = pair.indexOf('=');
+            if (eq > 0) {
+                const k = decodeURIComponent(pair.slice(0, eq));
+                const v = decodeURIComponent(pair.slice(eq + 1));
+                out[k] = v;
+            }
+        }
+    }
+    else if (payload && typeof payload === 'object') {
+        for (const [k, v] of Object.entries(payload)) {
+            if (v !== undefined && v !== null) {
+                if (typeof v === 'object' || typeof v === 'function') {
+                    out[k] = JSON.stringify(v) ?? '';
+                }
+                else {
+                    // primitive branch: safe stringify (TS typeof narrowing on unknown leaves {}; the assert excludes it)
+                    out[k] = primitiveString(v);
+                }
+            }
+        }
+    }
+    return out;
+}
+export function createJeepayDriver(_store, options) {
+    const fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));
+    /** MD5 sign: non-empty params (excluding sign) ASCII-sorted + &key=appSecret → MD5 → uppercase. */
+    function md5Sign(params) {
+        const str = Object.keys(params)
+            .filter((k) => k !== 'sign' && params[k] !== undefined && params[k] !== null && params[k] !== '')
+            .sort()
+            .map((k) => `${k}=${params[k]}`)
+            .join('&');
+        return createHash('md5').update(`${str}&key=${options.appSecret}`).digest('hex').toUpperCase();
+    }
+    function md5Verify(params) {
+        const sign = params['sign'];
+        if (!sign)
+            return false;
+        return md5Sign(params) === sign.toUpperCase();
+    }
+    /** Scene → wayCode (extras.wayCode wins when set). */
+    function resolveWayCode(input) {
+        const explicit = input.extras?.['wayCode'];
+        if (typeof explicit === 'string' && explicit)
+            return explicit;
+        const openid = input.extras?.['openid'];
+        if (input.scene === 'pc')
+            return 'WX_NATIVE';
+        if (input.scene === 'miniapp')
+            return 'WX_LITE';
+        if (typeof openid === 'string')
+            return 'WX_JSAPI';
+        return 'ALI_WAP';
+    }
+    /** Channel extra params (openid, etc.) → JSON string. */
+    function channelExtraOf(input) {
+        const extras = (input.extras ?? {});
+        const openid = extras['openid'];
+        if (typeof openid === 'string') {
+            return JSON.stringify({ openid });
+        }
+        return undefined;
+    }
+    async function createOrder(input) {
+        const params = {
+            mchNo: options.mchNo,
+            appId: options.appId,
+            mchOrderNo: input.orderId,
+            wayCode: resolveWayCode(input),
+            amount: String(input.amount),
+            currency: 'cny',
+            subject: input.subject,
+            body: input.subject,
+            notifyUrl: input.notifyUrl,
+        };
+        const clientIp = input.extras?.['clientIp'];
+        if (typeof clientIp === 'string' && clientIp)
+            params['clientIp'] = clientIp;
+        const channelExtra = channelExtraOf(input);
+        if (channelExtra)
+            params['channelExtra'] = channelExtra;
+        params['sign'] = md5Sign(params);
+        const res = await fetchImpl(`${options.baseUrl}/api/pay/unifiedOrder`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(params),
+        });
+        const body = (await res.json());
+        if (body.code !== 0 || !body.data) {
+            throw new Error(`jeepay_error:${body.code ?? 'unknown'}:${body.msg ?? ''}`);
+        }
+        const data = body.data;
+        const payData = data.payData ?? '';
+        if (data.payDataType === 'codeUrl') {
+            return {
+                kind: 'qr',
+                qrUrl: payData,
+                expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+            };
+        }
+        if (data.payDataType === 'payUrl') {
+            return { kind: 'redirect', payUrl: payData };
+        }
+        if (data.payDataType === 'wxpay') {
+            return { kind: 'jsapi', payParams: JSON.parse(payData) };
+        }
+        throw new Error(`unsupported_pay_data_type:${data.payDataType ?? 'unknown'}`);
+    }
+    function verifyCallback(payload, _headers) {
+        const params = toParams(payload);
+        if (!md5Verify(params)) {
+            return { ok: false, reason: 'bad_signature' };
+        }
+        // state: 2 = success (0 unpaid / 1 paying / 2 success / 3 closed)
+        const state = Number(params['state'] ?? params['orderState']);
+        if (state !== 2) {
+            return { ok: false, reason: `state:${state}` };
+        }
+        const orderId = params['mchOrderNo'];
+        const amount = params['amount'];
+        if (!orderId || amount === undefined) {
+            return { ok: false, reason: 'bad_payload' };
+        }
+        return {
+            ok: true,
+            orderId,
+            paidAmount: Number(amount),
+            ...(params['payOrderId'] ? { channelTxnId: params['payOrderId'] } : {}),
+        };
+    }
+    async function queryOrder(orderId) {
+        try {
+            const params = {
+                mchNo: options.mchNo,
+                appId: options.appId,
+                mchOrderNo: orderId,
+            };
+            params['sign'] = md5Sign(params);
+            const res = await fetchImpl(`${options.baseUrl}/api/pay/query`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(params),
+            });
+            const body = (await res.json());
+            if (body.code !== 0 || !body.data) {
+                return { state: 'unknown', raw: body };
+            }
+            // orderState: 0 unpaid / 1 paying / 2 success / 3 closed
+            const state = body.data.orderState;
+            if (state === 2) {
+                return { state: 'paid' };
+            }
+            if (state === 3) {
+                return { state: 'closed' };
+            }
+            return { state: 'created' };
+        }
+        catch {
+            return { state: 'unknown', raw: { error: 'query_failed' } };
+        }
+    }
+    return {
+        name: 'jeepay',
+        scenes: ['pc', 'h5', 'miniapp'],
+        createOrder,
+        verifyCallback,
+        queryOrder,
+        successResponseText: 'SUCCESS',
+    };
+}

package/dist/lakala.d.ts

@@ -0,0 +1,41 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * Lakala aggregator payment driver (licensed aggregator; main-scan / JSAPI / miniapp).
+ *
+ * Docs: o.lakala.com (aggregator main-scan /api/v3/labs/trans/preorder).
+ *
+ * Scene mapping (trans_type + account_type):
+ *  - `pc`            → trans_type=41 NATIVE (main scan), account_type from extras.accountType
+ *                      (WECHAT/ALIPAY/UQRCODEPAY, default WECHAT) → `{kind:'qr'}`
+ *  - `h5` + openid   → trans_type=51 JSAPI (WeChat official account, acc_busi_fields.openid) → `{kind:'jsapi'}`
+ *  - `miniapp`       → trans_type=71 WeChat miniapp (acc_busi_fields.openid) → `{kind:'jsapi'}`
+ *  - `h5` no openid  → **unsupported** (main scan has no WAP form; aggregator cashier product API awaits
+ *                      official confirmation, P2 extension)
+ *
+ * Security:
+ *  - Request/callback signing: merchant private key RSA-SHA256 (params minus sign, sorted, → base64); responses/callbacks verified with the Lakala public key
+ *  - Callbacks use the channel self-verification path; research confirms the callback expects a `success` text within 5s or Lakala retries
+ *
+ * ⚠️ Integration status: request fields come from the official docs (2026-03); **response structure / signature details /
+ *    callback field names follow the latest Lakala docs and must be calibrated during sandbox integration
+ *    (test.wsmsd.cn)** — this implementation follows industry convention with lenient parsing.
+ */
+import type { PaymentDriver } from './types.js';
+import type { PaymentStore } from './store.js';
+export interface LakalaOptions {
+    /** Merchant number assigned by Lakala. */
+    readonly merchantNo: string;
+    /** Business terminal number assigned by Lakala. */
+    readonly termNo: string;
+    /** Merchant private key (PEM, used for request signing). */
+    readonly privateKeyPem: string;
+    /** Lakala public key (PEM, used to verify callbacks). */
+    readonly lakalaPublicKeyPem: string;
+    /** Gateway URL. Production s2.lakala.com, test test.wsmsd.cn (path includes /api/v3). */
+    readonly baseUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+export declare function createLakalaDriver(_store: PaymentStore, options: LakalaOptions): PaymentDriver;

package/dist/lakala.js

@@ -0,0 +1,242 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * Lakala aggregator payment driver (licensed aggregator; main-scan / JSAPI / miniapp).
+ *
+ * Docs: o.lakala.com (aggregator main-scan /api/v3/labs/trans/preorder).
+ *
+ * Scene mapping (trans_type + account_type):
+ *  - `pc`            → trans_type=41 NATIVE (main scan), account_type from extras.accountType
+ *                      (WECHAT/ALIPAY/UQRCODEPAY, default WECHAT) → `{kind:'qr'}`
+ *  - `h5` + openid   → trans_type=51 JSAPI (WeChat official account, acc_busi_fields.openid) → `{kind:'jsapi'}`
+ *  - `miniapp`       → trans_type=71 WeChat miniapp (acc_busi_fields.openid) → `{kind:'jsapi'}`
+ *  - `h5` no openid  → **unsupported** (main scan has no WAP form; aggregator cashier product API awaits
+ *                      official confirmation, P2 extension)
+ *
+ * Security:
+ *  - Request/callback signing: merchant private key RSA-SHA256 (params minus sign, sorted, → base64); responses/callbacks verified with the Lakala public key
+ *  - Callbacks use the channel self-verification path; research confirms the callback expects a `success` text within 5s or Lakala retries
+ *
+ * ⚠️ Integration status: request fields come from the official docs (2026-03); **response structure / signature details /
+ *    callback field names follow the latest Lakala docs and must be calibrated during sandbox integration
+ *    (test.wsmsd.cn)** — this implementation follows industry convention with lenient parsing.
+ */
+import { createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
+const DEFAULT_GATEWAY = 'https://s2.lakala.com/api/v3';
+/** Unknown value → string (objects JSON-serialized to avoid [object Object]). */
+function toStr(value) {
+    return typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
+}
+/** Scene → trans_type (Lakala access-mode code). */
+function transTypeOf(scene) {
+    if (scene === 'pc')
+        return '41';
+    if (scene === 'h5')
+        return '51';
+    if (scene === 'miniapp')
+        return '71';
+    return undefined;
+}
+export function createLakalaDriver(_store, options) {
+    const baseUrl = options.baseUrl ?? DEFAULT_GATEWAY;
+    const fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));
+    const merchantKey = createPrivateKey(options.privateKeyPem);
+    const lakalaPublicKey = createPublicKey(options.lakalaPublicKeyPem);
+    /** RSA sign: params (excluding sign/empty) sorted → SHA256withRSA → base64. */
+    function rsaSign(params) {
+        const str = Object.keys(params)
+            .filter((k) => k !== 'sign' && params[k] !== undefined && params[k] !== null && params[k] !== '')
+            .sort()
+            .map((k) => `${k}=${params[k]}`)
+            .join('&');
+        return sign('RSA-SHA256', Buffer.from(str), merchantKey).toString('base64');
+    }
+    /** RSA verify (Lakala public key). */
+    function rsaVerify(params) {
+        const signature = params['sign'];
+        if (!signature)
+            return false;
+        const str = Object.keys(params)
+            .filter((k) => k !== 'sign' && params[k] !== undefined && params[k] !== null && params[k] !== '')
+            .sort()
+            .map((k) => `${k}=${params[k]}`)
+            .join('&');
+        try {
+            return verify('RSA-SHA256', Buffer.from(str), lakalaPublicKey, Buffer.from(signature, 'base64'));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Location info (required for risk control). */
+    function locationInfoOf(input) {
+        const extras = (input.extras ?? {});
+        const clientIp = typeof extras['clientIp'] === 'string' && extras['clientIp']
+            ? extras['clientIp']
+            : '127.0.0.1';
+        return { request_ip: clientIp };
+    }
+    /** Account-side business info (JSAPI/miniapp scenes pass openid/userId per channel). */
+    function accBusiFieldsOf(input, accountType) {
+        const extras = (input.extras ?? {});
+        const openid = extras['openid'];
+        if (typeof openid === 'string' && openid) {
+            return accountType === 'WECHAT' ? { openid } : { user_id: openid };
+        }
+        const userId = extras['userId'];
+        if (typeof userId === 'string' && userId) {
+            return { user_id: userId };
+        }
+        return undefined;
+    }
+    /** Wallet type: extras.accountType explicit (WECHAT/ALIPAY/UQRCODEPAY), default WECHAT. */
+    function accountTypeOf(input) {
+        const explicit = input.extras?.['accountType'];
+        return typeof explicit === 'string' && explicit ? explicit : 'WECHAT';
+    }
+    async function createOrder(input) {
+        const transType = transTypeOf(input.scene);
+        if (!transType) {
+            throw new Error(`unsupported_scene:${input.scene}`);
+        }
+        // JSAPI (51) / miniapp (71) require openid/userId
+        if (input.scene === 'h5' || input.scene === 'miniapp') {
+            const extras = (input.extras ?? {});
+            if (typeof extras['openid'] !== 'string' && typeof extras['userId'] !== 'string') {
+                throw new Error(`unsupported_scene:${input.scene} (JSAPI/小程序需 openid)`);
+            }
+        }
+        const accountType = accountTypeOf(input);
+        const params = {
+            merchant_no: options.merchantNo,
+            term_no: options.termNo,
+            out_trade_no: input.orderId,
+            account_type: accountType,
+            trans_type: transType,
+            total_amount: String(input.amount),
+            busi_mode: 'ACQ',
+            subject: input.subject,
+            notify_url: input.notifyUrl,
+            location_info: JSON.stringify(locationInfoOf(input)),
+        };
+        const accFields = accBusiFieldsOf(input, accountType);
+        if (accFields) {
+            params['acc_busi_fields'] = JSON.stringify(accFields);
+        }
+        params['sign'] = rsaSign(params);
+        const res = await fetchImpl(`${baseUrl}/labs/trans/preorder`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(params),
+        });
+        const body = (await res.json());
+        if (!res.ok || (body['code'] !== undefined && body['code'] !== '0000' && body['code'] !== 0)) {
+            throw new Error(`lakala_error:${toStr(body['code'] ?? res.status)}:${toStr(body['msg'] ?? body['message'] ?? '')}`);
+        }
+        // ⚠️ response field names follow the latest Lakala docs (sandbox-calibrated); parse leniently
+        const data = (body['data'] ?? body);
+        if (transType === '41') {
+            // main-scan: returns QR code content
+            const qrCode = data['code_url'] ??
+                data['codeUrl'] ??
+                data['qr_code'] ??
+                data['prepayCode'] ??
+                data['code'];
+            if (typeof qrCode === 'string' && qrCode) {
+                return {
+                    kind: 'qr',
+                    qrUrl: qrCode,
+                    expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+                };
+            }
+        }
+        else {
+            // JSAPI/miniapp: returns pay params (JSON string)
+            const payParam = data['pay_param'] ?? data['payParams'] ?? data['pay_params'] ?? data['pay_param_json'];
+            if (typeof payParam === 'string' && payParam) {
+                return { kind: 'jsapi', payParams: JSON.parse(payParam) };
+            }
+        }
+        throw new Error(`lakala_unsupported_response:${JSON.stringify(body)}`);
+    }
+    function verifyCallback(payload, _headers) {
+        // ⚠️ callback field names follow the latest official docs (sandbox-calibrated). JSON notification + sign-field verification.
+        let obj;
+        try {
+            obj =
+                typeof payload === 'string'
+                    ? JSON.parse(payload)
+                    : payload;
+        }
+        catch {
+            return { ok: false, reason: 'bad_payload' };
+        }
+        const params = Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, String(v)]));
+        if (!rsaVerify(params)) {
+            return { ok: false, reason: 'bad_signature' };
+        }
+        // status field candidates (pay_status / trade_status / result_code); success values 'SUCCESS'/'00'/'0000'/2
+        const status = String(params['pay_status'] ??
+            params['trade_status'] ??
+            params['result_code'] ??
+            params['order_status'] ??
+            '');
+        const success = status === 'SUCCESS' ||
+            status === '00' ||
+            status === '0000' ||
+            status === '2' ||
+            status === 'TRADE_SUCCESS';
+        if (!success) {
+            return { ok: false, reason: `status:${status}` };
+        }
+        const orderId = params['out_trade_no'] ?? params['outTradeNo'];
+        const amount = params['total_amount'] ?? params['amount'];
+        if (!orderId || amount === undefined) {
+            return { ok: false, reason: 'bad_payload' };
+        }
+        return {
+            ok: true,
+            orderId,
+            paidAmount: Number(amount),
+            ...(params['pay_order_no'] ? { channelTxnId: params['pay_order_no'] } : {}),
+        };
+    }
+    async function queryOrder(orderId) {
+        try {
+            const params = {
+                merchant_no: options.merchantNo,
+                term_no: options.termNo,
+                out_trade_no: orderId,
+            };
+            params['sign'] = rsaSign(params);
+            const res = await fetchImpl(`${baseUrl}/trade/query`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(params),
+            });
+            const body = (await res.json());
+            const data = (body['data'] ?? body);
+            const status = toStr(data['pay_status'] ?? data['trade_status'] ?? data['order_status'] ?? '');
+            if (status === 'SUCCESS' || status === '00' || status === 'TRADE_SUCCESS') {
+                return { state: 'paid' };
+            }
+            if (status === 'CLOSED' || status === 'CLOSE') {
+                return { state: 'closed' };
+            }
+            return { state: 'created' };
+        }
+        catch {
+            return { state: 'unknown', raw: { error: 'query_failed' } };
+        }
+    }
+    return {
+        name: 'lakala',
+        scenes: ['pc', 'h5', 'miniapp'],
+        createOrder,
+        verifyCallback,
+        queryOrder,
+        successResponseText: 'success',
+    };
+}

package/dist/manager.d.ts

@@ -0,0 +1,63 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * PaymentManager — payment core service layer (framework-agnostic, pure logic).
+ *
+ * Security baseline coverage (design doc §3/§5):
+ *  - Server-side pricing (amount comes from the business's getOrderAmount; the frontend amount is only a consistency check)
+ *  - MAX_AMOUNT per-order limit (over-limit rejected, avoids channel errors/risk control)
+ *  - Order idempotency (idempotencyKey) + duplicate-order guard for the same business order (duplicateOrderStrategy)
+ *  - Callback verification + time window + nonce anti-replay + callback idempotency (persist before responding)
+ *  - Conflict freeze / paid-after-close freeze / large-amount manual review (AUDIT_THRESHOLD + confirm)
+ *  - Operation audit (order/callback-book/freeze/confirm all logged)
+ *  - onVerified business hook (must be idempotent) / onAlert alert hook
+ */
+import type { AuditEntry, CallbackResult, CreateOrderRequest, CreateOrderResult, GetOrderAmount, OrderState, OrderStatus, PaymentAlert, PaymentConfig, PaymentDriver, PaymentScene, VerifiedResult } from './types.js';
+import { type PaymentStore } from './store.js';
+export type OrderErrorCode = 'order_not_found' | 'amount_mismatch' | 'amount_exceeds_limit' | 'order_conflict' | 'channel_unavailable' | 'bad_request';
+export type OrderError = {
+    readonly error: OrderErrorCode;
+    readonly message?: string;
+    readonly expected?: number;
+    readonly max?: number;
+};
+export type CreateOrderOutcome = CreateOrderResult | OrderError;
+export interface PaymentManagerOptions {
+    readonly config?: PaymentConfig;
+    /** Defaults to an in-memory store. */
+    readonly store?: PaymentStore;
+    /** Callback signature key (HMAC-SHA256). Inject via KMS/env in production. */
+    readonly apiKey?: string;
+    /** Server-pricing hook (business: orderId → amount in fen; undefined = order not found). */
+    readonly getOrderAmount?: GetOrderAmount;
+    /** Business action after booking (deliver/activate) — must be idempotent; on failure the business must retry or compensate manually. */
+    readonly onVerified?: (result: VerifiedResult) => void | Promise<void>;
+    /** Alerts (frozen/conflict/large-amount/signature-failure). */
+    readonly onAlert?: (alert: PaymentAlert) => void;
+}
+export interface PaymentManager {
+    registerDriver(driver: PaymentDriver): void;
+    available(): readonly {
+        readonly name: string;
+        readonly scenes: readonly PaymentScene[];
+    }[];
+    createOrder(req: CreateOrderRequest): Promise<CreateOrderOutcome>;
+    getStatus(orderId: string): OrderStatus | undefined;
+    close(orderId: string): OrderStatus | undefined;
+    confirm(orderId: string): OrderStatus | undefined;
+    /** Active reconciliation (compensates lost callbacks): query channel status → sync locally (channel paid & local created → migrate via state machine, incl. large-amount audit). */
+    syncOrderStatus(orderId: string): Promise<OrderStatus | undefined>;
+    /** Expiry scan: created & past ttlMs → closed; returns closed orders. Call from a scheduled task. */
+    scanExpiredOrders(ttlMs: number): readonly {
+        readonly orderId: string;
+        readonly state: OrderState;
+    }[];
+    handleCallback(driverName: string, ctx: {
+        readonly headers: Readonly<Record<string, string | undefined>>;
+        readonly body: string;
+    }): Promise<CallbackResult>;
+    auditLog(): readonly AuditEntry[];
+}
+export declare function createPaymentManager(options?: PaymentManagerOptions): PaymentManager;