@vobs/payment 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vobsjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/alipay-official.d.ts

@@ -0,0 +1,34 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * Alipay official driver (Open Platform API) — face-to-face (PC scan) / PC web / mobile web (H5).
+ *
+ * Covered scenes (web):
+ *  - `pc`       → alipay.trade.precreate (face-to-face) → `{kind:'qr', qrUrl: qr_code}`
+ *  - `h5`       → alipay.trade.wap.pay (mobile web) → `{kind:'redirect', payUrl}`
+ *  - `miniapp`  → same as h5 (Alipay miniapp webview uses H5 payment; native my.tradePay out of scope)
+ *
+ * Security:
+ *  - Request signing: app private key RSA2 (SHA256withRSA), params joined in lexicographic order
+ *  - Async notify: verify with Alipay public key (excluding sign/sign_type) + notify_id anti-replay + state-machine idempotency
+ *  - Channel self-verification: callbacks bypass the framework's generic HMAC protocol; this driver verifies itself
+ *
+ * Dependencies: node:crypto (Node built-in, zero third-party). Sandbox: set baseUrl to openapi-sandbox.dl.alipaydev.com.
+ */
+import type { PaymentDriver } from './types.js';
+import type { PaymentStore } from './store.js';
+export interface AlipayOfficialOptions {
+    readonly appId: string;
+    /** App private key (PEM, used for request signing). */
+    readonly privateKeyPem: string;
+    /** Alipay public key (PEM, used to verify async-notify/response signatures). */
+    readonly alipayPublicKeyPem: string;
+    /** Gateway URL. Production defaults to openapi.alipay.com, sandbox to openapi-sandbox.dl.alipaydev.com. */
+    readonly baseUrl?: string;
+    /** Page-jump gateway (GET redirects for PC web / mobile web). Defaults to baseUrl. */
+    readonly pageBaseUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+export declare function createAlipayOfficialDriver(store: PaymentStore, options: AlipayOfficialOptions): PaymentDriver;

package/dist/alipay-official.js

@@ -0,0 +1,195 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * Alipay official driver (Open Platform API) — face-to-face (PC scan) / PC web / mobile web (H5).
+ *
+ * Covered scenes (web):
+ *  - `pc`       → alipay.trade.precreate (face-to-face) → `{kind:'qr', qrUrl: qr_code}`
+ *  - `h5`       → alipay.trade.wap.pay (mobile web) → `{kind:'redirect', payUrl}`
+ *  - `miniapp`  → same as h5 (Alipay miniapp webview uses H5 payment; native my.tradePay out of scope)
+ *
+ * Security:
+ *  - Request signing: app private key RSA2 (SHA256withRSA), params joined in lexicographic order
+ *  - Async notify: verify with Alipay public key (excluding sign/sign_type) + notify_id anti-replay + state-machine idempotency
+ *  - Channel self-verification: callbacks bypass the framework's generic HMAC protocol; this driver verifies itself
+ *
+ * Dependencies: node:crypto (Node built-in, zero third-party). Sandbox: set baseUrl to openapi-sandbox.dl.alipaydev.com.
+ */
+import { createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
+const DEFAULT_GATEWAY = 'https://openapi.alipay.com/gateway.do';
+/** Yuan (string) → fen (integer): '99.90' → 9990. */
+function yuanToFen(v) {
+    return Math.round(Number(v) * 100);
+}
+/** Fen → yuan string (2 decimals): 9990 → '99.90'. */
+function fenToYuan(amount) {
+    return (amount / 100).toFixed(2);
+}
+function nowTimestamp() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+export function createAlipayOfficialDriver(store, options) {
+    const baseUrl = options.baseUrl ?? DEFAULT_GATEWAY;
+    const pageBaseUrl = options.pageBaseUrl ?? options.baseUrl ?? DEFAULT_GATEWAY;
+    const fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));
+    const privateKey = createPrivateKey(options.privateKeyPem);
+    const alipayPublicKey = createPublicKey(options.alipayPublicKeyPem);
+    /** RSA2 signature (SHA256withRSA), base64-encoded. */
+    function rsaSign(data) {
+        return sign('RSA-SHA256', Buffer.from(data), privateKey).toString('base64');
+    }
+    /** RSA2 verify (Alipay public key). */
+    function rsaVerify(data, signature) {
+        try {
+            return verify('RSA-SHA256', Buffer.from(data), alipayPublicKey, Buffer.from(signature, 'base64'));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Join params (excluding sign/sign_type) in lexicographic order → k=v&k=v. */
+    function sortParams(params) {
+        return Object.keys(params)
+            .filter((k) => k !== 'sign' && k !== 'sign_type')
+            .sort()
+            .map((k) => `${k}=${params[k]}`)
+            .join('&');
+    }
+    async function gateway(method, bizContent) {
+        const params = {
+            app_id: options.appId,
+            method,
+            charset: 'utf-8',
+            sign_type: 'RSA2',
+            timestamp: nowTimestamp(),
+            version: '1.0',
+            biz_content: JSON.stringify(bizContent),
+        };
+        params['sign'] = rsaSign(sortParams(params));
+        const res = await fetchImpl(baseUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(params),
+        });
+        const body = (await res.json());
+        if (!res.ok) {
+            throw new Error(`alipay_api_error:${res.status}`);
+        }
+        return body;
+    }
+    function buildPageUrl(method, bizContent) {
+        const params = {
+            app_id: options.appId,
+            method,
+            charset: 'utf-8',
+            sign_type: 'RSA2',
+            timestamp: nowTimestamp(),
+            version: '1.0',
+            biz_content: JSON.stringify(bizContent),
+            return_url: '',
+            notify_url: '',
+        };
+        params['sign'] = rsaSign(sortParams(params));
+        const qs = Object.keys(params)
+            .sort()
+            .map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(params[k] ?? '')}`)
+            .join('&');
+        return `${pageBaseUrl}?${qs}`;
+    }
+    async function createOrder(input) {
+        const biz = {
+            out_trade_no: input.orderId,
+            total_amount: fenToYuan(input.amount),
+            subject: input.subject,
+        };
+        if (input.scene === 'pc') {
+            // Face-to-face (scan) payment
+            const body = await gateway('alipay.trade.precreate', biz);
+            const resp = body.alipay_trade_precreate_response;
+            if (resp?.code !== '10000' || !resp.qr_code) {
+                throw new Error(`alipay_precreate_failed:${resp?.sub_code ?? resp?.msg ?? 'unknown'}`);
+            }
+            return {
+                kind: 'qr',
+                qrUrl: resp.qr_code,
+                expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+            };
+        }
+        // h5 / miniapp: mobile web payment (redirect to cashier)
+        return { kind: 'redirect', payUrl: buildPageUrl('alipay.trade.wap.pay', biz) };
+    }
+    function verifyCallback(payload, _headers) {
+        // Async notify is a form-encoded string: a=1&b=2&sign=... (URL-decoded)
+        let params;
+        if (typeof payload === 'string') {
+            params = {};
+            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));
+                    params[k] = v;
+                }
+            }
+        }
+        else {
+            const obj = payload;
+            params = Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, String(v)]));
+        }
+        const signature = params['sign'] ?? '';
+        if (!rsaVerify(sortParams(params), signature)) {
+            return { ok: false, reason: 'bad_alipay_signature' };
+        }
+        // notify_id anti-replay (channel self-verification path)
+        const notifyId = params['notify_id'] ?? '';
+        if (!store.addNonce(`ali:${notifyId}`)) {
+            return { ok: false, reason: 'nonce_reused' };
+        }
+        // Only successful states are booked (TRADE_SUCCESS / TRADE_FINISHED)
+        const tradeStatus = params['trade_status'] ?? '';
+        if (tradeStatus !== 'TRADE_SUCCESS' && tradeStatus !== 'TRADE_FINISHED') {
+            return { ok: false, reason: `trade_status:${tradeStatus}` };
+        }
+        const orderId = params['out_trade_no'];
+        if (!orderId || params['total_amount'] === undefined) {
+            return { ok: false, reason: 'bad_payload' };
+        }
+        return {
+            ok: true,
+            orderId,
+            paidAmount: yuanToFen(params['total_amount']),
+            ...(params['trade_no'] ? { channelTxnId: params['trade_no'] } : {}),
+        };
+    }
+    async function queryOrder(orderId) {
+        try {
+            const body = await gateway('alipay.trade.query', {
+                out_trade_no: orderId,
+            });
+            const resp = body.alipay_trade_query_response;
+            const status = resp?.trade_status;
+            if (status === 'TRADE_SUCCESS' || status === 'TRADE_FINISHED') {
+                return { state: 'paid', ...(resp.send_pay_date ? { paidAt: resp.send_pay_date } : {}) };
+            }
+            if (status === 'TRADE_CLOSED') {
+                return { state: 'closed' };
+            }
+            return { state: 'created' };
+        }
+        catch {
+            return { state: 'unknown', raw: { error: 'query_failed' } };
+        }
+    }
+    return {
+        name: 'alipay_official',
+        scenes: ['pc', 'h5', 'miniapp'],
+        createOrder,
+        verifyCallback,
+        queryOrder,
+        successResponseText: 'success',
+    };
+}

package/dist/handlers.d.ts

@@ -0,0 +1,33 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * Framework-agnostic HTTP handler layer — `paymentHttpDispatch` returns standard responses that
+ * the business wraps in one line inside its own server (Hono/Express/Fastify). This package does
+ * not bind to any server.
+ *
+ * Route conventions (per design doc §3.3/§3.5):
+ *   GET  /payment/available-methods                 available payment methods
+ *   POST /api/payment/orders                        create order (server-side pricing + limit + idempotency + duplicate guard)
+ *   GET  /api/payment/orders/:id/status             query status (frontend polling)
+ *   POST /api/payment/orders/:id/close              close on timeout/cancel (example helper)
+ *   POST /api/payment/orders/:id/confirm            manual release for large-amount review (admin; business-side auth required)
+ *   POST /payment/callback/:driver                  channel callback (verify + anti-replay + state machine)
+ */
+import type { PaymentManager } from './manager.js';
+export interface HttpResponse {
+    readonly status: number;
+    readonly body: unknown;
+}
+export interface HttpRequestContext {
+    readonly method: string;
+    /** Relative path (e.g. `/api/payment/orders` or `/payment/callback/mock`). */
+    readonly path: string;
+    readonly headers?: Readonly<Record<string, string | undefined>>;
+    readonly body?: string;
+}
+type RouteResult = HttpResponse;
+/** Create a dispatch function (pure logic, no framework dependency). */
+export declare function paymentHttpDispatch(manager: PaymentManager): (ctx: HttpRequestContext) => Promise<RouteResult>;
+export {};

package/dist/handlers.js

@@ -0,0 +1,95 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * Framework-agnostic HTTP handler layer — `paymentHttpDispatch` returns standard responses that
+ * the business wraps in one line inside its own server (Hono/Express/Fastify). This package does
+ * not bind to any server.
+ *
+ * Route conventions (per design doc §3.3/§3.5):
+ *   GET  /payment/available-methods                 available payment methods
+ *   POST /api/payment/orders                        create order (server-side pricing + limit + idempotency + duplicate guard)
+ *   GET  /api/payment/orders/:id/status             query status (frontend polling)
+ *   POST /api/payment/orders/:id/close              close on timeout/cancel (example helper)
+ *   POST /api/payment/orders/:id/confirm            manual release for large-amount review (admin; business-side auth required)
+ *   POST /payment/callback/:driver                  channel callback (verify + anti-replay + state machine)
+ */
+const json = (status, body) => ({ status, body });
+function errorStatus(err) {
+    switch (err.error) {
+        case 'order_not_found':
+            return 404;
+        case 'amount_exceeds_limit':
+        case 'amount_mismatch':
+        case 'bad_request':
+            return 400;
+        case 'order_conflict':
+            return 409;
+        case 'channel_unavailable':
+            return 503;
+        default:
+            return 500;
+    }
+}
+/** Create a dispatch function (pure logic, no framework dependency). */
+export function paymentHttpDispatch(manager) {
+    return async function dispatch(ctx) {
+        const { method, path } = ctx;
+        if (method === 'GET' && path === '/payment/available-methods') {
+            return json(200, { methods: manager.available() });
+        }
+        if (method === 'POST' && path === '/api/payment/orders') {
+            let req;
+            try {
+                req = JSON.parse(ctx.body ?? '');
+            }
+            catch {
+                return json(400, { error: 'bad_json' });
+            }
+            const outcome = await manager.createOrder(req);
+            if ('error' in outcome) {
+                return json(errorStatus(outcome), outcome);
+            }
+            return json(200, outcome);
+        }
+        const statusMatch = path.match(/^\/api\/payment\/orders\/([^/]+)\/status$/);
+        if (statusMatch && method === 'GET') {
+            const orderId = statusMatch[1];
+            const status = manager.getStatus(orderId);
+            if (!status)
+                return json(404, { error: 'order_not_found' });
+            return json(200, { orderId, ...status });
+        }
+        const closeMatch = path.match(/^\/api\/payment\/orders\/([^/]+)\/close$/);
+        if (closeMatch && method === 'POST') {
+            const orderId = closeMatch[1];
+            const status = manager.close(orderId);
+            if (!status)
+                return json(404, { error: 'order_not_found' });
+            return json(200, { orderId, ...status });
+        }
+        const confirmMatch = path.match(/^\/api\/payment\/orders\/([^/]+)\/confirm$/);
+        if (confirmMatch && method === 'POST') {
+            const orderId = confirmMatch[1];
+            const status = manager.confirm(orderId);
+            if (!status)
+                return json(404, { error: 'order_not_found' });
+            return json(200, { orderId, ...status });
+        }
+        const callbackMatch = path.match(/^\/payment\/callback\/([^/]+)$/);
+        if (callbackMatch && method === 'POST') {
+            const driver = callbackMatch[1];
+            const result = await manager.handleCallback(driver, {
+                headers: ctx.headers ?? {},
+                body: ctx.body ?? '',
+            });
+            // Channel-agreed response protocol: if text exists → plain text (WeChat/Jeepay SUCCESS, Alipay success), else JSON
+            if (result.text !== undefined) {
+                return { status: result.status, body: result.text };
+            }
+            return json(result.status, result.body);
+        }
+        return json(404, { error: 'not_found' });
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * @vobs/payment — payment-factory backend SDK (Experimental).
+ *
+ * Positioning: an official vobs extension package embedded in the business backend (not a standalone service).
+ * Responsibility: the forward payment pipeline (order → verify → book → reconcile); **no refunds**.
+ *
+ * Usage (business backend, 3 touch points):
+ * ```ts
+ * import { createPaymentManager, createMockDriver, paymentHttpDispatch } from '@vobs/payment'
+ *
+ * const manager = createPaymentManager({
+ *   apiKey: process.env.PAYMENT_API_KEY!,
+ *   getOrderAmount: (orderId) => orderDao.find(orderId)?.amount,  // server-side pricing (red line)
+ *   onVerified: ({ orderId }) => orderDao.markPaid(orderId),       // idempotent
+ * })
+ * manager.registerDriver(createMockDriver(store))                  // swap in a real channel driver for P1
+ * const dispatch = paymentHttpDispatch(manager)
+ * // in your server: app.post('/api/payment/orders', async (req) => dispatch({ method:'POST', path:'/api/payment/orders', body: await req.text() }))
+ * ```
+ */
+export * from './types.js';
+export * from './verify.js';
+export * from './state-machine.js';
+export * from './store.js';
+export * from './mock-driver.js';
+export * from './wechat-official.js';
+export * from './alipay-official.js';
+export * from './jeepay.js';
+export * from './lakala.js';
+export * from './manager.js';
+export * from './handlers.js';

package/dist/index.js

@@ -0,0 +1,35 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * @vobs/payment — payment-factory backend SDK (Experimental).
+ *
+ * Positioning: an official vobs extension package embedded in the business backend (not a standalone service).
+ * Responsibility: the forward payment pipeline (order → verify → book → reconcile); **no refunds**.
+ *
+ * Usage (business backend, 3 touch points):
+ * ```ts
+ * import { createPaymentManager, createMockDriver, paymentHttpDispatch } from '@vobs/payment'
+ *
+ * const manager = createPaymentManager({
+ *   apiKey: process.env.PAYMENT_API_KEY!,
+ *   getOrderAmount: (orderId) => orderDao.find(orderId)?.amount,  // server-side pricing (red line)
+ *   onVerified: ({ orderId }) => orderDao.markPaid(orderId),       // idempotent
+ * })
+ * manager.registerDriver(createMockDriver(store))                  // swap in a real channel driver for P1
+ * const dispatch = paymentHttpDispatch(manager)
+ * // in your server: app.post('/api/payment/orders', async (req) => dispatch({ method:'POST', path:'/api/payment/orders', body: await req.text() }))
+ * ```
+ */
+export * from './types.js';
+export * from './verify.js';
+export * from './state-machine.js';
+export * from './store.js';
+export * from './mock-driver.js';
+export * from './wechat-official.js';
+export * from './alipay-official.js';
+export * from './jeepay.js';
+export * from './lakala.js';
+export * from './manager.js';
+export * from './handlers.js';

package/dist/jeepay.d.ts

@@ -0,0 +1,39 @@
+/** @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 type { PaymentDriver } from './types.js';
+import type { PaymentStore } from './store.js';
+export interface JeepayOptions {
+    /** Merchant number (issued by the Jeepay ops platform). */
+    readonly mchNo: string;
+    /** Application ID (merchant app). */
+    readonly appId: string;
+    /** Signing secret (configured on the merchant app, used for MD5). */
+    readonly appSecret: string;
+    /** Payment gateway URL (self-hosted, e.g. https://pay.example.com; or official cloud https://pay.jeepay.vip). */
+    readonly baseUrl: string;
+    readonly fetchImpl?: typeof fetch;
+}
+export declare function createJeepayDriver(_store: PaymentStore, options: JeepayOptions): PaymentDriver;