shutro-erp 0.3.2 → 0.3.4

package/dist/payment/index.js

@@ -22,14 +22,21 @@ import { portalDocuments } from '../portal/index.js';
 import { HttpProblem } from '../server/index.js';
 import { orm } from '../server/orm.js';
 import { action, form, list } from '../views/index.js';
+import { bkashFromEnvironment } from './bkash.js';
 import { PaymentProvider, PaymentTransaction, paymentShutro } from './module.js';
 import { ADAPTERS, FAKE_SIGNATURE, fakeAdapter } from './providers.js';
+import { razorpayFromEnvironment } from './razorpay.js';
 import { settle } from './settle.js';
 import { sslcommerzFromEnvironment } from './sslcommerz.js';
+import { stripeFromEnvironment } from './stripe.js';
+export { bkashAdapter, bkashFromEnvironment } from './bkash.js';
 export { newReference, PaymentProvider, PaymentTransaction, PROVIDERS, paymentShutro, } from './module.js';
+export { decimalsOf, fromSubunits, toSubunits } from './money.js';
 export { ADAPTERS, FAKE_SIGNATURE, fakeAdapter, } from './providers.js';
+export { razorpayAdapter, razorpayFromEnvironment } from './razorpay.js';
 export { settle } from './settle.js';
 export { sslcommerzAdapter, sslcommerzFromEnvironment, } from './sslcommerz.js';
+export { stripeAdapter, stripeFromEnvironment } from './stripe.js';
 const typed = (env) => env;
 const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
 /** A callback endpoint per adapter: verified by the adapter with the endpoint's secret, settled as the system. */
@@ -158,25 +165,34 @@ function registerPaymentRoutes(context, adapters, urls) {
             await su.flush(); // company checks run in this superuser scope, not at commit (Shutro request #11)
             const [tx] = await created.load({});
             const reference = tx?.reference ?? '';
-            const { redirectUrl } = await adapter.createPayment({
-                reference,
-                amount: due.toFixed(move.currency.decimalPlaces ?? 2),
-                currency: move.currency.name,
-                description: `${d.spec.label} ${move.name}`,
-                customer: {
-                    name: move.partner?.name ?? '',
-                    email: move.partner?.email ?? null,
-                    phone: move.partner?.phone ?? move.partner?.mobile ?? null,
-                    street: move.partner?.street ?? null,
-                    city: move.partner?.city ?? null,
-                    zip: move.partner?.zip ?? null,
-                    country: move.partner?.country ?? null,
-                },
-                returnUrl: `${urls.api}/api/v1/payment/return/${encodeURIComponent(reference)}`,
-                callbackUrl: `${urls.api}/api/v1/hooks/${token}`,
-                mode: provider.state === 'live' ? 'live' : 'test',
-            });
-            return { reference, redirectUrl };
+            let started;
+            try {
+                started = await adapter.createPayment({
+                    reference,
+                    amount: due.toFixed(move.currency.decimalPlaces ?? 2),
+                    currency: move.currency.name,
+                    description: `${d.spec.label} ${move.name}`,
+                    customer: {
+                        name: move.partner?.name ?? '',
+                        email: move.partner?.email ?? null,
+                        phone: move.partner?.phone ?? move.partner?.mobile ?? null,
+                        street: move.partner?.street ?? null,
+                        city: move.partner?.city ?? null,
+                        zip: move.partner?.zip ?? null,
+                        country: move.partner?.country ?? null,
+                    },
+                    returnUrl: `${urls.api}/api/v1/payment/return/${encodeURIComponent(reference)}`,
+                    callbackUrl: `${urls.api}/api/v1/hooks/${token}`,
+                    mode: provider.state === 'live' ? 'live' : 'test',
+                });
+            }
+            catch (error) {
+                throw new HttpProblem(502, 'provider-error', 'The payment could not start', error instanceof Error ? error.message : String(error));
+            }
+            if (started.providerReference !== undefined)
+                await created.write({ providerReference: started.providerReference });
+            await su.flush();
+            return { reference, redirectUrl: started.redirectUrl };
         });
         return reply.status(201).send(started);
     });
