@birtalanrobert/commerce 1.0.0

package/NOTICE

@@ -0,0 +1,45 @@
+mortar
+Copyright (C) 2026 Robert Birtalan
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License along
+with this program. If not, see <https://www.gnu.org/licenses/>.
+
+--------------------------------------------------------------------------------
+
+RIGHTS RESERVED BY THE COPYRIGHT HOLDER
+
+The AGPL is a grant from the copyright holder to everyone else. The copyright
+holder is not a licensee of their own work, and is therefore not bound by these
+terms.
+
+Robert Birtalan, as sole copyright holder, retains the right to use, modify and
+distribute this software under any other terms, including within closed-source
+and commercial products, without triggering any obligation under the AGPL.
+
+Commercial licences for third parties who cannot or do not wish to comply with
+the AGPL are available on request.
+
+--------------------------------------------------------------------------------
+
+CONTRIBUTIONS
+
+Contributions are not currently accepted.
+
+This is deliberate and load-bearing. A contributor retains copyright in their
+contribution unless they assign it. Accepting outside contributions without a
+copyright assignment or a contributor licence agreement would mean the project
+was no longer wholly owned by one copyright holder — and the reserved rights
+above would no longer apply to those parts, because one cannot relicense code
+one does not own.
+
+Should contributions be accepted in future, a CLA assigning copyright to the
+maintainer is a prerequisite, not a formality.

package/README.md

@@ -0,0 +1,79 @@
+# @birtalanrobert/commerce
+
+Taking money **on a business's behalf**: payout onboarding, card payments,
+manually recorded takings, refunds, and the record of all of it.
+
+**We never hold anybody's funds.** The customer pays the business directly and
+our cut is taken on top as an application fee. This is an architectural rule
+rather than a preference — holding third-party money turns a software company
+into a regulated payments business — and everything here follows from it.
+
+Not to be confused with `@birtalanrobert/billing`, which is the other direction:
+the business paying _us_ for a subscription. They differ in who pays whom, in
+which provider account, and in what happens when one fails.
+
+## What is decided without a provider
+
+The root entry point is pure, because a console shows these numbers while
+somebody drags a slider:
+
+```ts
+import { depositFor, canTakeMoney } from '@birtalanrobert/commerce';
+
+depositFor(15_000, { kind: 'percentage', value: 30 }); // 4_500
+canTakeMoney('pending'); // false — the provider has not verified them yet
+```
+
+## Using it in a NestJS application
+
+```ts
+import { StripeConnect } from '@birtalanrobert/commerce';
+import {
+  COMMERCE_PROVIDER,
+  CommerceService,
+  commerceEntities,
+  commerceMigrations,
+} from '@birtalanrobert/commerce/nestjs';
+
+@Module({
+  providers: [
+    {
+      provide: COMMERCE_PROVIDER,
+      useFactory: (config: AppConfig) =>
+        new StripeConnect({
+          secretKey: config.STRIPE_SECRET_KEY,
+          webhookSecret: config.STRIPE_WEBHOOK_SECRET,
+        }),
+      inject: [ConfigModule.token()],
+    },
+    CommerceService,
+  ],
+})
+export class PaymentsModule {}
+```
+
+Register `commerceEntities` and `commerceMigrations` with the data source, as
+with every other package here.
+
+## The parts worth knowing before using it
+
+- **A business cannot be charged for until the provider says it may be paid
+  out.** `take` refuses before the provider is called. A charge that succeeded
+  into an account with no destination would leave the customer debited and the
+  money nowhere anybody can see it.
+- **`authorized` is not `captured`.** A card held against a no-show fee is
+  authorised and charged only if the fee is actually applied — and _that
+  decision is a human one_. This package offers the mechanism and never the
+  trigger, because charging a customer automatically is how a business loses
+  them permanently.
+- **Cash, terminal, voucher and transfer payments are recorded, not
+  processed** — and recording them is not a lesser feature. A salon is mostly
+  cash, a restaurant takes meal vouchers, a box office takes notes. A report
+  counting only what a provider processed tells a business a fraction of its own
+  takings while looking complete.
+- **The record outlives the provider.** Amounts, dates, what it was for and who
+  decided are stored in full rather than as identifiers to fetch, because a
+  business must be able to produce its own takings after the account is closed.
+- **There is 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 what would stop this being shared.

