@birtalanrobert/commerce 1.0.0 → 3.0.0

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@birtalanrobert/commerce",
-  "version": "1.0.0",
+  "version": "3.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/birtalanrobert/mortar.git",
+    "directory": "packages/commerce"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "commonjs",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,6 +20,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./stripe": {
+      "types": "./dist/providers/stripe.d.ts",
+      "default": "./dist/providers/stripe.js"
+    },
     "./nestjs": {
       "types": "./dist/nestjs/index.d.ts",
       "default": "./dist/nestjs/index.js"
@@ -26,16 +38,17 @@
     "README.md",
     "LICENSE",
     "NOTICE",
+    "stripe",
     "nestjs",
     "CHANGELOG.md"
   ],
   "dependencies": {
     "stripe": "^22.6.0",
     "@birtalanrobert/context": "^1.1.0",
+    "@birtalanrobert/http": "^2.0.0",
     "@birtalanrobert/money": "^1.0.0",
     "@birtalanrobert/database": "^1.0.0",
-    "@birtalanrobert/tenancy": "^1.1.0",
-    "@birtalanrobert/http": "^2.0.0"
+    "@birtalanrobert/tenancy": "^1.1.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",

package/src/index.ts

@@ -12,10 +12,12 @@
  * 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`.
+ * **This entry point is pure**, and stays that way by leaving things out. 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. Storage and the container are behind `/nestjs`; the Stripe client is
+ * behind `/stripe`, because a barrel that re-exports it puts the vendor's whole
+ * SDK into every bundle that wanted to divide a price by three.
  */
 export {
   balanceAfter,
@@ -27,6 +29,14 @@ export {
   type PayoutStatus,
 } from './deposits';
 
+export {
+  isRefundable,
+  refundableAmount,
+  type PaymentKind,
+  type PaymentMethod,
+  type PaymentState,
+} from './payments';
+
 export type {
   ChargeRequest,
   ChargeResult,
@@ -35,6 +45,18 @@ export type {
   ProviderAccount,
   ProviderEvent,
   RefundRequest,
+  SaveCardRequest,
+  SaveCardResult,
+  StoredCard,
 } from './providers/port';
 
-export { StripeConnect, type StripeConnectOptions } from './providers/stripe';
+/*
+ * `StripeConnect` is deliberately NOT re-exported here.
+ *
+ * It lives at `@birtalanrobert/commerce/stripe`, because importing it pulls in
+ * the vendor's whole SDK — and this entry point is imported by browser code
+ * that only wants to know what a deposit comes to. Re-exporting it put 30 KB of
+ * a payments SDK into a console's first load for a screen that never calls it:
+ * a barrel is a bundling decision, and the only way to keep this one pure is to
+ * leave the heavy thing out of it.
+ */

package/src/migrations/1790000000000-AddSavedCardsAndKind.ts

@@ -0,0 +1,92 @@
+import type { MigrationInterface, QueryRunner } from 'typeorm';
+import { enableRlsSql } from '@birtalanrobert/tenancy';
+
+/**
+ * A card kept for later, and what each payment was actually for.
+ *
+ * ## `mortar_saved_cards`
+ *
+ * The strongest thing a business can do about people not turning up short of
+ * taking their money: nothing leaves the customer's account, and the card is
+ * there if a fee is later decided on. A **hold is not a substitute** — providers
+ * expire an authorisation within days and an appointment is usually further
+ * away than that — which is why this is a table and not a longer-lived hold.
+ *
+ * The consent is stored as **text with a time**, not as a boolean. A flag says
+ * somebody clicked; the sentence says what they were told they were agreeing
+ * to, and only the second is worth anything when they say they were not told.
+ *
+ * ## `kind` on a payment
+ *
+ * A tip belongs to the person who earned it and a product to neither the
+ * service nor the diary. Counting all three as service income tells a business
+ * its haircuts are more profitable than they are, and nothing computed
+ * afterwards can separate them again — so the distinction goes in the row, with
+ * `sale` as the default so every existing payment keeps meaning what it meant.
+ */
+export class AddSavedCardsAndKind1790000000000 implements MigrationInterface {
+  name = 'AddSavedCardsAndKind1790000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE "mortar_payments"
+        ADD COLUMN "kind" varchar(16) NOT NULL DEFAULT 'sale'
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE "mortar_payments"
+        ADD CONSTRAINT "ck_payments_kind"
+          CHECK ("kind" IN ('sale', 'deposit', 'fee', 'tip', 'product'))
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE "mortar_saved_cards" (
+        "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,
+        -- Whose card it is, as the owning product names it. No foreign key, for
+        -- the same reason a payment has none: one product hangs a card off a
+        -- salon's client, another off a tenant's guest.
+        "subject" varchar(160) NOT NULL,
+        "provider" varchar(32) NOT NULL DEFAULT 'stripe',
+        -- The customer on *our* account. Under a destination charge the money
+        -- lands on the business's account while the card stays ours to charge,
+        -- and one created on the business's account cannot be used from here.
+        "customer_ref" varchar(128) NOT NULL,
+        "payment_method_ref" varchar(128) NOT NULL,
+        -- Enough to recognise it, and nothing more. We never see the number.
+        "brand" varchar(24),
+        "last4" varchar(4),
+        "expiry_month" int,
+        "expiry_year" int,
+        -- What they were told they were agreeing to, in the language they read
+        -- it in. Required: a card charged on a consent nobody can produce is an
+        -- argument the business loses.
+        "consent_text" varchar(1000) NOT NULL,
+        "consented_at" timestamptz NOT NULL,
+        "stored_by" uuid,
+        CONSTRAINT "pk_saved_cards" PRIMARY KEY ("id"),
+        CONSTRAINT "uq_saved_cards_tenant_id" UNIQUE ("tenant_id", "id"),
+        CONSTRAINT "uq_saved_cards_method" UNIQUE ("tenant_id", "payment_method_ref")
+      )
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX "ix_saved_cards_subject"
+        ON "mortar_saved_cards" ("tenant_id", "subject")
+    `);
+
+    for (const statement of enableRlsSql('mortar_saved_cards')) {
+      await queryRunner.query(statement);
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS "mortar_saved_cards" CASCADE`);
+    await queryRunner.query(`
+      ALTER TABLE "mortar_payments" DROP CONSTRAINT IF EXISTS "ck_payments_kind"
+    `);
+    await queryRunner.query(`ALTER TABLE "mortar_payments" DROP COLUMN IF EXISTS "kind"`);
+  }
+}

package/src/nestjs/commerce.service.ts

@@ -7,7 +7,9 @@ import { ConflictError, NotFoundError, ValidationError } from '@birtalanrobert/h
 import { canTakeMoney, type PayoutStatus } from '../deposits';
 import type { PaymentProvider, ProviderEvent } from '../providers/port';
 import { PayoutAccount } from './payout-account.entity';
+import { isRefundable, type PaymentKind } from '../payments';
 import { Payment, PaymentRefund, type PaymentMethod } from './payment.entity';
+import { SavedCard } from './saved-card.entity';
 
 /** The provider this deployment uses, injected so tests can supply their own. */
 export const COMMERCE_PROVIDER = Symbol('COMMERCE_PROVIDER');
@@ -18,6 +20,15 @@ export interface TakePayment {
   readonly currency: string;
   readonly applicationFee?: number;
   readonly description?: string;
+  /** What it is for. `sale` unless said otherwise. */
+  readonly kind?: PaymentKind;
+  /**
+   * A stored card to charge without anybody present.
+   *
+   * The whole reason for keeping one: a fee is decided days after the fact, and
+   * the customer is not there to be asked.
+   */
+  readonly savedCardId?: string;
   /** False holds the money instead of taking it. See `capture`. */
   readonly capture?: boolean;
   /**
@@ -34,9 +45,32 @@ export interface RecordPayment {
   readonly amount: number;
   readonly currency: string;
   readonly method: Exclude<PaymentMethod, 'card'>;
+  readonly kind?: PaymentKind;
   readonly detail?: string;
 }
 
+/**
+ * A charge, and what the browser needs to finish it.
+ *
+ * The secret is returned rather than stored: a charge created on the server has
+ * no card attached to it yet, and the card is entered against the provider's own
+ * script so the number never reaches us. Without handing it back, a payment can
+ * be created and never paid — which a customer reads as "it took my booking and
+ * lost my money".
+ */
+export interface TakenPayment {
+  readonly payment: Payment;
+  readonly clientSecret?: string;
+}
+
+/** A card being stored, and what the browser confirms it with. */
+export interface CardToSave {
+  readonly subject: string;
+  readonly reference: string;
+  /** What the customer was told they were agreeing to, in their own language. */
+  readonly consentText: string;
+}
+
 /**
  * Money between a customer and a business, and the record of it.
  *
@@ -120,13 +154,19 @@ export class CommerceService {
    * customer debited and the money nowhere anybody can see it, and the first
    * the business hears is asking where it went.
    */
-  async take(tenantId: string, input: TakePayment): Promise<Payment> {
+  async take(tenantId: string, input: TakePayment): Promise<TakenPayment> {
     const account = await this.payoutAccount(tenantId);
 
     if (!account || !canTakeMoney(account.status)) {
       throw new ConflictError('This business cannot take card payments yet.');
     }
 
+    const saved = input.savedCardId ? await this.savedCard(tenantId, input.savedCardId) : null;
+
+    if (input.savedCardId && !saved) {
+      throw new NotFoundError('SavedCard', input.savedCardId);
+    }
+
     if (input.amount <= 0) {
       throw new ValidationError(
         [{ field: 'amount', message: 'There is nothing to charge.' }],
@@ -142,10 +182,11 @@ export class CommerceService {
       subject: input.subject,
       capture: input.capture ?? true,
       ...(input.description ? { description: input.description } : {}),
+      ...(saved ? { customer: saved.customerRef, paymentMethod: saved.paymentMethodRef } : {}),
       reference: input.reference,
     });
 
-    return runInTenantTransaction(
+    const payment = await runInTenantTransaction(
       this.dataSource,
       async (scoped) => {
         const repository = scoped.getRepository(Payment);
@@ -155,6 +196,7 @@ export class CommerceService {
             tenantId,
             subject: input.subject,
             method: 'card',
+            kind: input.kind ?? 'sale',
             state: result.state,
             amount: String(input.amount),
             currency: input.currency,
@@ -173,6 +215,130 @@ export class CommerceService {
       },
       { tenantId },
     );
+
+    /*
+     * The secret is handed back and never written down.
+     *
+     * It authorises whoever holds it to pay this one charge, so it belongs in
+     * the response to the person paying and nowhere else — not in a column, not
+     * in a log line, and not in an error.
+     */
+    return { payment, ...(result.clientSecret ? { clientSecret: result.clientSecret } : {}) };
+  }
+
+  /**
+   * Starts storing a card without charging it, and records what was agreed.
+   *
+   * Two steps, because there is a browser in the middle: this creates the
+   * intent and hands back a secret, and `confirmCard` writes the row once the
+   * provider says a card really is stored. Believing the browser instead would
+   * mean a business holding a card reference that charges nothing.
+   */
+  async saveCard(
+    tenantId: string,
+    input: CardToSave,
+  ): Promise<{ externalId: string; clientSecret: string }> {
+    const existing = await this.savedCards(tenantId, input.subject);
+
+    const result = await this.provider.saveCard({
+      subject: input.subject,
+      reference: input.reference,
+      // Reuse the customer this person already has, so a second card joins the
+      // first rather than creating a stranger with the same name.
+      ...(existing[0] ? { customer: existing[0].customerRef } : {}),
+    });
+
+    return { externalId: result.externalId, clientSecret: result.clientSecret };
+  }
+
+  /**
+   * Writes down the card the provider says is now stored.
+   *
+   * Read back from the provider rather than taken from the browser: what a page
+   * reports is what a page was told to report, and this row is what a business
+   * will later charge real money against.
+   */
+  async confirmCard(
+    tenantId: string,
+    externalId: string,
+    input: CardToSave,
+  ): Promise<SavedCard | null> {
+    const stored = await this.provider.storedCard(externalId);
+    if (!stored) return null;
+
+    return runInTenantTransaction(
+      this.dataSource,
+      async (scoped) => {
+        const repository = scoped.getRepository(SavedCard);
+
+        const already = await repository.findOne({
+          where: { tenantId, paymentMethodRef: stored.paymentMethod },
+        });
+
+        // Confirming twice is the ordinary case on a slow connection, not an
+        // exotic one, and it must not leave two rows for one card.
+        if (already) return already;
+
+        return repository.save(
+          repository.create({
+            tenantId,
+            subject: input.subject,
+            provider: this.provider.name,
+            customerRef: stored.customer,
+            paymentMethodRef: stored.paymentMethod,
+            brand: stored.brand ?? null,
+            last4: stored.last4 ?? null,
+            expiryMonth: stored.expiryMonth ?? null,
+            expiryYear: stored.expiryYear ?? null,
+            consentText: input.consentText,
+            consentedAt: new Date(),
+            storedBy: getActor()?.id ?? null,
+          }),
+        );
+      },
+      { tenantId },
+    );
+  }
+
+  /** Every card kept for somebody, newest first. */
+  async savedCards(tenantId: string, subject: string): Promise<SavedCard[]> {
+    return runInTenantTransaction(
+      this.dataSource,
+      (scoped) =>
+        scoped
+          .getRepository(SavedCard)
+          .find({ where: { tenantId, subject }, order: { createdAt: 'DESC' } }),
+      { tenantId },
+    );
+  }
+
+  async savedCard(tenantId: string, id: string): Promise<SavedCard | null> {
+    return runInTenantTransaction(
+      this.dataSource,
+      (scoped) => scoped.getRepository(SavedCard).findOne({ where: { tenantId, id } }),
+      { tenantId },
+    );
+  }
+
+  /**
+   * Forgets a card, at the customer's request or the business's.
+   *
+   * The provider is told first. A row deleted while the provider still holds
+   * the card is a card nobody can see and anybody with the reference can
+   * charge; the reverse — a detached card with a row still here — is merely a
+   * charge that fails.
+   */
+  async forgetCard(tenantId: string, id: string): Promise<void> {
+    const card = await this.savedCard(tenantId, id);
+    if (!card) return;
+
+    await this.provider.forgetCard(card.paymentMethodRef);
+
+    await runInTenantTransaction(
+      this.dataSource,
+      (scoped) => scoped.getRepository(SavedCard).delete({ tenantId, id }),
+      { tenantId },
+    );
   }
 
   /**
@@ -202,6 +368,7 @@ export class CommerceService {
             tenantId,
             subject: input.subject,
             method: input.method,
+            kind: input.kind ?? 'sale',
             // Captured immediately: the money is in the till. There is no
             // provider to wait for and nothing that can fail later.
             state: 'captured',
@@ -275,7 +442,7 @@ export class CommerceService {
   ): Promise<Payment> {
     const payment = await this.find(tenantId, paymentId);
 
-    if (payment.state !== 'captured' && payment.state !== 'partially_refunded') {
+    if (!isRefundable(payment.state)) {
       throw new ConflictError('That payment cannot be refunded.');
     }
 

package/src/nestjs/index.ts

@@ -6,19 +6,31 @@
  * browser bundle.
  */
 export { PayoutAccount } from './payout-account.entity';
-export { Payment, PaymentRefund, type PaymentMethod, type PaymentState } from './payment.entity';
+export {
+  Payment,
+  PaymentRefund,
+  type PaymentKind,
+  type PaymentMethod,
+  type PaymentState,
+} from './payment.entity';
+export { SavedCard } from './saved-card.entity';
 export {
   COMMERCE_PROVIDER,
   CommerceService,
+  type CardToSave,
   type RecordPayment,
+  type TakenPayment,
   type TakePayment,
 } from './commerce.service';
 export { CreateCommerce1789800000000 } from '../migrations/1789800000000-CreateCommerce';
+export { AddSavedCardsAndKind1790000000000 } from '../migrations/1790000000000-AddSavedCardsAndKind';
 
 import { PayoutAccount } from './payout-account.entity';
 import { Payment, PaymentRefund } from './payment.entity';
+import { SavedCard } from './saved-card.entity';
 import { CreateCommerce1789800000000 } from '../migrations/1789800000000-CreateCommerce';
+import { AddSavedCardsAndKind1790000000000 } from '../migrations/1790000000000-AddSavedCardsAndKind';
 
 /** Register with the data source, the way every other mortar package is. */
-export const commerceEntities = [PayoutAccount, Payment, PaymentRefund];
-export const commerceMigrations = [CreateCommerce1789800000000];
+export const commerceEntities = [PayoutAccount, Payment, PaymentRefund, SavedCard];
+export const commerceMigrations = [CreateCommerce1789800000000, AddSavedCardsAndKind1790000000000];

package/src/nestjs/payment.entity.ts

@@ -1,33 +1,14 @@
 import { Column, Entity, Index, Unique } from 'typeorm';
 import { BaseEntity, MONEY_AMOUNT_COLUMN } from '@birtalanrobert/database';
+import type { PaymentKind, PaymentMethod, PaymentState } from '../payments';
 
-/**
- * How the money arrived.
- *
- * `card` is the only one this package processes. The rest are **recorded, not
- * taken** — and recording them is not a lesser feature: a salon is mostly cash
- * at the counter, a restaurant's till takes meal vouchers, and a box office
- * takes notes. A report that only counts what a provider processed tells a
- * business a fraction of its own takings, which is worse than telling it
- * nothing because it looks complete.
- */
-export type PaymentMethod = 'card' | 'cash' | 'terminal' | 'voucher' | 'transfer';
-
-/**
- * Where a payment is.
+/*
+ * The lifecycle types live in the pure entry point and are re-exported here.
  *
- * `authorized` is separate from `captured` on purpose: a card held against a
- * no-show fee is authorised and never captured unless the fee is applied, and
- * that decision is a human one.
+ * A console renders a refund button from the same union the entity is typed
+ * with, and it must not reach TypeORM to get it.
  */
-export type PaymentState =
-  | 'pending'
-  | 'authorized'
-  | 'captured'
-  | 'failed'
-  | 'refunded'
-  | 'partially_refunded'
-  | 'cancelled';
+export type { PaymentKind, PaymentMethod, PaymentState } from '../payments';
 
 /**
  * One movement of money between a customer and a business.
@@ -58,6 +39,17 @@ export class Payment extends BaseEntity {
   @Column('varchar', { length: 16 })
   method!: PaymentMethod;
 
+  /**
+   * What it was for.
+   *
+   * A tip belongs to the person who earned it and a product to neither the
+   * service nor the diary — a report counting all three as service income tells
+   * a business its haircuts are more profitable than they are, and no amount of
+   * arithmetic afterwards can separate them again.
+   */
+  @Column('varchar', { length: 16, default: 'sale' })
+  kind!: PaymentKind;
+
   @Column('varchar', { length: 24, default: 'pending' })
   state!: PaymentState;
 

package/src/nestjs/saved-card.entity.ts

@@ -0,0 +1,69 @@
+import { Column, Entity, Index, Unique } from 'typeorm';
+import { BaseEntity } from '@birtalanrobert/database';
+
+/**
+ * A card kept for later, with the words the customer agreed to.
+ *
+ * **The strongest thing a business can do about people not turning up, short of
+ * taking their money.** Nothing leaves the customer's account when they book;
+ * the card is simply there if a fee is later decided on — and the decision is
+ * still a human one made days afterwards, which is exactly when asking somebody
+ * to enter a card is a conversation that does not happen.
+ *
+ * A hold is not a substitute and must not be sold as one: providers expire an
+ * authorisation within days, and an appointment is usually further away.
+ *
+ * **The consent is stored as text, not as a flag.** A boolean records that
+ * somebody clicked; the sentence records what they were told they were agreeing
+ * to, which is the only thing worth anything when they say they were not.
+ */
+@Entity('mortar_saved_cards')
+@Unique('uq_saved_cards_tenant_id', ['tenantId', 'id'])
+@Index('ix_saved_cards_subject', ['tenantId', 'subject'])
+export class SavedCard extends BaseEntity {
+  @Column('uuid')
+  tenantId!: string;
+
+  /**
+   * Whose card it is, as the owning product names it: `customer:<id>`.
+   *
+   * No foreign key, for the same reason a payment has none — one product hangs
+   * a card off a salon's client, another off a tenant's guest.
+   */
+  @Column('varchar', { length: 160 })
+  subject!: string;
+
+  @Column('varchar', { length: 32 })
+  provider!: string;
+
+  /** The customer on *our* account, which is where a saved card can be used. */
+  @Column('varchar', { length: 128 })
+  customerRef!: string;
+
+  @Column('varchar', { length: 128 })
+  paymentMethodRef!: string;
+
+  /** Enough to recognise it — "Visa ending 4242" — and nothing more. */
+  @Column('varchar', { length: 24, nullable: true })
+  brand!: string | null;
+
+  @Column('varchar', { length: 4, nullable: true })
+  last4!: string | null;
+
+  @Column('int', { name: 'expiry_month', nullable: true })
+  expiryMonth!: number | null;
+
+  @Column('int', { name: 'expiry_year', nullable: true })
+  expiryYear!: number | null;
+
+  /** What they were told they were agreeing to, in the language they read it. */
+  @Column('varchar', { length: 1000 })
+  consentText!: string;
+
+  @Column('timestamptz')
+  consentedAt!: Date;
+
+  /** Who stored it, where a member of staff did it on somebody's behalf. */
+  @Column('uuid', { nullable: true })
+  storedBy!: string | null;
+}

package/src/payments.ts

@@ -0,0 +1,67 @@
+/**
+ * Where a payment is, and what may still be done to it.
+ *
+ * Pure and dependency-free, because a console renders a refund button from
+ * exactly the rule the server enforces — and a screen that offers a refund the
+ * server will refuse is a screen that teaches its user not to trust it.
+ */
+
+/**
+ * How the money arrived.
+ *
+ * `card` is the only one this package processes. The rest are **recorded, not
+ * taken** — and recording them is not a lesser feature: a salon is mostly cash
+ * at the counter, a restaurant's till takes meal vouchers, and a box office
+ * takes notes. A report that only counts what a provider processed tells a
+ * business a fraction of its own takings, which is worse than telling it
+ * nothing because it looks complete.
+ */
+export type PaymentMethod = 'card' | 'cash' | 'terminal' | 'voucher' | 'transfer';
+
+/**
+ * Where a payment is.
+ *
+ * `authorized` is separate from `captured` on purpose: a card held against a
+ * no-show fee is authorised and never captured unless the fee is applied, and
+ * that decision is a human one.
+ */
+export type PaymentState =
+  | 'pending'
+  | 'authorized'
+  | 'captured'
+  | 'failed'
+  | 'refunded'
+  | 'partially_refunded'
+  | 'cancelled';
+
+/**
+ * What a payment was for.
+ *
+ * Not decoration: a tip belongs to the person who earned it and a product to
+ * neither the service nor the diary, so a revenue report that counts all three
+ * as service income tells a business its haircuts are more profitable than they
+ * are. The distinction has to survive into the row, because it cannot be
+ * recovered from an amount afterwards.
+ */
+export type PaymentKind = 'sale' | 'deposit' | 'fee' | 'tip' | 'product';
+
+/**
+ * Whether money actually moved, and so can be given back.
+ *
+ * A held card has taken nothing yet — releasing it is a different operation
+ * with a different name — and a failed charge never will. Both look refundable
+ * to anyone reasoning from "there is a payment row here", which is why this is
+ * one function and not a condition written twice.
+ */
+export const isRefundable = (state: PaymentState): boolean =>
+  state === 'captured' || state === 'partially_refunded';
+
+/**
+ * What is left to give back, in minor units.
+ *
+ * Takes the two amounts rather than a row, because they arrive as strings from
+ * a `bigint` column in one caller and as numbers in another, and the subtraction
+ * should not be where that difference is discovered.
+ */
+export const refundableAmount = (amount: number, refunded: number): number =>
+  Math.max(0, amount - refunded);