@@ -200,6 +216,7 @@ function registerPaymentRoutes(context, adapters, urls) {
                         currency: t.currency.name,
                         code: t.provider.code,
                         mode: t.provider.state === 'live' ? 'live' : 'test',
+                        providerReference: t.providerReference,
                         error: t.error,
                     };
             });
@@ -215,7 +232,10 @@ function registerPaymentRoutes(context, adapters, urls) {
         let error = found.error;
         // Back before the callback: the provider's word settles it now (once; the callback then finds it settled).
         if (state === 'pending') {
-            const result = await adapters.get(found.code)?.status(reference, found.mode);
+            const result = await adapters
+                .get(found.code)
+                ?.status(reference, found.mode, found.providerReference)
+                .catch(() => null);
             if (result !== null && result !== undefined && result.status !== 'pending') {
                 const settled = await context.shutro.bootstrap({ reason: `payment ${reference}: the customer returned`, company: found.company }, (env) => settle(typed(env), result));
                 state = settled?.state ?? state;
@@ -267,12 +287,41 @@ function registerPaymentRoutes(context, adapters, urls) {
             config: { auth: false },
             handler: async (request, reply) => {
                 const reference = String(request.params['reference'] ?? '');
-                const move = await context.shutro.bootstrap({ reason: 'payment return' }, (raw) => raw.asSuperuser({ reason: 'payment return: which invoice' }, async (su) => {
+                const tx = await context.shutro.bootstrap({ reason: 'payment return' }, (raw) => raw.asSuperuser({ reason: 'payment return: which invoice' }, async (su) => {
                     const [t] = await (await typed(su.withFlags({ checkCompany: false }))
                         .model('payment.transaction')
-                        .search({ where: { reference }, limit: 1 })).load({});
-                    return t?.move.id ?? null;
+                        .search({ where: { reference }, limit: 1 })).load({ provider: true });
+                    return t === undefined
+                        ? null
+                        : {
+                            move: t.move.id,
+                            company: t.company.id,
+                            state: t.state,
+                            code: t.provider.code,
+                            mode: t.provider.state === 'live' ? 'live' : 'test',
+                            providerReference: t.providerReference,
+                        };
                 }));
+                // Providers that complete a payment on the merchant's request (bKash) do it now; the adapter asks the
+                // provider itself — what the browser brings is only a hint.
+                const adapter = tx === null ? undefined : adapters.get(tx.code);
+                if (tx !== null && tx.state !== 'done' && adapter?.returned !== undefined) {
+                    const query = Object.fromEntries(Object.entries((request.query ?? {})).map(([k, v]) => [k, String(v)]));
+                    try {
+                        const result = await adapter.returned({
+                            reference,
+                            providerReference: tx.providerReference,
+                            mode: tx.mode,
+                            query,
+                        });
+                        if (result !== null)
+                            await context.shutro.bootstrap({ reason: `payment ${reference}: the customer returned`, company: tx.company }, (env) => settle(typed(env), result));
+                    }
+                    catch (error) {
+                        request.log.warn({ err: error, reference }, 'payment return: the provider did not answer');
+                    }
+                }
+                const move = tx?.move ?? null;
                 return reply.redirect(move === null
                     ? `${urls.portal}/`
                     : `${urls.portal}/d/${encodeURIComponent(payable)}/${move}?payment=${encodeURIComponent(reference)}`, 303);
@@ -300,7 +349,14 @@ function registerPaymentRoutes(context, adapters, urls) {
 }
 /** Online payments with explicit options (tests, installations wiring their own adapters). */
 export function paymentModule(options = {}) {
-    const adapters = options.adapters ?? new Map([...ADAPTERS, ['sslcommerz', sslcommerzFromEnvironment()]]);
+    const adapters = options.adapters ??
+        new Map([
+            ...ADAPTERS,
+            ['sslcommerz', sslcommerzFromEnvironment()],
+            ['bkash', bkashFromEnvironment()],
+            ['razorpay', razorpayFromEnvironment()],
+            ['stripe', stripeFromEnvironment()],
+        ]);
     return defineModule({
         shutro: paymentShutro,
         kosh: '^0.1.0',

package/dist/payment/module.d.ts

@@ -4,6 +4,9 @@ export declare const newReference: () => string;
 export declare const PROVIDERS: {
     readonly fake: 'Test provider (no money moves)';
     readonly sslcommerz: 'SSLCommerz';
+    readonly bkash: 'bKash';
+    readonly razorpay: 'Razorpay';
+    readonly stripe: 'Stripe';
 };
 export declare const PaymentProvider: import("shutro").Model<"payment.provider", {
     readonly id: import("shutro").IdField<"payment.provider">;
@@ -58,7 +61,7 @@ export declare const PaymentProvider: import("shutro").Model<"payment.provider",
         readonly hasDefault: false;
         readonly readonly: false;
     }, string>;
-    readonly code: import("shutro").SelectionField<"fake" | "sslcommerz", {
+    readonly code: import("shutro").SelectionField<"bkash" | "fake" | "razorpay" | "sslcommerz" | "stripe", {
         readonly required: true;
         readonly computed: false;
         readonly inverse: false;
@@ -119,7 +122,7 @@ export declare const PaymentProvider: import("shutro").Model<"payment.provider",
         readonly hasDefault: false;
         readonly readonly: false;
     }, string>;
-    readonly code: import("shutro").SelectionField<"fake" | "sslcommerz", {
+    readonly code: import("shutro").SelectionField<"bkash" | "fake" | "razorpay" | "sslcommerz" | "stripe", {
         readonly required: true;
         readonly computed: false;
         readonly inverse: false;
@@ -491,7 +494,7 @@ export declare const paymentShutro: import("shutro").Module<readonly [import("sh
         readonly hasDefault: false;
         readonly readonly: false;
     }, string>;
-    readonly code: import("shutro").SelectionField<"fake" | "sslcommerz", {
+    readonly code: import("shutro").SelectionField<"bkash" | "fake" | "razorpay" | "sslcommerz" | "stripe", {
         readonly required: true;
         readonly computed: false;
         readonly inverse: false;
@@ -552,7 +555,7 @@ export declare const paymentShutro: import("shutro").Module<readonly [import("sh
         readonly hasDefault: false;
         readonly readonly: false;
     }, string>;
-    readonly code: import("shutro").SelectionField<"fake" | "sslcommerz", {
+    readonly code: import("shutro").SelectionField<"bkash" | "fake" | "razorpay" | "sslcommerz" | "stripe", {
         readonly required: true;
         readonly computed: false;
         readonly inverse: false;

package/dist/payment/module.js

@@ -16,6 +16,9 @@ export const newReference = () => `PAY-${randomBytes(9).toString('base64url')}`;
 export const PROVIDERS = {
     fake: 'Test provider (no money moves)',
     sslcommerz: 'SSLCommerz',
+    bkash: 'bKash',
+    razorpay: 'Razorpay',
+    stripe: 'Stripe',
 };
 export const PaymentProvider = defineModel('payment.provider', {
     label: 'Payment provider',

package/dist/payment/money.d.ts

@@ -0,0 +1,7 @@
+/** Amounts in a currency's subunits, as payment providers take them (`'1500.00'` INR ↔ 150000). */
+/** Decimal places of a currency's subunit. */
+export declare function decimalsOf(currency: string): number;
+/** `'1500.00'` INR → 150000. */
+export declare function toSubunits(amount: string, currency: string): number;
+/** 150000 INR → `'1500.00'`. */
+export declare function fromSubunits(subunits: number, currency: string): string;

package/dist/payment/money.js

@@ -0,0 +1,37 @@
+/** Amounts in a currency's subunits, as payment providers take them (`'1500.00'` INR ↔ 150000). */
+/** Currencies without subunits, and with three decimals (Stripe's and Razorpay's lists). */
+const ZERO = new Set([
+    'BIF',
+    'CLP',
+    'DJF',
+    'GNF',
+    'JPY',
+    'KMF',
+    'KRW',
+    'MGA',
+    'PYG',
+    'RWF',
+    'UGX',
+    'VND',
+    'VUV',
+    'XAF',
+    'XOF',
+    'XPF',
+]);
+const THREE = new Set(['BHD', 'JOD', 'KWD', 'OMR', 'TND']);
+/** Decimal places of a currency's subunit. */
+export function decimalsOf(currency) {
+    const code = currency.toUpperCase();
+    return ZERO.has(code) ? 0 : THREE.has(code) ? 3 : 2;
+}
+/** `'1500.00'` INR → 150000. */
+export function toSubunits(amount, currency) {
+    const d = decimalsOf(currency);
+    const [whole = '0', fraction = ''] = amount.split('.');
+    return Number(`${whole}${fraction.padEnd(d, '0').slice(0, d)}`);
+}
+/** 150000 INR → `'1500.00'`. */
+export function fromSubunits(subunits, currency) {
+    const d = decimalsOf(currency);
+    return (subunits / 10 ** d).toFixed(d);
+}

package/dist/payment/providers.d.ts

@@ -38,16 +38,27 @@ export interface PaymentAdapter {
     readonly code: string;
     /** Whether its credentials are set (the portal offers only providers whose adapter can work). */
     configured(mode: 'test' | 'live'): boolean;
-    /** Starts a payment; returns the page to send the customer to. */
+    /** Starts a payment; returns the page to send the customer to (and the provider's id of it, when it has one). */
     createPayment(request: PaymentRequest): Promise<{
         readonly redirectUrl: string;
+        readonly providerReference?: string;
     }>;
     /** A callback's event id, or `null` when it is not genuine (checked with the endpoint's secret). */
     verifyCallback(call: InboundCall, secret: string): string | null | Promise<string | null>;
     /** What a verified callback says. */
     readCallback(call: InboundCall): PaymentResult | null;
     /** The provider's word on a payment (null: unknown to it). */
-    status(reference: string, mode: 'test' | 'live'): Promise<PaymentResult | null>;
+    status(reference: string, mode: 'test' | 'live', providerReference: string | null): Promise<PaymentResult | null>;
+    /**
+     * The customer is back (`query`: what the provider put in the return URL — a hint, never proof). Providers that
+     * complete a payment only when the merchant asks (bKash's execute) do it here; the result is settled at once.
+     */
+    returned?(input: {
+        readonly reference: string;
+        readonly providerReference: string | null;
+        readonly mode: 'test' | 'live';
+        readonly query: Readonly<Record<string, string>>;
+    }): Promise<PaymentResult | null>;
 }
 /** The fake adapter's header: HMAC-SHA256 (hex) of the raw body with the endpoint's secret. */
 export declare const FAKE_SIGNATURE = "x-fake-signature";

package/dist/payment/razorpay.d.ts

@@ -0,0 +1,12 @@
+import type { PaymentAdapter } from './providers.js';
+export interface RazorpayOptions {
+    readonly keyId?: string | undefined;
+    readonly keySecret?: string | undefined;
+    /** The API's base (default `https://api.razorpay.com/v1`). */
+    readonly baseUrl?: string | undefined;
+    /** The HTTP client (tests). */
+    readonly fetch?: typeof fetch;
+}
+export declare function razorpayAdapter(options?: RazorpayOptions): PaymentAdapter;
+/** Razorpay with its keys from the environment, read on first use. */
+export declare function razorpayFromEnvironment(env?: NodeJS.ProcessEnv): PaymentAdapter;

package/dist/payment/razorpay.js

@@ -0,0 +1,149 @@
+/**
+ * The Razorpay adapter (India; RFC 0017 §5.5), on Payment Links: a link per transaction (`reference_id` = its
+ * reference; amounts in subunits) whose page the customer pays on, back to the return URL. Razorpay's webhook
+ * (`payment_link.paid`) is set up in its dashboard with the provider's endpoint URL and **the endpoint's secret**:
+ * `X-Razorpay-Signature` (HMAC-SHA256, hex, of the raw body) is checked with it, `x-razorpay-event-id` makes deliveries
+ * idempotent. On the customer's return (and when asked) the adapter fetches the link from Razorpay by the id it
+ * kept — what the browser brings is not used.
+ *
+ * Credentials come from the environment, never from records: `SHUTRO_ERP_RAZORPAY_KEY_ID` and
+ * `SHUTRO_ERP_RAZORPAY_KEY_SECRET`. Test keys (`rzp_test_…`) serve providers in test mode, live keys live ones.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { fromSubunits, toSubunits } from './money.js';
+const text = (v) => (v === undefined || v === null ? '' : String(v));
+/** What a payment link says of its payment. */
+function linkResult(reference, link) {
+    if (text(link['reference_id']) !== reference)
+        return null;
+    const status = text(link['status']);
+    const currency = text(link['currency']) || 'INR';
+    if (status === 'paid') {
+        const payments = Array.isArray(link['payments']) ? link['payments'] : [];
+        return {
+            reference,
+            status: 'done',
+            providerReference: text(payments.at(-1)?.['payment_id']) || text(link['id']) || null,
+            amount: fromSubunits(Number(link['amount_paid'] ?? 0), currency),
+            currency,
+        };
+    }
+    if (status === 'expired' || status === 'cancelled')
+        return { reference, status: 'cancelled', providerReference: text(link['id']) || null };
+    return { reference, status: 'pending', providerReference: text(link['id']) || null };
+}
+export function razorpayAdapter(options = {}) {
+    const keyId = options.keyId ?? '';
+    const keySecret = options.keySecret ?? '';
+    const base = (options.baseUrl || 'https://api.razorpay.com/v1').replace(/\/$/, '');
+    const http = options.fetch ?? fetch;
+    const ready = keyId !== '' && keySecret !== '';
+    const call = async (method, path, body) => {
+        if (!ready)
+            throw new Error('Razorpay is not configured: set SHUTRO_ERP_RAZORPAY_KEY_ID and SHUTRO_ERP_RAZORPAY_KEY_SECRET.');
+        const res = await http(`${base}${path}`, {
+            method,
+            headers: {
+                authorization: `Basic ${Buffer.from(`${keyId}:${keySecret}`).toString('base64')}`,
+                'content-type': 'application/json',
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: AbortSignal.timeout(30_000),
+        });
+        const answer = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            const error = (answer['error'] ?? {});
+            throw new Error(`Razorpay answered ${res.status}: ${text(error['description']) || 'no detail'}.`);
+        }
+        return answer;
+    };
+    const fetchLink = (id) => call('GET', `/payment_links/${encodeURIComponent(id)}`);
+    return {
+        code: 'razorpay',
+        configured: (mode) => ready && keyId.startsWith(mode === 'test' ? 'rzp_test_' : 'rzp_live_'),
+        async createPayment(request) {
+            const phone = (request.customer.phone ?? '').replace(/[^\d+]/g, '');
+            const link = await call('POST', '/payment_links', {
+                amount: toSubunits(request.amount, request.currency),
+                currency: request.currency,
+                reference_id: request.reference,
+                description: request.description.slice(0, 2048),
+                customer: {
+                    name: request.customer.name,
+                    ...(request.customer.email === null ? {} : { email: request.customer.email }),
+                    ...(phone.length >= 8 && phone.length <= 14 ? { contact: phone } : {}),
+                },
+                notify: { sms: false, email: false },
+                reminder_enable: false,
+                callback_url: request.returnUrl,
+                callback_method: 'get',
+            });
+            const id = text(link['id']);
+            const page = text(link['short_url']);
+            if (id === '' || page === '')
+                throw new Error('Razorpay made no payment link.');
+            return { redirectUrl: page, providerReference: id };
+        },
+        verifyCallback(call, secret) {
+            const given = Buffer.from(call.headers['x-razorpay-signature'] ?? '');
+            const expected = Buffer.from(createHmac('sha256', secret).update(call.body).digest('hex'));
+            if (given.length !== expected.length || !timingSafeEqual(given, expected))
+                return null;
+            const id = call.headers['x-razorpay-event-id'] ?? '';
+            return id !== '' ? id : null;
+        },
+        readCallback(call) {
+            const event = call.json;
+            const payload = (event?.['payload'] ?? {});
+            const link = (payload['payment_link']?.['entity'] ??
+                null);
+            if (link === null)
+                return null;
+            const reference = text(link['reference_id']);
+            const kind = text(event?.['event']);
+            if (kind === 'payment_link.paid') {
+                const payment = (payload['payment']?.['entity'] ?? {});
+                const currency = text(link['currency']) || 'INR';
+                return {
+                    reference,
+                    status: 'done',
+                    providerReference: text(payment['id']) || text(link['id']) || null,
+                    amount: fromSubunits(Number(link['amount_paid'] ?? payment['amount'] ?? 0), currency),
+                    currency,
+                };
+            }
+            if (kind === 'payment_link.expired' || kind === 'payment_link.cancelled')
+                return { reference, status: 'cancelled', providerReference: text(link['id']) || null };
+            return null;
+        },
+        async returned({ reference, providerReference }) {
+            if (providerReference === null || providerReference === '')
+                return null;
+            const result = linkResult(reference, await fetchLink(providerReference));
+            return result?.status === 'pending' ? null : result;
+        },
+        async status(reference, _mode, providerReference) {
+            if (!ready || providerReference === null || providerReference === '')
+                return null;
+            return linkResult(reference, await fetchLink(providerReference));
+        },
+    };
+}
+/** Razorpay with its keys from the environment, read on first use. */
+export function razorpayFromEnvironment(env = process.env) {
+    let made;
+    const real = () => (made ??= razorpayAdapter({
+        keyId: env['KOSH_RAZORPAY_KEY_ID'],
+        keySecret: env['KOSH_RAZORPAY_KEY_SECRET'],
+        baseUrl: env['KOSH_RAZORPAY_BASE_URL'],
+    }));
+    return {
+        code: 'razorpay',
+        configured: (mode) => real().configured(mode),
+        createPayment: (request) => real().createPayment(request),
+        verifyCallback: (call, secret) => real().verifyCallback(call, secret),
+        readCallback: (call) => real().readCallback(call),
+        returned: (input) => real().returned?.(input) ?? Promise.resolve(null),
+        status: (reference, mode, providerReference) => real().status(reference, mode, providerReference),
+    };
+}

package/dist/payment/sslcommerz.js

@@ -180,6 +180,6 @@ export function sslcommerzFromEnvironment(env = process.env) {
         createPayment: (request) => real().createPayment(request),
         verifyCallback: (call, secret) => real().verifyCallback(call, secret),
         readCallback: (call) => real().readCallback(call),
-        status: (reference, mode) => real().status(reference, mode),
+        status: (reference, mode, providerReference) => real().status(reference, mode, providerReference),
     };
 }

package/dist/payment/stripe.d.ts

@@ -0,0 +1,15 @@
+import type { PaymentAdapter } from './providers.js';
+export interface StripeOptions {
+    readonly secretKey?: string | undefined;
+    /** The API's base (default `https://api.stripe.com/v1`). */
+    readonly baseUrl?: string | undefined;
+    /** How old a signed event may be, in seconds (default 300). */
+    readonly tolerance?: number;
+    /** The HTTP client (tests). */
+    readonly fetch?: typeof fetch;
+    /** The clock (tests). */
+    readonly now?: () => number;
+}
+export declare function stripeAdapter(options?: StripeOptions): PaymentAdapter;
+/** Stripe with its key from the environment, read on first use. */
+export declare function stripeFromEnvironment(env?: NodeJS.ProcessEnv): PaymentAdapter;