shutro-erp 0.3.1 → 0.3.3

package/dist/payment/module.js

@@ -0,0 +1,77 @@
+/**
+ * The data layer of online payments (RFC 0017 §5.5): a company's payment providers (the adapter, its mode, the
+ * journal the money arrives in, the inbound webhook its callbacks come through) and the transactions customers
+ * start from the portal (the invoice, the amount, the provider's reference, the state, the `account.payment` that
+ * settled it). Credentials are never in records: an adapter reads them from the environment; the callbacks' secret
+ * is the endpoint's.
+ */
+import { randomBytes } from 'node:crypto';
+import { accountPortalShutro } from '../account_portal/index.js';
+import { integrationsShutro } from '../integrations/index.js';
+import { defineModel, defineModule, f } from './.kosh/bindings.js';
+const ALL = ['read', 'write', 'create', 'unlink', 'export', 'import'];
+/** A transaction's reference: what the provider is told and gives back. */
+export const newReference = () => `PAY-${randomBytes(9).toString('base64url')}`;
+/** The adapters Kosh ships; a module adding one extends this selection. */
+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',
+    recName: 'name',
+    companyScoped: { required: true },
+    order: ['sequence asc', 'id asc'],
+    tracking: ['state', 'journal'],
+    access: { 'account.user': ['read'], 'account.manager': ALL },
+    fields: {
+        name: f.char({ required: true }),
+        code: f.selection(PROVIDERS, { required: true, default: 'fake', label: 'Provider' }),
+        state: f.selection({ disabled: 'Disabled', test: 'Test', live: 'Live' }, { required: true, default: 'test', label: 'Mode' }),
+        /** Where the money arrives: the payments are registered in this bank (or cash) journal. */
+        journal: f.many2one('account.journal', { required: true, checkCompany: true }),
+        /** The inbound webhook the provider's callbacks come through (made with the provider). */
+        endpoint: f.many2one('webhook.endpoint', { label: 'Callback endpoint' }),
+        sequence: f.integer({ required: true, default: 10 }),
+    },
+});
+export const PaymentTransaction = defineModel('payment.transaction', {
+    label: 'Payment transaction',
+    recName: 'reference',
+    companyScoped: { required: true },
+    order: ['id desc'],
+    tracking: ['state'],
+    access: {
+        'account.invoicing': ['read'],
+        'account.user': ['read', 'export'],
+        'account.manager': ['read', 'export'],
+    },
+    fields: {
+        reference: f.char({ required: true, index: 'unique', default: newReference }),
+        provider: f.many2one('payment.provider', { required: true, checkCompany: true }),
+        move: f.many2one('account.move', { required: true, label: 'Invoice', checkCompany: true }),
+        partner: f.many2one('res.partner', { label: 'Customer' }),
+        currency: f.many2one('res.currency', { required: true }),
+        amount: f.monetary({ currency: 'currency', required: true }),
+        state: f.selection({
+            pending: 'Pending',
+            done: 'Paid',
+            failed: 'Failed',
+            cancelled: 'Cancelled',
+        }, { required: true, default: 'pending' }),
+        providerReference: f.char({ label: 'Provider reference' }),
+        /** The payment registered when the provider confirmed. */
+        payment: f.many2one('account.payment', { label: 'Payment' }),
+        error: f.text(),
+        doneAt: f.datetime({ label: 'Paid at' }),
+    },
+});
+export const paymentShutro = defineModule({
+    name: 'payment',
+    version: '0.1.0',
+    depends: [accountPortalShutro, integrationsShutro],
+    models: [PaymentProvider, PaymentTransaction],
+});

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

