@birtalanrobert/commerce 1.0.0

package/dist/providers/stripe.js

@@ -0,0 +1,221 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StripeConnect = void 0;
+const stripe_1 = __importDefault(require("stripe"));
+/**
+ * Stripe Connect, as the port describes it.
+ *
+ * **Destination charges throughout.** The money is created on our platform
+ * account and transferred immediately to the business, with our cut taken as an
+ * application fee — which is what keeps this a software company rather than a
+ * regulated one, and what lets the business see its own payouts in its own
+ * Stripe dashboard.
+ *
+ * Everything the provider does *not* need to decide is decided before this file
+ * is reached: what a deposit comes to, whether a business may sell, what a
+ * refund leaves. What is here is the part that genuinely needs somebody else's
+ * money-moving licence.
+ */
+class StripeConnect {
+    options;
+    name = 'stripe';
+    stripe;
+    constructor(options) {
+        this.options = options;
+        this.stripe = options.client ?? new stripe_1.default(options.secretKey);
+    }
+    async account(externalId, country, email) {
+        const account = externalId
+            ? await this.stripe.accounts.retrieve(externalId)
+            : await this.stripe.accounts.create({
+                type: 'express',
+                country,
+                ...(email ? { email } : {}),
+                capabilities: { card_payments: { requested: true }, transfers: { requested: true } },
+            });
+        return interpretAccount(account);
+    }
+    async onboard(externalId, returnUrl, refreshUrl) {
+        const link = await this.stripe.accountLinks.create({
+            account: externalId,
+            type: 'account_onboarding',
+            return_url: returnUrl,
+            /*
+             * Where the business lands if the link has aged out.
+             *
+             * Stripe's onboarding links are short-lived and somebody *will* open one
+             * the next morning. Without this they meet an error page from a company
+             * they have never heard of, halfway through giving it their passport.
+             */
+            refresh_url: refreshUrl,
+        });
+        return { url: link.url, expiresAt: new Date(link.expires_at * 1000) };
+    }
+    async charge(request) {
+        try {
+            const intent = await this.stripe.paymentIntents.create({
+                amount: request.amount,
+                currency: request.currency.toLowerCase(),
+                /*
+                 * The money lands on the business's account, not ours.
+                 *
+                 * `transfer_data.destination` with `application_fee_amount` is the
+                 * destination-charge shape: we never hold their funds, and their
+                 * payouts appear in their own dashboard.
+                 */
+                transfer_data: { destination: request.account },
+                ...(request.applicationFee > 0 ? { application_fee_amount: request.applicationFee } : {}),
+                capture_method: request.capture ? 'automatic' : 'manual',
+                ...(request.description ? { description: request.description } : {}),
+                // Carried through so a webhook can be matched back to what it paid
+                // for without a lookup table of our own.
+                metadata: { subject: request.subject },
+                automatic_payment_methods: { enabled: true },
+            }, 
+            // The provider's own idempotency, so a retried request — a timeout, a
+            // double submit — does not charge somebody twice.
+            { idempotencyKey: request.reference });
+            return interpretIntent(intent);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    }
+    async capture(externalId, amount) {
+        try {
+            const intent = await this.stripe.paymentIntents.capture(externalId, amount === undefined ? undefined : { amount_to_capture: amount });
+            return interpretIntent(intent);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    }
+    async release(externalId) {
+        await this.stripe.paymentIntents.cancel(externalId);
+    }
+    async refund(request) {
+        const refund = await this.stripe.refunds.create({
+            payment_intent: request.externalId,
+            amount: request.amount,
+            metadata: { reason: request.reason.slice(0, 500) },
+        }, { idempotencyKey: request.reference });
+        return { externalId: refund.id };
+    }
+    verify(payload, signature) {
+        if (!signature || !this.options.webhookSecret)
+            return undefined;
+        let event;
+        try {
+            event = this.stripe.webhooks.constructEvent(payload, signature, this.options.webhookSecret);
+        }
+        catch {
+            /*
+             * A forgery, or a payload something re-encoded on the way in.
+             *
+             * `undefined` rather than a thrown error: the caller answers a request
+             * that did not come from Stripe with a flat acknowledgement, not with a
+             * message describing what was wrong with it.
+             */
+            return undefined;
+        }
+        return interpretEvent(event);
+    }
+}
+exports.StripeConnect = StripeConnect;
+/** Stripe's account shape, reduced to the question anybody actually asks. */
+function interpretAccount(account) {
+    const requirements = [
+        ...(account.requirements?.currently_due ?? []),
+        ...(account.requirements?.past_due ?? []),
+    ];
+    /*
+     * `charges_enabled` and `payouts_enabled` together, not either alone.
+     *
+     * A business that can take money but cannot be paid out is worse than one
+     * that cannot sell yet: the customer is charged and the money sits with the
+     * provider, and the first anybody hears is the business asking where it is.
+     */
+    const ready = account.charges_enabled === true && account.payouts_enabled === true;
+    return {
+        externalId: account.id,
+        status: ready ? 'ready' : requirements.length > 0 ? 'restricted' : 'pending',
+        requirements: [...new Set(requirements)],
+    };
+}
+function interpretIntent(intent) {
+    const state = intent.status === 'succeeded'
+        ? 'captured'
+        : intent.status === 'requires_capture'
+            ? 'authorized'
+            : intent.status === 'canceled'
+                ? 'failed'
+                : 'pending';
+    const charge = intent.latest_charge;
+    const card = typeof charge === 'object' && charge?.payment_method_details?.card
+        ? `${charge.payment_method_details.card.brand} ending ${charge.payment_method_details.card.last4}`
+        : undefined;
+    return {
+        externalId: intent.id,
+        state,
+        ...(intent.next_action?.redirect_to_url?.url
+            ? { redirectUrl: intent.next_action.redirect_to_url.url }
+            : {}),
+        ...(card ? { instrument: card } : {}),
+        ...(intent.last_payment_error?.message ? { detail: intent.last_payment_error.message } : {}),
+    };
+}
+function interpretEvent(event) {
+    switch (event.type) {
+        case 'payment_intent.succeeded':
+        case 'payment_intent.amount_capturable_updated':
+        case 'payment_intent.payment_failed': {
+            const intent = event.data.object;
+            const result = interpretIntent(intent);
+            return {
+                kind: 'payment',
+                externalId: intent.id,
+                state: event.type === 'payment_intent.payment_failed'
+                    ? 'failed'
+                    : result.state === 'captured'
+                        ? 'captured'
+                        : 'authorized',
+                ...(result.instrument ? { instrument: result.instrument } : {}),
+                ...(result.detail ? { detail: result.detail } : {}),
+            };
+        }
+        case 'charge.refunded': {
+            const charge = event.data.object;
+            return {
+                kind: 'payment',
+                externalId: typeof charge.payment_intent === 'string' ? charge.payment_intent : charge.id,
+                state: 'refunded',
+            };
+        }
+        case 'account.updated': {
+            const account = event.data.object;
+            return { kind: 'account', externalId: account.id, accountStatus: interpretAccount(account) };
+        }
+        default:
+            /*
+             * Everything else is acknowledged and ignored.
+             *
+             * Stripe sends a great many event types and a deployment's subscription
+             * will drift; treating an unknown one as an error means retries and an
+             * alert for something that was never any of our business.
+             */
+            return { kind: 'other', externalId: event.id };
+    }
+}
+/** A provider's refusal, as a result rather than an exception. */
+function failure(error) {
+    const message = error instanceof stripe_1.default.errors.StripeError
+        ? (error.message ?? 'The payment was refused.')
+        : error instanceof Error
+            ? error.message
+            : 'The payment was refused.';
+    return { externalId: '', state: 'failed', detail: message };
+}
+//# sourceMappingURL=stripe.js.map

package/dist/providers/stripe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.js","sourceRoot":"","sources":["../../src/providers/stripe.ts"],"names":[],"mappings":"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"}

package/nestjs/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../dist/nestjs/index.js",
+  "types": "../dist/nestjs/index.d.ts",
+  "sideEffects": false
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@birtalanrobert/commerce",
+  "version": "1.0.0",
+  "description": "Taking money on a business's behalf: payout onboarding, payments, refunds and the record of both",
+  "license": "AGPL-3.0-only",
+  "author": "Robert Birtalan",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./nestjs": {
+      "types": "./dist/nestjs/index.d.ts",
+      "default": "./dist/nestjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "nestjs",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "stripe": "^22.6.0",
+    "@birtalanrobert/context": "^1.1.0",
+    "@birtalanrobert/money": "^1.0.0",
+    "@birtalanrobert/database": "^1.0.0",
+    "@birtalanrobert/tenancy": "^1.1.0",
+    "@birtalanrobert/http": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "typeorm": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/deposits.ts

@@ -0,0 +1,96 @@
+/**
+ * What a customer has to pay up front, worked out the way a person would check.
+ *
+ * **Pure, and at the root entry point on purpose.** A console shows "30% of
+ * 150,00 lei is 45,00 lei" while somebody drags a slider, and a booking page
+ * shows the same number before anybody types a card into it. Neither may reach
+ * for a database, and both must arrive at exactly the number the charge will be.
+ */
+
+/** How a business asks for money before the work. */
+export type DepositKind = 'none' | 'percentage' | 'fixed' | 'full';
+
+export interface DepositPolicy {
+  readonly kind: DepositKind;
+  /**
+   * Whole percent for `percentage`, minor units for `fixed`, ignored otherwise.
+   *
+   * Whole percent rather than a fraction because it is typed into a box by a
+   * person: "30" is what a tattoo studio says, and `0.3` is what turns into
+   * `0.30000000000000004` two operations later.
+   */
+  readonly value: number;
+}
+
+/**
+ * The deposit for a given total.
+ *
+ * **Rounded to the nearest minor unit, and never past the total.** A percentage
+ * of an odd amount is a fraction of a ban, and a deposit larger than the price
+ * is what a misconfigured 150% produces — both are refused here rather than at
+ * the provider, where the message is in English and mentions an integer.
+ */
+export function depositFor(total: number, policy: DepositPolicy): number {
+  if (total <= 0) return 0;
+
+  switch (policy.kind) {
+    case 'none':
+      return 0;
+    case 'full':
+      return total;
+    case 'fixed':
+      // A fixed deposit above the price is a configuration mistake, and taking
+      // more than the thing costs is the worst possible way to surface it.
+      return clamp(Math.round(policy.value), total);
+    case 'percentage':
+      /*
+       * Rounded half away from zero, which is what a person doing it by hand
+       * produces. `Math.round` rounds half *up*, which differs on negatives —
+       * irrelevant here because a total is never negative, and stated so that
+       * the day it is, this is the line to look at.
+       */
+      return clamp(Math.round((total * clamp(policy.value, 100)) / 100), total);
+    default:
+      return 0;
+  }
+}
+
+/** What is still owed after a deposit. Never negative, whatever was paid. */
+export const balanceAfter = (total: number, paid: number): number => Math.max(0, total - paid);
+
+const clamp = (value: number, max: number): number => Math.min(Math.max(0, value), max);
+
+/**
+ * Whether a business may take money at all.
+ *
+ * The provider's onboarding is the gate, and it is a hard one: funds go
+ * directly to the business and our fee is taken on top, so until the provider
+ * has verified who they are there is nowhere for the money to go. Every
+ * consumer of this package has to answer the same question in front of the
+ * same button, which is why it is here rather than written three times.
+ */
+export type PayoutStatus = 'none' | 'pending' | 'restricted' | 'ready';
+
+export const canTakeMoney = (status: PayoutStatus): boolean => status === 'ready';
+
+/**
+ * What to tell a business that cannot yet, in the order it becomes true.
+ *
+ * Returned as a key rather than a sentence: the words belong to whichever
+ * product is showing them, and a package that shipped English into a Romanian
+ * console would be worse than one that shipped nothing.
+ */
+export const payoutBlockReason = (
+  status: PayoutStatus,
+): 'not-started' | 'in-progress' | 'needs-attention' | null => {
+  switch (status) {
+    case 'none':
+      return 'not-started';
+    case 'pending':
+      return 'in-progress';
+    case 'restricted':
+      return 'needs-attention';
+    case 'ready':
+      return null;
+  }
+};

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Taking money on a business's behalf.
+ *
+ * **We never hold anybody's funds.** The customer pays the business directly
+ * and our fee is taken on top as an application fee — a hard architectural rule
+ * rather than a preference, because holding third-party money turns a software
+ * company into a regulated payments business. Every design decision here
+ * follows from it.
+ *
+ * Not to be confused with `@birtalanrobert/billing`, which is the other
+ * direction: the business paying *us* for a subscription. Conflating the two is
+ * the mistake that makes both hard to reason about — they differ in who pays
+ * whom, in which Stripe account, and in what happens when one fails.
+ *
+ * **This entry point is pure.** What a deposit comes to and whether a business
+ * may sell yet are decided without a database or a provider, because a console
+ * shows both while somebody drags a slider. Everything needing storage or
+ * somebody else's money-moving licence is behind `/nestjs`.
+ */
+export {
+  balanceAfter,
+  canTakeMoney,
+  depositFor,
+  payoutBlockReason,
+  type DepositKind,
+  type DepositPolicy,
+  type PayoutStatus,
+} from './deposits';
+
+export type {
+  ChargeRequest,
+  ChargeResult,
+  OnboardingLink,
+  PaymentProvider,
+  ProviderAccount,
+  ProviderEvent,
+  RefundRequest,
+} from './providers/port';
+
+export { StripeConnect, type StripeConnectOptions } from './providers/stripe';

package/src/migrations/1789800000000-CreateCommerce.ts

@@ -0,0 +1,156 @@
+import type { MigrationInterface, QueryRunner } from 'typeorm';
+import { enableRlsSql } from '@birtalanrobert/tenancy';
+
+/**
+ * Taking money on a business's behalf.
+ *
+ * **We never hold anybody's funds.** The customer pays the business directly
+ * and our fee is taken on top — a hard architectural rule rather than a
+ * preference, because holding third-party money turns a software company into a
+ * regulated payments business. Everything here follows from that.
+ *
+ * ## Three tables, and why each is separate
+ *
+ * `mortar_payout_accounts` is the gate. Until the provider has verified who a
+ * business is, there is nowhere for a payment to land, and every product that
+ * sells on somebody's behalf has to answer that same question in front of the
+ * same button.
+ *
+ * `mortar_payments` is the record, and it **outlives the provider**: amounts,
+ * dates, what it was for and who decided are stored in full rather than as
+ * identifiers to fetch later. A business must be able to produce its own
+ * takings years after the provider account is closed or the vendor replaced.
+ *
+ * `mortar_payment_refunds` is one row per act of giving money back. Several
+ * partial refunds against one payment is ordinary, and a single column cannot
+ * say when each happened or why.
+ *
+ * ## No foreign key to whatever was paid for
+ *
+ * One product takes a deposit against an appointment, another against a seat, a
+ * third against a table's tab. A key to any one of them is exactly what would
+ * stop this table being shared, so the subject is a string the owning product
+ * writes and reads.
+ */
+export class CreateCommerce1789800000000 implements MigrationInterface {
+  name = 'CreateCommerce1789800000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE "mortar_payout_accounts" (
+        "id" uuid NOT NULL DEFAULT gen_random_uuid(),
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        "tenant_id" uuid NOT NULL,
+        "provider" varchar(32) NOT NULL DEFAULT 'stripe',
+        "external_id" varchar(128) NOT NULL,
+        "status" varchar(16) NOT NULL DEFAULT 'pending',
+        -- What the provider still wants, in its own words. "A photograph of the
+        -- director's identity document" is actionable; "restricted" is a
+        -- support conversation.
+        "requirements" jsonb NOT NULL DEFAULT '[]'::jsonb,
+        "ready_at" timestamptz,
+        CONSTRAINT "pk_payout_accounts" PRIMARY KEY ("id"),
+        CONSTRAINT "uq_payout_accounts_tenant" UNIQUE ("tenant_id", "provider"),
+        CONSTRAINT "ck_payout_accounts_status"
+          CHECK ("status" IN ('none', 'pending', 'restricted', 'ready'))
+      )
+    `);
+
+    /* A webhook arrives naming the provider's account, not ours. */
+    await queryRunner.query(`
+      CREATE INDEX "ix_payout_accounts_external"
+        ON "mortar_payout_accounts" ("provider", "external_id")
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE "mortar_payments" (
+        "id" uuid NOT NULL DEFAULT gen_random_uuid(),
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        "tenant_id" uuid NOT NULL,
+        -- What it was for, as the owning product names it. No foreign key: see
+        -- the note above.
+        "subject" varchar(160) NOT NULL,
+        -- 'card' is the only one this package processes. The rest are recorded
+        -- rather than taken, and recording them is not a lesser feature: a
+        -- report that counts only what a provider processed tells a salon a
+        -- fraction of its own takings and looks complete.
+        "method" varchar(16) NOT NULL,
+        "state" varchar(24) NOT NULL DEFAULT 'pending',
+        "amount" bigint NOT NULL,
+        "currency" varchar(3) NOT NULL,
+        -- Recorded even when zero: "charged nothing" and "nobody wrote down
+        -- what was charged" are different facts.
+        "application_fee" bigint NOT NULL DEFAULT 0,
+        "refunded" bigint NOT NULL DEFAULT 0,
+        "provider" varchar(32),
+        "external_id" varchar(128),
+        -- "Visa ending 4242". Never the number, never anything chargeable from
+        -- a database dump.
+        "instrument" varchar(40),
+        "taken_at" timestamptz,
+        "detail" varchar(400),
+        "recorded_by" uuid,
+        CONSTRAINT "pk_payments" PRIMARY KEY ("id"),
+        CONSTRAINT "uq_payments_tenant_id" UNIQUE ("tenant_id", "id"),
+        CONSTRAINT "ck_payments_method"
+          CHECK ("method" IN ('card', 'cash', 'terminal', 'voucher', 'transfer')),
+        CONSTRAINT "ck_payments_state"
+          CHECK ("state" IN ('pending', 'authorized', 'captured', 'failed',
+                             'refunded', 'partially_refunded', 'cancelled')),
+        -- Money is never negative here, and nothing may be given back twice.
+        CONSTRAINT "ck_payments_amount" CHECK ("amount" >= 0),
+        CONSTRAINT "ck_payments_refunded"
+          CHECK ("refunded" >= 0 AND "refunded" <= "amount")
+      )
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX "ix_payments_subject" ON "mortar_payments" ("tenant_id", "subject")
+    `);
+    /* Every revenue report reads this: a tenant's takings over a period. */
+    await queryRunner.query(`
+      CREATE INDEX "ix_payments_taken" ON "mortar_payments" ("tenant_id", "taken_at")
+    `);
+    /* And a webhook arrives naming the provider's payment. */
+    await queryRunner.query(`
+      CREATE INDEX "ix_payments_external" ON "mortar_payments" ("provider", "external_id")
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE "mortar_payment_refunds" (
+        "id" uuid NOT NULL DEFAULT gen_random_uuid(),
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        "tenant_id" uuid NOT NULL,
+        "payment_id" uuid NOT NULL,
+        "amount" bigint NOT NULL,
+        -- Required. "We refunded her ninety lei in March" is a question
+        -- somebody asks a year later, and a blank reason cannot be defended.
+        "reason" varchar(400) NOT NULL,
+        "external_id" varchar(128),
+        "refunded_by" uuid,
+        CONSTRAINT "pk_payment_refunds" PRIMARY KEY ("id"),
+        CONSTRAINT "fk_payment_refunds_payment" FOREIGN KEY ("tenant_id", "payment_id")
+          REFERENCES "mortar_payments" ("tenant_id", "id") ON DELETE RESTRICT,
+        CONSTRAINT "ck_payment_refunds_amount" CHECK ("amount" > 0)
+      )
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX "ix_payment_refunds_payment"
+        ON "mortar_payment_refunds" ("tenant_id", "payment_id")
+    `);
+
+    for (const table of ['mortar_payout_accounts', 'mortar_payments', 'mortar_payment_refunds']) {
+      for (const statement of enableRlsSql(table)) await queryRunner.query(statement);
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS "mortar_payment_refunds" CASCADE`);
+    await queryRunner.query(`DROP TABLE IF EXISTS "mortar_payments" CASCADE`);
+    await queryRunner.query(`DROP TABLE IF EXISTS "mortar_payout_accounts" CASCADE`);
+  }
+}