feat: add payment module

modules/payment/schemas/account.ts

@@ -0,0 +1,35 @@
+import z from "zod";
+
+import { CurrencySchema } from "./currency.ts";
+
+/*
+ |--------------------------------------------------------------------------------
+ | Account
+ |--------------------------------------------------------------------------------
+ |
+ | An account is a entity which can be the sender or recipient in a transaction.
+ |
+ */
+
+export const AccountSchema = z.strictObject({
+  _id: z.uuid().describe("Primary identifier of the account"),
+  walletId: z.string().describe("Identifier of the wallet this account belongs to"),
+  label: z.string().describe("Human-readable name for the account"),
+  currency: CurrencySchema.describe("Currency this account trades in"),
+});
+
+export type Account = z.output<typeof AccountSchema>;
+
+/*
+ |--------------------------------------------------------------------------------
+ | Database
+ |--------------------------------------------------------------------------------
+ */
+
+export const AccountInsertSchema = z.strictObject({
+  walletId: AccountSchema.shape.walletId,
+  label: z.string().nullable().default(null).describe("Human-readable identifier for the account"),
+  currency: AccountSchema.shape.currency,
+});
+
+export type AccountInsert = z.input<typeof AccountInsertSchema>;

modules/payment/schemas/beneficiary.ts

@@ -0,0 +1,40 @@
+import z from "zod";
+
+/*
+ |--------------------------------------------------------------------------------
+ | Beneficiary
+ |--------------------------------------------------------------------------------
+ |
+ | A beneficiary is an entity (person, organization, or system) that owns one or
+ | more ledgers. All financial activity is scoped under the beneficiary.
+ |
+ */
+
+export const BeneficiarySchema = z.strictObject({
+  _id: z.uuid().describe("Primary identifier of the beneficiary"),
+  tenantId: z.string().describe("Identifier of the tenant this beneficiary belongs to"),
+  label: z.string().optional().describe("Human-readable name for the beneficiary"),
+  createdAt: z.coerce.date().describe("Timestamp when the beneficiary was created"),
+});
+
+export type Beneficiary = z.output<typeof BeneficiarySchema>;
+
+/*
+ |--------------------------------------------------------------------------------
+ | Database
+ |--------------------------------------------------------------------------------
+ */
+
+export const BeneficiaryInsertSchema = z.strictObject({
+  tenantId: BeneficiarySchema.shape.tenantId,
+  label: z.string().nullable().default(null).describe("Human-readable name for the beneficiary"),
+});
+
+export type BeneficiaryInsert = z.input<typeof BeneficiaryInsertSchema>;
+
+export const BeneficiaryUpdateSchema = z.strictObject({
+  _id: z.uuid().describe("Primary identifier of the beneficiary"),
+  label: z.string().nullable().default(null).describe("Human-readable name for the beneficiary"),
+});
+
+export type BeneficiaryUpdate = z.input<typeof BeneficiaryUpdateSchema>;

modules/payment/schemas/currency.ts

@@ -0,0 +1,24 @@
+import z from "zod";
+
+/*
+ |--------------------------------------------------------------------------------
+ | Currency
+ |--------------------------------------------------------------------------------
+ |
+ | A union of currencies the system supports trade in.
+ |
+ */
+
+export const CurrencySchema = z.union([
+  z.literal("USD").describe("United States Dollar"),
+  z.literal("EUR").describe("Euro"),
+  z.literal("GBP").describe("British Pound Sterling"),
+  z.literal("CHF").describe("Swiss Franc"),
+  z.literal("JPY").describe("Japanese Yen"),
+  z.literal("CAD").describe("Canadian Dollar"),
+  z.literal("AUD").describe("Australian Dollar"),
+  z.literal("NOK").describe("Norwegian Krone"),
+  z.literal("SEK").describe("Swedish Krona"),
+]);
+
+export type Currency = z.output<typeof CurrencySchema>;

modules/payment/schemas/ledger.ts