@@ -0,0 +1,75 @@
+import type { InboundCall } from '../modules-sdk/index.js';
+export type PaymentStatus = 'pending' | 'done' | 'failed' | 'cancelled';
+export interface PaymentRequest {
+    /** The transaction's reference: what the provider gives back. */
+    readonly reference: string;
+    /** Decimal string in the currency's unit (`'1250.00'`). */
+    readonly amount: string;
+    /** ISO 4217 (`BDT`). */
+    readonly currency: string;
+    /** What is paid (`Invoice INV/2026/0042`). */
+    readonly description: string;
+    readonly customer: {
+        readonly name: string;
+        readonly email: string | null;
+        readonly phone: string | null;
+        readonly street: string | null;
+        readonly city: string | null;
+        readonly zip: string | null;
+        /** ISO 3166 alpha-2. */
+        readonly country: string | null;
+    };
+    /** Where the provider sends the customer back (GET or POST; the server forwards them to the portal). */
+    readonly returnUrl: string;
+    /** The inbound webhook the provider calls (absolute URL). */
+    readonly callbackUrl: string;
+    readonly mode: 'test' | 'live';
+}
+export interface PaymentResult {
+    readonly reference: string;
+    readonly status: PaymentStatus;
+    readonly providerReference: string | null;
+    /** What the provider says was paid; checked against the transaction. */
+    readonly amount?: string;
+    readonly currency?: string;
+    readonly error?: string;
+}
+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 (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', 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";
+export declare const fakeAdapter: PaymentAdapter & {
+    /** The payment the fake checkout shows. */
+    pending(reference: string): PaymentRequest | null;
+    /** The customer paid or declined on the fake checkout: the result and the signed callback body. */
+    complete(reference: string, paid: boolean, secret: string): {
+        body: string;
+        signature: string;
+    } | null;
+};
+/** The adapters by code. */
+export declare const ADAPTERS: ReadonlyMap<string, PaymentAdapter>;

package/dist/payment/providers.js

@@ -0,0 +1,77 @@
+/**
+ * Payment provider adapters (RFC 0017 §5.5). An adapter starts a payment at the provider (a page to send the customer
+ * to), reads the provider's callbacks (verified with the callback endpoint's secret), and asks the provider for a
+ * payment's status (when the customer returns before the callback). Credentials come from the environment, never
+ * from records. The fake adapter moves no money: its checkout page (served by this module) lets the customer pay or
+ * decline, and it calls back like a real provider, signed.
+ */
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+/** The fake adapter's header: HMAC-SHA256 (hex) of the raw body with the endpoint's secret. */
+export const FAKE_SIGNATURE = 'x-fake-signature';
+/** What the fake checkout knows (per process: it is for tests and demonstrations). */
+const fakeLedger = new Map();
+export const fakeAdapter = {
+    code: 'fake',
+    configured: (mode) => mode === 'test',
+    async createPayment(request) {
+        fakeLedger.set(request.reference, {
+            reference: request.reference,
+            status: 'pending',
+            providerReference: null,
+            request,
+        });
+        return {
+            redirectUrl: `/api/v1/payment/fake/checkout/${encodeURIComponent(request.reference)}`,
+        };
+    },
+    verifyCallback(call, secret) {
+        const given = Buffer.from(call.headers[FAKE_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.json?.id;
+        return typeof id === 'string' && id !== '' ? id : null;
+    },
+    readCallback(call) {
+        const event = call.json;
+        if (typeof event?.reference !== 'string')
+            return null;
+        return {
+            reference: event.reference,
+            status: event.status ?? 'pending',
+            providerReference: event.providerReference ?? null,
+            ...(event.amount === undefined ? {} : { amount: event.amount }),
+            ...(event.currency === undefined ? {} : { currency: event.currency }),
+        };
+    },
+    async status(reference) {
+        const known = fakeLedger.get(reference);
+        if (known === undefined)
+            return null;
+        const { request: _request, ...result } = known;
+        return result;
+    },
+    pending(reference) {
+        const known = fakeLedger.get(reference);
+        return known?.status === 'pending' ? known.request : null;
+    },
+    complete(reference, paid, secret) {
+        const known = fakeLedger.get(reference);
+        if (known === undefined || known.status !== 'pending')
+            return null;
+        const result = {
+            reference,
+            status: paid ? 'done' : 'failed',
+            providerReference: `FAKE-${randomUUID().slice(0, 8).toUpperCase()}`,
+            amount: known.request.amount,
+            currency: known.request.currency,
+        };
+        fakeLedger.set(reference, { ...result, request: known.request });
+        const body = JSON.stringify({ id: `evt_${randomUUID()}`, ...result });
+        return { body, signature: createHmac('sha256', secret).update(body).digest('hex') };
+    },
+};
+/** The adapters by code. */
+export const ADAPTERS = new Map([
+    [fakeAdapter.code, fakeAdapter],
+]);

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/settle.d.ts

@@ -0,0 +1,11 @@
+import type { Env } from './.kosh/bindings.js';
+import type { PaymentResult } from './providers.js';
+export interface Settled {
+    readonly reference: string;
+    readonly state: string;
+    /** False when it was settled before (a repeated callback, a return after the callback). */
+    readonly changed: boolean;
+    readonly payment: number | null;
+}
+/** Applies the provider's result to transaction `result.reference`, as the system in the transaction's company. */
+export declare function settle(env: Env, result: PaymentResult): Promise<Settled | null>;

package/dist/payment/settle.js

@@ -0,0 +1,59 @@
+/**
+ * Settling a transaction (RFC 0017 §5.5): the provider's word — by its callback or asked when the customer returns —
+ * moves a pending transaction to paid, failed or cancelled. Paid registers an `account.payment` for the invoice in
+ * the provider's journal (Accounting posts and reconciles it), **once**: a transaction-scoped advisory lock on the
+ * reference serialises a callback and a return arriving together, and a paid transaction is never settled again
+ * (a failed or cancelled one becomes paid if the provider confirms it later).
+ */
+import { registerPayment } from '../accounting/index.js';
+import { orm } from '../server/orm.js';
+/** Applies the provider's result to transaction `result.reference`, as the system in the transaction's company. */
+export async function settle(env, result) {
+    await env.sql `SELECT pg_advisory_xact_lock(hashtext(${`payment:${result.reference}`}))`;
+    const found = await env
+        .model('payment.transaction')
+        .search({ where: { reference: result.reference }, limit: 1 });
+    if (found.length === 0)
+        return null;
+    const [tx] = await found.load({ provider: true, currency: true, move: true });
+    if (tx === undefined)
+        return null;
+    const same = { reference: tx.reference, changed: false };
+    // Paid is final. A failure or cancellation is not: the provider may still confirm the payment later (a retry,
+    // a failure reported early) — then it is paid. Nothing else changes a settled transaction.
+    if (tx.state === 'done' ||
+        result.status === 'pending' ||
+        (tx.state !== 'pending' && result.status !== 'done'))
+        return { ...same, state: tx.state, payment: tx.payment?.id ?? null };
+    if (result.status !== 'done') {
+        await found.write({
+            state: result.status,
+            providerReference: result.providerReference,
+            error: result.error ?? (result.status === 'failed' ? 'The provider refused the payment.' : null),
+        });
+        return { ...same, state: result.status, changed: true, payment: null };
+    }
+    // What the provider says was paid must be what was asked.
+    const amount = tx.amount.amount;
+    if ((result.amount !== undefined && !orm.toDecimal(result.amount).eq(amount)) ||
+        (result.currency !== undefined && result.currency !== tx.currency.name)) {
+        const error = `The provider reports ${result.amount ?? '?'} ${result.currency ?? ''}, not ${amount.toFixed()} ${tx.currency.name}.`;
+        await found.write({ state: 'failed', providerReference: result.providerReference, error });
+        return { ...same, state: 'failed', changed: true, payment: null };
+    }
+    const payment = await registerPayment(env, {
+        moves: [tx.move.id],
+        journal: tx.provider.journal.id,
+        amount: amount.toFixed(),
+        memo: `${tx.provider.name} ${result.providerReference ?? tx.reference}`,
+    });
+    await found.write({
+        state: 'done',
+        providerReference: result.providerReference,
+        payment: payment.id,
+        error: null,
+        doneAt: new Date(),
+    });
+    await env.flush(); // checks run in this system scope, not at commit (Shutro request #11)
+    return { ...same, state: 'done', changed: true, payment: payment.id };
+}

package/dist/payment/sslcommerz.d.ts

@@ -0,0 +1,12 @@
+import type { PaymentAdapter } from './providers.js';
+export interface SslcommerzOptions {
+    readonly storeId?: string | undefined;
+    readonly storePassword?: string | undefined;
+    /** The sandbox (default) or the live system. */
+    readonly sandbox?: boolean;
+    /** The HTTP client (tests). */
+    readonly fetch?: typeof fetch;
+}
+export declare function sslcommerzAdapter(options?: SslcommerzOptions): PaymentAdapter;
+/** SSLCommerz with its credentials from the environment, read on first use (after the server applied its names). */
+export declare function sslcommerzFromEnvironment(env?: NodeJS.ProcessEnv): PaymentAdapter;