package/dist/deposits.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare function depositFor(total: number, policy: DepositPolicy): number;
+/** What is still owed after a deposit. Never negative, whatever was paid. */
+export declare const balanceAfter: (total: number, paid: number) => number;
+/**
+ * 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 declare const canTakeMoney: (status: PayoutStatus) => boolean;
+/**
+ * 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 declare const payoutBlockReason: (status: PayoutStatus) => "not-started" | "in-progress" | "needs-attention" | null;
+//# sourceMappingURL=deposits.d.ts.map

package/dist/deposits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deposits.d.ts","sourceRoot":"","sources":["../src/deposits.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qDAAqD;AACrD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;AAEnE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAuBvE;AAED,6EAA6E;AAC7E,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,MAAmC,CAAC;AAI/F;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,OAAO,CAAC;AAEvE,eAAO,MAAM,YAAY,GAAI,QAAQ,YAAY,KAAG,OAA6B,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,YAAY,KACnB,aAAa,GAAG,aAAa,GAAG,iBAAiB,GAAG,IAWtD,CAAC"}

package/dist/deposits.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.payoutBlockReason = exports.canTakeMoney = exports.balanceAfter = void 0;
+exports.depositFor = depositFor;
+/**
+ * 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.
+ */
+function depositFor(total, policy) {
+    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. */
+const balanceAfter = (total, paid) => Math.max(0, total - paid);
+exports.balanceAfter = balanceAfter;
+const clamp = (value, max) => Math.min(Math.max(0, value), max);
+const canTakeMoney = (status) => status === 'ready';
+exports.canTakeMoney = canTakeMoney;
+/**
+ * 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.
+ */
+const payoutBlockReason = (status) => {
+    switch (status) {
+        case 'none':
+            return 'not-started';
+        case 'pending':
+            return 'in-progress';
+        case 'restricted':
+            return 'needs-attention';
+        case 'ready':
+            return null;
+    }
+};
+exports.payoutBlockReason = payoutBlockReason;
+//# sourceMappingURL=deposits.js.map

package/dist/deposits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deposits.js","sourceRoot":"","sources":["../src/deposits.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAyBH,gCAuBC;AA/BD;;;;;;;GAOG;AACH,SAAgB,UAAU,CAAC,KAAa,EAAE,MAAqB;IAC7D,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAEzB,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,MAAM;YACT,OAAO,CAAC,CAAC;QACX,KAAK,MAAM;YACT,OAAO,KAAK,CAAC;QACf,KAAK,OAAO;YACV,yEAAyE;YACzE,qEAAqE;YACrE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;QAChD,KAAK,YAAY;YACf;;;;;eAKG;YACH,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5E;YACE,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED,6EAA6E;AACtE,MAAM,YAAY,GAAG,CAAC,KAAa,EAAE,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,CAAC;AAAlF,QAAA,YAAY,gBAAsE;AAE/F,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,GAAW,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC;AAajF,MAAM,YAAY,GAAG,CAAC,MAAoB,EAAW,EAAE,CAAC,MAAM,KAAK,OAAO,CAAC;AAArE,QAAA,YAAY,gBAAyD;AAElF;;;;;;GAMG;AACI,MAAM,iBAAiB,GAAG,CAC/B,MAAoB,EACsC,EAAE;IAC5D,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,aAAa,CAAC;QACvB,KAAK,SAAS;YACZ,OAAO,aAAa,CAAC;QACvB,KAAK,YAAY;YACf,OAAO,iBAAiB,CAAC;QAC3B,KAAK,OAAO;YACV,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC,CAAC;AAbW,QAAA,iBAAiB,qBAa5B"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StripeConnect = exports.payoutBlockReason = exports.depositFor = exports.canTakeMoney = exports.balanceAfter = void 0;
+/**
+ * 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`.
+ */
+var deposits_1 = require("./deposits");
+Object.defineProperty(exports, "balanceAfter", { enumerable: true, get: function () { return deposits_1.balanceAfter; } });
+Object.defineProperty(exports, "canTakeMoney", { enumerable: true, get: function () { return deposits_1.canTakeMoney; } });
+Object.defineProperty(exports, "depositFor", { enumerable: true, get: function () { return deposits_1.depositFor; } });
+Object.defineProperty(exports, "payoutBlockReason", { enumerable: true, get: function () { return deposits_1.payoutBlockReason; } });
+var stripe_1 = require("./providers/stripe");
+Object.defineProperty(exports, "StripeConnect", { enumerable: true, get: function () { return stripe_1.StripeConnect; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,uCAQoB;AAPlB,wGAAA,YAAY,OAAA;AACZ,wGAAA,YAAY,OAAA;AACZ,sGAAA,UAAU,OAAA;AACV,6GAAA,iBAAiB,OAAA;AAgBnB,6CAA8E;AAArE,uGAAA,aAAa,OAAA"}

package/dist/migrations/1789800000000-CreateCommerce.d.ts

@@ -0,0 +1,38 @@
+import type { MigrationInterface, QueryRunner } from 'typeorm';
+/**
+ * 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 declare class CreateCommerce1789800000000 implements MigrationInterface {
+    name: string;
+    up(queryRunner: QueryRunner): Promise<void>;
+    down(queryRunner: QueryRunner): Promise<void>;
+}
+//# sourceMappingURL=1789800000000-CreateCommerce.d.ts.map

package/dist/migrations/1789800000000-CreateCommerce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"1789800000000-CreateCommerce.d.ts","sourceRoot":"","sources":["../../src/migrations/1789800000000-CreateCommerce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,2BAA4B,YAAW,kBAAkB;IACpE,IAAI,SAAiC;IAExB,EAAE,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAiH3C,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAK3D"}

package/dist/migrations/1789800000000-CreateCommerce.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateCommerce1789800000000 = void 0;
+const tenancy_1 = require("@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.
+ */
+class CreateCommerce1789800000000 {
+    name = 'CreateCommerce1789800000000';
+    async up(queryRunner) {
+        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 (0, tenancy_1.enableRlsSql)(table))
+                await queryRunner.query(statement);
+        }
+    }
+    async down(queryRunner) {
+        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`);
+    }
+}
+exports.CreateCommerce1789800000000 = CreateCommerce1789800000000;
+//# sourceMappingURL=1789800000000-CreateCommerce.js.map

package/dist/migrations/1789800000000-CreateCommerce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"1789800000000-CreateCommerce.js","sourceRoot":"","sources":["../../src/migrations/1789800000000-CreateCommerce.ts"],"names":[],"mappings":";;;AACA,qDAAuD;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAa,2BAA2B;IACtC,IAAI,GAAG,6BAA6B,CAAC;IAE9B,KAAK,CAAC,EAAE,CAAC,WAAwB;QACtC,MAAM,WAAW,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;KAmBvB,CAAC,CAAC;QAEH,gEAAgE;QAChE,MAAM,WAAW,CAAC,KAAK,CAAC;;;KAGvB,CAAC,CAAC;QAEH,MAAM,WAAW,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAyCvB,CAAC,CAAC;QAEH,MAAM,WAAW,CAAC,KAAK,CAAC;;KAEvB,CAAC,CAAC;QACH,wEAAwE;QACxE,MAAM,WAAW,CAAC,KAAK,CAAC;;KAEvB,CAAC,CAAC;QACH,0DAA0D;QAC1D,MAAM,WAAW,CAAC,KAAK,CAAC;;KAEvB,CAAC,CAAC;QAEH,MAAM,WAAW,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;KAkBvB,CAAC,CAAC;QAEH,MAAM,WAAW,CAAC,KAAK,CAAC;;;KAGvB,CAAC,CAAC;QAEH,KAAK,MAAM,KAAK,IAAI,CAAC,wBAAwB,EAAE,iBAAiB,EAAE,wBAAwB,CAAC,EAAE,CAAC;YAC5F,KAAK,MAAM,SAAS,IAAI,IAAA,sBAAY,EAAC,KAAK,CAAC;gBAAE,MAAM,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,WAAwB;QACxC,MAAM,WAAW,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAC;QACjF,MAAM,WAAW,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;QAC1E,MAAM,WAAW,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAC;IACnF,CAAC;CACF;AAzHD,kEAyHC"}

package/dist/nestjs/commerce.service.d.ts

@@ -0,0 +1,122 @@
+import type { DataSource } from 'typeorm';
+import { type PayoutStatus } from '../deposits';
+import type { PaymentProvider, ProviderEvent } from '../providers/port';
+import { PayoutAccount } from './payout-account.entity';
+import { Payment, PaymentRefund, type PaymentMethod } from './payment.entity';
+/** The provider this deployment uses, injected so tests can supply their own. */
+export declare const COMMERCE_PROVIDER: unique symbol;
+export interface TakePayment {
+    readonly subject: string;
+    readonly amount: number;
+    readonly currency: string;
+    readonly applicationFee?: number;
+    readonly description?: string;
+    /** False holds the money instead of taking it. See `capture`. */
+    readonly capture?: boolean;
+    /**
+     * Makes the charge idempotent across retries of the same act.
+     *
+     * A person pressing a button twice on a slow connection is the ordinary case,
+     * not an exotic one, and the second press must not produce a second charge.
+     */
+    readonly reference: string;
+}
+export interface RecordPayment {
+    readonly subject: string;
+    readonly amount: number;
+    readonly currency: string;
+    readonly method: Exclude<PaymentMethod, 'card'>;
+    readonly detail?: string;
+}
+/**
+ * Money between a customer and a business, and the record of it.
+ *
+ * **We never hold their funds** — the customer pays the business directly and
+ * our fee is taken on top — so almost everything here is about the *record*
+ * rather than the movement. That record has to be complete enough to produce a
+ * business's own takings years later, after the provider account is closed.
+ *
+ * Every method runs inside the tenant's policy, reads included: these tables are
+ * under row-level security, and an unbound read returns *nothing* rather than
+ * failing — which here means a revenue report of zero for a business that took
+ * money all month.
+ */
+export declare class CommerceService {
+    private readonly dataSource;
+    private readonly provider;
+    constructor(dataSource: DataSource, provider: PaymentProvider);
+    /** Where a business's money goes, and whether the provider will send it yet. */
+    payoutAccount(tenantId: string): Promise<PayoutAccount | null>;
+    payoutStatus(tenantId: string): Promise<PayoutStatus>;
+    /**
+     * Starts or resumes onboarding, creating the provider's account if needed.
+     *
+     * Called again as often as somebody presses the button: onboarding is a form
+     * people abandon and come back to, and the link is short-lived, so "resume"
+     * is the common case rather than the exception.
+     */
+    startOnboarding(tenantId: string, options: {
+        country: string;
+        email?: string;
+        returnUrl: string;
+        refreshUrl: string;
+    }): Promise<{
+        url: string;
+        expiresAt: Date;
+    }>;
+    /** Asks the provider where onboarding stands, and records the answer. */
+    refreshPayoutAccount(tenantId: string): Promise<PayoutStatus>;
+    /**
+     * Charges a card, or holds one.
+     *
+     * Refused before the provider is called if the business cannot be paid out:
+     * a charge that succeeds into an account with no destination leaves the
+     * customer debited and the money nowhere anybody can see it, and the first
+     * the business hears is asking where it went.
+     */
+    take(tenantId: string, input: TakePayment): Promise<Payment>;
+    /**
+     * Writes down money that arrived some other way.
+     *
+     * Cash at the counter, a card terminal, a meal voucher, a bank transfer.
+     * **Recording is not a lesser feature**: a salon is mostly cash, a restaurant
+     * takes vouchers, a box office takes notes — and a report that counted only
+     * what a provider processed would tell a business a fraction of its own
+     * takings while looking complete.
+     */
+    record(tenantId: string, input: RecordPayment): Promise<Payment>;
+    /**
+     * Takes money that was only held.
+     *
+     * **The human decision has been made by the time this is called.** Charging a
+     * no-show fee automatically is how a business loses that customer
+     * permanently, so this package offers the mechanism and never the trigger.
+     */
+    capture(tenantId: string, paymentId: string, amount?: number): Promise<Payment>;
+    /** Lets a held card go without taking anything. */
+    release(tenantId: string, paymentId: string): Promise<Payment>;
+    /**
+     * Refunds some or all of a payment, with a reason.
+     *
+     * The reason is required because "we refunded her ninety lei in March" is a
+     * question somebody asks a year later, and a blank answer cannot be defended.
+     */
+    refund(tenantId: string, paymentId: string, amount: number, reason: string): Promise<Payment>;
+    /** Everything taken for one thing: a booking, an order, a tab. */
+    forSubject(tenantId: string, subject: string): Promise<Payment[]>;
+    /** What a payment has had given back, and why. */
+    refundsFor(tenantId: string, paymentId: string): Promise<PaymentRefund[]>;
+    /**
+     * Records what a webhook said, whatever it was about.
+     *
+     * A payment the deployment has no record of is **ignored rather than
+     * inserted**: it belongs to another environment sharing the provider account,
+     * and inventing a row for it would put another system's money in this one's
+     * books.
+     */
+    settle(event: ProviderEvent): Promise<Payment | PayoutAccount | undefined>;
+    private find;
+    private update;
+    private saveAccount;
+}
+//# sourceMappingURL=commerce.service.d.ts.map

package/dist/nestjs/commerce.service.d.ts.map

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