@@ -0,0 +1,36 @@
+import z from "zod";
+
+import { CurrencySchema } from "./currency.ts";
+
+/*
+ |--------------------------------------------------------------------------------
+ | Ledger
+ |--------------------------------------------------------------------------------
+ |
+ | A ledger is the primary container in which transactions are held.
+ |
+ */
+
+export const LedgerSchema = z.strictObject({
+  _id: z.uuid().describe("Primary identifier of the ledger"),
+  beneficiaryId: z.uuid().describe("Identifier of the beneficiary this ledger belongs to"),
+  label: z.string().optional().describe("Human-readable identifier for the ledger"),
+  currencies: z.array(CurrencySchema).describe("Currency this ledger trades in"),
+  createdAt: z.coerce.date().describe("Timestamp the ledger was created"),
+});
+
+export type Ledger = z.output<typeof LedgerSchema>;
+
+/*
+ |--------------------------------------------------------------------------------
+ | Database
+ |--------------------------------------------------------------------------------
+ */
+
+export const LedgerInsertSchema = z.strictObject({
+  beneficiaryId: LedgerSchema.shape.beneficiaryId,
+  label: z.string().nullable().default(null).describe("Human-readable identifier for the ledger"),
+  currencies: LedgerSchema.shape.currencies,
+});
+
+export type LedgerInsert = z.input<typeof LedgerInsertSchema>;

modules/payment/schemas/transaction-participant.ts

@@ -0,0 +1,17 @@
+import z from "zod";
+
+/*
+ |--------------------------------------------------------------------------------
+ | Transaction Participant
+ |--------------------------------------------------------------------------------
+ |
+ | A participant is either an internal account or an external entity.
+ |
+ */
+
+export const TransactionParticipantType = z.union([
+  z.literal("account").describe("Participant is an internal account on the ledger"),
+  z.literal("external").describe("Participant is a opaque external entity"),
+]);
+
+export type TransactionParticipant = z.output<typeof TransactionParticipantType>;

modules/payment/schemas/transaction.ts

@@ -0,0 +1,40 @@
+import z from "zod";
+
+import { TransactionParticipantType } from "./transaction-participant.ts";
+
+/*
+ |--------------------------------------------------------------------------------
+ | Transaction
+ |--------------------------------------------------------------------------------
+ |
+ | A transaction is a description of value being moved from a source to a target.
+ | Transaction must have at least one "account" participant or it is considered
+ | invalid as our system does not support "external" -> "external" transactions.
+ |
+ | Which ledger the transaction resides in is determined by the participants
+ | account traced upwards tx -> account -> wallet -> ledger. A transaction is
+ | invalid if both source and target participant account leads to different
+ | ledgers.
+ |
+ */
+
+export const TransactionSchema = z.strictObject({
+  _id: z.uuid().describe("Primary identifier of the transaction"),
+
+  sourceType: TransactionParticipantType,
+  sourceId: z.string().describe("Identifier of the source sending value"),
+
+  targetType: TransactionParticipantType,
+  targetId: z.string().describe("Identifier of the target receiving value"),
+
+  amount: z.string().describe("Value amount being transferred"),
+  conversionRate: z
+    .number()
+    .optional()
+    .describe("Conversation rate from source to target if they operate in different currencies"),
+
+  occurredAt: z.coerce.date().describe("Timestamp of when the transaction occured"),
+  approvedBy: z.string().describe("Identifier of the individual who approved the transfer"),
+});
+
+export type Transaction = z.output<typeof TransactionSchema>;

modules/payment/schemas/wallet.ts

@@ -0,0 +1,35 @@
+import z from "zod";
+
+/*
+ |--------------------------------------------------------------------------------
+ | Wallet
+ |--------------------------------------------------------------------------------
+ |
+ | A wallet can hold one or more accounts and is a complete overview of entities
+ | funds in a ledger.
+ |
+ */
+
+export const WalletSchema = z.strictObject({
+  _id: z.uuid().describe("Primary identifier of the wallet"),
+  ledgerId: z.uuid().describe("Identifier of the ledger this wallet belongs to"),
+  entityId: z.string().describe("Identifier of the entity this wallet belongs to"),
+  label: z.string().optional().describe("Human-readable identifier for the wallet"),
+  createdAt: z.coerce.date().describe("Timestamp the wallet was created"),
+});
+
+export type Wallet = z.output<typeof WalletSchema>;
+
+/*
+ |--------------------------------------------------------------------------------
+ | Database
+ |--------------------------------------------------------------------------------
+ */
+
+export const WalletInsertSchema = z.strictObject({
+  ledgerId: WalletSchema.shape.ledgerId,
+  entityId: WalletSchema.shape.entityId,
+  label: z.string().nullable().default(null).describe("Human-readable identifier for the wallet"),
+});
+
+export type WalletInsert = z.input<typeof WalletInsertSchema>;