@luca-financial/luca-schema 3.0.3 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0] - 2026-04-04
+
+### Added
+
+- Add a new `transactionLink` schema to represent links between related transactions across accounts.
+- Add optional `transactionLinks` support to the aggregate Luca Schema, schema exports, enums, and validator metadata.
+- Add bundled transaction-link example data and validation tests covering valid transaction-link usage.
+
+### Changed
+
+- Update README and example documentation to describe transaction links and how they fit into the aggregate schema.
+
+## [3.1.0] - 2026-04-04
+
+### Added
+
+- Support `CASH` and `ESCROW` as valid `AccountType` enum values.
+- Add `CASH` and `ESCROW` account examples to bundled example datasets.
+- Add validation tests covering `CASH` and `ESCROW` account types.
+
+### Changed
+
+- Update README account schema documentation to include the new account types.
+
+## [3.0.3] - 2026-03-18
+
+### Changed
+
+- Upgrade runtime and development dependencies to their latest compatible versions.
+- Refresh the linting and test toolchain, including the ESLint and Jest stacks.
+- Regenerate `pnpm-lock.yaml` to capture the updated dependency graph for the 3.0.3 release.
+
 ## [3.0.2] - 2026-02-14
 
 ### Changed

package/README.md

@@ -52,11 +52,13 @@ const common = {
 
 Validates financial accounts.
 
+Supported account types include `CHECKING`, `SAVINGS`, `CASH`, `CREDIT_CARD`, `ESCROW`, and `EXTERNAL`. Use `CASH` for physical cash balances and `ESCROW` for held-funds accounts such as deposits or tax escrows.
+
 ```typescript
 const account = {
   id: string;
   name: string;
-  type: 'CHECKING' | 'SAVINGS' | 'CREDIT_CARD' | 'EXTERNAL';
+  type: 'CHECKING' | 'SAVINGS' | 'CASH' | 'CREDIT_CARD' | 'ESCROW' | 'EXTERNAL';
   institution: string | null;
   aggregationServiceId: string | null;
   statementClosingDay: number | null;
@@ -208,6 +210,24 @@ const transactionSplit = {
 };
 ```
 
+### TransactionLink
+
+Validates links between related transactions, such as transfers recorded in separate accounts.
+
+```typescript
+const transactionLink = {
+  id: string;
+  sourceTransactionId: string;
+  destinationTransactionId: string;
+  createdAt: string;
+  updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
+};
+```
+
+Cross-transaction rules like matching dates, matching amounts, or opposite signs are not enforced by this schema and should be handled in application logic.
+
 ### LucaSchema
 
 Validates the full ledger export.
@@ -221,6 +241,7 @@ const lucaSchema = {
   recurringTransactions: RecurringTransaction[];
   recurringTransactionEvents: RecurringTransactionEvent[];
   transactions: Transaction[];
+  transactionLinks?: TransactionLink[];
   transactionSplits: TransactionSplit[];
 };
 ```
@@ -249,7 +270,7 @@ import {
 - `validate(schemaKey, data)` → `{ valid: boolean, errors: AjvError[] }`
 - `validateCollection(schemaKey, array)` → `{ valid: boolean, errors: [{ index, entity, errors }] }`
 - `getDateFieldPaths(schemaKey)` → `string[]` of `format: date` fields for a schema key
-- `getDateFieldPathsByCollection()` → `{ accounts, categories, statements, recurringTransactions, recurringTransactionEvents, transactions, transactionSplits }`
+- `getDateFieldPathsByCollection()` → `{ accounts, categories, statements, recurringTransactions, recurringTransactionEvents, transactions, transactionLinks, transactionSplits }`
 - `getValidFields(schemaKey)` → `Set<string>` of all fields (includes common fields when applicable)
 - `getRequiredFields(schemaKey)` → `Set<string>` of required fields (includes common required fields)
 - `stripInvalidFields(schemaKey, data)` → new object with only schema-defined keys

package/dist/esm/index.d.ts

@@ -6,7 +6,7 @@ export type Account = Common & {
   /**
    * Allowed account types
    */
-  type: 'CHECKING' | 'SAVINGS' | 'CREDIT_CARD' | 'EXTERNAL';
+  type: 'CHECKING' | 'SAVINGS' | 'CASH' | 'CREDIT_CARD' | 'ESCROW' | 'EXTERNAL';
   institution?: Institution;
   aggregationServiceId?: AggregationServiceID;
   statementClosingDay?: StatementClosingDay;
@@ -174,7 +174,7 @@ export interface Common {
  * This interface was referenced by `LucaSchemaEnums`'s JSON-Schema
  * via the `definition` "AccountType".
  */
-export type AccountType = 'CHECKING' | 'SAVINGS' | 'CREDIT_CARD' | 'EXTERNAL';
+export type AccountType = 'CHECKING' | 'SAVINGS' | 'CASH' | 'CREDIT_CARD' | 'ESCROW' | 'EXTERNAL';
 /**
  * Allowed transaction lifecycle states
  *
@@ -274,7 +274,7 @@ export type Account = Common1 & {
   /**
    * Allowed account types
    */
-  type: 'CHECKING' | 'SAVINGS' | 'CREDIT_CARD' | 'EXTERNAL';
+  type: 'CHECKING' | 'SAVINGS' | 'CASH' | 'CREDIT_CARD' | 'ESCROW' | 'EXTERNAL';
   institution?: Institution;
   aggregationServiceId?: AggregationServiceID;
   statementClosingDay?: StatementClosingDay;
@@ -617,10 +617,45 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID1 = string | null;
+/**
+ * Links two related transactions, such as transfer legs recorded in separate accounts.
+ */
+export type TransactionLink = Common6 & {
+  sourceTransactionId: SourceTransactionID;
+  destinationTransactionId: DestinationTransactionID;
+};
+/**
+ * UUID for the item
+ */
+export type ID6 = string;
+/**
+ * The timestamp of the creation of the item
+ */
+export type DateCreated6 = string;
+/**
+ * The timestamp of the last update or null if the item has not been updated yet
+ */
+export type LastUpdated6 = string | null;
+/**
+ * The timestamp of when the item was soft-deleted
+ */
+export type DateDeleted6 = string | null;
+/**
+ * Version number for optimistic concurrency control
+ */
+export type Version6 = number;
+/**
+ * UUID of the source transaction in the link.
+ */
+export type SourceTransactionID = string;
+/**
+ * UUID of the destination transaction in the link.
+ */
+export type DestinationTransactionID = string;
 /**
  * Defines a split within a transaction.
  */
-export type TransactionSplit = Common6 & {
+export type TransactionSplit = Common7 & {
   transactionId: TransactionID;
   amount: Amount2;
   categoryId: CategoryID2;
@@ -630,23 +665,23 @@ export type TransactionSplit = Common6 & {
 /**
  * UUID for the item
  */
-export type ID6 = string;
+export type ID7 = string;
 /**
  * The timestamp of the creation of the item
  */
-export type DateCreated6 = string;
+export type DateCreated7 = string;
 /**
  * The timestamp of the last update or null if the item has not been updated yet
  */
-export type LastUpdated6 = string | null;
+export type LastUpdated7 = string | null;
 /**
  * The timestamp of when the item was soft-deleted
  */
-export type DateDeleted6 = string | null;
+export type DateDeleted7 = string | null;
 /**
  * Version number for optimistic concurrency control
  */
-export type Version6 = number;
+export type Version7 = number;
 /**
  * The identifier of the parent transaction.
  */
@@ -700,6 +735,10 @@ export interface LucaSchema {
    * List of transactions
    */
   transactions: Transaction[];
+  /**
+   * List of links between related transactions
+   */
+  transactionLinks?: TransactionLink[];
   /**
    * List of transaction splits
    */
@@ -775,6 +814,16 @@ export interface Common6 {
   deletedAt?: DateDeleted6;
   version?: Version6;
 }
+/**
+ * Common properties for all schemas
+ */
+export interface Common7 {
+  id: ID7;
+  createdAt: DateCreated7;
+  updatedAt: LastUpdated7;
+  deletedAt?: DateDeleted7;
+  version?: Version7;
+}
 
 /**
  * Defines recurring financial transactions within the application.
@@ -1106,6 +1155,53 @@ export interface Common {
   version?: Version;
 }
 
+/**
+ * Links two related transactions, such as transfer legs recorded in separate accounts.
+ */
+export type TransactionLink = Common & {
+  sourceTransactionId: SourceTransactionID;
+  destinationTransactionId: DestinationTransactionID;
+};
+/**
+ * UUID for the item
+ */
+export type ID = string;
+/**
+ * The timestamp of the creation of the item
+ */
+export type DateCreated = string;
+/**
+ * The timestamp of the last update or null if the item has not been updated yet
+ */
+export type LastUpdated = string | null;
+/**
+ * The timestamp of when the item was soft-deleted
+ */
+export type DateDeleted = string | null;
+/**
+ * Version number for optimistic concurrency control
+ */
+export type Version = number;
+/**
+ * UUID of the source transaction in the link.
+ */
+export type SourceTransactionID = string;
+/**
+ * UUID of the destination transaction in the link.
+ */
+export type DestinationTransactionID = string;
+
+/**
+ * Common properties for all schemas
+ */
+export interface Common {
+  id: ID;
+  createdAt: DateCreated;
+  updatedAt: LastUpdated;
+  deletedAt?: DateDeleted;
+  version?: Version;
+}
+
 /**
  * Defines a split within a transaction.
  */

package/dist/esm/index.js

@@ -8,6 +8,7 @@ import {
   recurringTransactionEvent,
   statement,
   transaction,
+  transactionLink,
   transactionSplit
 } from './schemas/index.js';
 import { enums, LucaSchemas } from './enums.js';
@@ -30,6 +31,7 @@ const schemas = {
   recurringTransaction,
   recurringTransactionEvent,
   transaction,
+  transactionLink,
   transactionSplit,
   enums: enumsSchema
 };
@@ -43,6 +45,7 @@ export const recurringTransactionSchema = schemas.recurringTransaction;
 export const recurringTransactionEventSchema =
   schemas.recurringTransactionEvent;
 export const transactionSchema = schemas.transaction;
+export const transactionLinkSchema = schemas.transactionLink;
 export const transactionSplitSchema = schemas.transactionSplit;
 
 export {

package/dist/esm/lucaValidator.js

@@ -9,6 +9,7 @@ import statementSchemaJson from './schemas/statement.json' with { type: 'json' }
 import recurringTransactionSchemaJson from './schemas/recurringTransaction.json' with { type: 'json' };
 import recurringTransactionEventSchemaJson from './schemas/recurringTransactionEvent.json' with { type: 'json' };
 import transactionSchemaJson from './schemas/transaction.json' with { type: 'json' };
+import transactionLinkSchemaJson from './schemas/transactionLink.json' with { type: 'json' };
 import transactionSplitSchemaJson from './schemas/transactionSplit.json' with { type: 'json' };
 
 const schemas = {
@@ -19,6 +20,7 @@ const schemas = {
   recurringTransaction: recurringTransactionSchemaJson,
   recurringTransactionEvent: recurringTransactionEventSchemaJson,
   transaction: transactionSchemaJson,
+  transactionLink: transactionLinkSchemaJson,
   transactionSplit: transactionSplitSchemaJson
 };
 
@@ -193,6 +195,7 @@ export function getDateFieldPaths(schemaKey) {
  *   recurringTransactions: Array<string>,
  *   recurringTransactionEvents: Array<string>,
  *   transactions: Array<string>,
+ *   transactionLinks: Array<string>,
  *   transactionSplits: Array<string>
  * }}
  */
@@ -204,6 +207,7 @@ export function getDateFieldPathsByCollection() {
     recurringTransactions: getDateFieldPaths('recurringTransaction'),
     recurringTransactionEvents: getDateFieldPaths('recurringTransactionEvent'),
     transactions: getDateFieldPaths('transaction'),
+    transactionLinks: getDateFieldPaths('transactionLink'),
     transactionSplits: getDateFieldPaths('transactionSplit')
   };
 }

package/dist/esm/schemas/enums.json

@@ -11,12 +11,20 @@
     "RECURRING_TRANSACTION": "recurringTransaction",
     "RECURRING_TRANSACTION_EVENT": "recurringTransactionEvent",
     "TRANSACTION": "transaction",
+    "TRANSACTION_LINK": "transactionLink",
     "TRANSACTION_SPLIT": "transactionSplit"
   },
   "$defs": {
     "AccountType": {
       "type": "string",
-      "enum": ["CHECKING", "SAVINGS", "CREDIT_CARD", "EXTERNAL"],
+      "enum": [
+        "CHECKING",
+        "SAVINGS",
+        "CASH",
+        "CREDIT_CARD",
+        "ESCROW",
+        "EXTERNAL"
+      ],
       "description": "Allowed account types"
     },
     "TransactionState": {

package/dist/esm/schemas/index.js

@@ -6,6 +6,7 @@ import statement from './statement.json' with { type: 'json' };
 import recurringTransaction from './recurringTransaction.json' with { type: 'json' };
 import recurringTransactionEvent from './recurringTransactionEvent.json' with { type: 'json' };
 import transaction from './transaction.json' with { type: 'json' };
+import transactionLink from './transactionLink.json' with { type: 'json' };
 import transactionSplit from './transactionSplit.json' with { type: 'json' };
 import enums from './enums.json' with { type: 'json' };
 
@@ -18,6 +19,7 @@ export {
   recurringTransaction,
   recurringTransactionEvent,
   transaction,
+  transactionLink,
   transactionSplit,
   enums
 };
@@ -31,6 +33,7 @@ export default {
   recurringTransaction,
   recurringTransactionEvent,
   transaction,
+  transactionLink,
   transactionSplit,
   enums
 };

package/dist/esm/schemas/lucaSchema.json

@@ -68,6 +68,14 @@
         "$ref": "./transaction.json"
       }
     },
+    "transactionLinks": {
+      "type": "array",
+      "description": "List of links between related transactions",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "./transactionLink.json"
+      }
+    },
     "transactionSplits": {
       "type": "array",
       "description": "List of transaction splits",

package/dist/esm/schemas/transactionLink.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/LucaFinancial/LucaSchema/main/src/schemas/transactionLink.json",
+  "title": "Transaction Link",
+  "description": "Links two related transactions, such as transfer legs recorded in separate accounts.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "./common.json"
+    }
+  ],
+  "properties": {
+    "sourceTransactionId": {
+      "type": "string",
+      "title": "Source Transaction ID",
+      "format": "uuid",
+      "description": "UUID of the source transaction in the link."
+    },
+    "destinationTransactionId": {
+      "type": "string",
+      "title": "Destination Transaction ID",
+      "format": "uuid",
+      "description": "UUID of the destination transaction in the link."
+    }
+  },
+  "unevaluatedProperties": false,
+  "required": ["sourceTransactionId", "destinationTransactionId"]
+}

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type Account = Common & {
   /**
    * Allowed account types
    */
-  type: 'CHECKING' | 'SAVINGS' | 'CREDIT_CARD' | 'EXTERNAL';
+  type: 'CHECKING' | 'SAVINGS' | 'CASH' | 'CREDIT_CARD' | 'ESCROW' | 'EXTERNAL';
   institution?: Institution;
   aggregationServiceId?: AggregationServiceID;
   statementClosingDay?: StatementClosingDay;
@@ -174,7 +174,7 @@ export interface Common {
  * This interface was referenced by `LucaSchemaEnums`'s JSON-Schema
  * via the `definition` "AccountType".
  */
-export type AccountType = 'CHECKING' | 'SAVINGS' | 'CREDIT_CARD' | 'EXTERNAL';
+export type AccountType = 'CHECKING' | 'SAVINGS' | 'CASH' | 'CREDIT_CARD' | 'ESCROW' | 'EXTERNAL';
 /**
  * Allowed transaction lifecycle states
  *
@@ -274,7 +274,7 @@ export type Account = Common1 & {
   /**
    * Allowed account types
    */
-  type: 'CHECKING' | 'SAVINGS' | 'CREDIT_CARD' | 'EXTERNAL';
+  type: 'CHECKING' | 'SAVINGS' | 'CASH' | 'CREDIT_CARD' | 'ESCROW' | 'EXTERNAL';
   institution?: Institution;
   aggregationServiceId?: AggregationServiceID;
   statementClosingDay?: StatementClosingDay;
@@ -617,10 +617,45 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID1 = string | null;
+/**
+ * Links two related transactions, such as transfer legs recorded in separate accounts.
+ */
+export type TransactionLink = Common6 & {
+  sourceTransactionId: SourceTransactionID;
+  destinationTransactionId: DestinationTransactionID;
+};
+/**
+ * UUID for the item
+ */
+export type ID6 = string;
+/**
+ * The timestamp of the creation of the item
+ */
+export type DateCreated6 = string;
+/**
+ * The timestamp of the last update or null if the item has not been updated yet
+ */
+export type LastUpdated6 = string | null;
+/**
+ * The timestamp of when the item was soft-deleted
+ */
+export type DateDeleted6 = string | null;
+/**
+ * Version number for optimistic concurrency control
+ */
+export type Version6 = number;
+/**
+ * UUID of the source transaction in the link.
+ */
+export type SourceTransactionID = string;
+/**
+ * UUID of the destination transaction in the link.
+ */
+export type DestinationTransactionID = string;
 /**
  * Defines a split within a transaction.
  */
-export type TransactionSplit = Common6 & {
+export type TransactionSplit = Common7 & {
   transactionId: TransactionID;
   amount: Amount2;
   categoryId: CategoryID2;
@@ -630,23 +665,23 @@ export type TransactionSplit = Common6 & {
 /**
  * UUID for the item
  */
-export type ID6 = string;
+export type ID7 = string;
 /**
  * The timestamp of the creation of the item
  */
-export type DateCreated6 = string;
+export type DateCreated7 = string;
 /**
  * The timestamp of the last update or null if the item has not been updated yet
  */
-export type LastUpdated6 = string | null;
+export type LastUpdated7 = string | null;
 /**
  * The timestamp of when the item was soft-deleted
  */
-export type DateDeleted6 = string | null;
+export type DateDeleted7 = string | null;
 /**
  * Version number for optimistic concurrency control
  */
-export type Version6 = number;
+export type Version7 = number;
 /**
  * The identifier of the parent transaction.
  */
@@ -700,6 +735,10 @@ export interface LucaSchema {
    * List of transactions
    */
   transactions: Transaction[];
+  /**
+   * List of links between related transactions
+   */
+  transactionLinks?: TransactionLink[];
   /**
    * List of transaction splits
    */
@@ -775,6 +814,16 @@ export interface Common6 {
   deletedAt?: DateDeleted6;
   version?: Version6;
 }
+/**
+ * Common properties for all schemas
+ */
+export interface Common7 {
+  id: ID7;
+  createdAt: DateCreated7;
+  updatedAt: LastUpdated7;
+  deletedAt?: DateDeleted7;
+  version?: Version7;
+}
 
 /**
  * Defines recurring financial transactions within the application.
@@ -1106,6 +1155,53 @@ export interface Common {
   version?: Version;
 }
 
+/**
+ * Links two related transactions, such as transfer legs recorded in separate accounts.
+ */
+export type TransactionLink = Common & {
+  sourceTransactionId: SourceTransactionID;
+  destinationTransactionId: DestinationTransactionID;
+};
+/**
+ * UUID for the item
+ */
+export type ID = string;
+/**
+ * The timestamp of the creation of the item
+ */
+export type DateCreated = string;
+/**
+ * The timestamp of the last update or null if the item has not been updated yet
+ */
+export type LastUpdated = string | null;
+/**
+ * The timestamp of when the item was soft-deleted
+ */
+export type DateDeleted = string | null;
+/**
+ * Version number for optimistic concurrency control
+ */
+export type Version = number;
+/**
+ * UUID of the source transaction in the link.
+ */
+export type SourceTransactionID = string;
+/**
+ * UUID of the destination transaction in the link.
+ */
+export type DestinationTransactionID = string;
+
+/**
+ * Common properties for all schemas
+ */
+export interface Common {
+  id: ID;
+  createdAt: DateCreated;
+  updatedAt: LastUpdated;
+  deletedAt?: DateDeleted;
+  version?: Version;
+}
+
 /**
  * Defines a split within a transaction.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luca-financial/luca-schema",
-  "version": "3.0.3",
+  "version": "3.2.0",
   "description": "Schemas for the Luca Ledger application",
   "author": "Johnathan Aspinwall",
   "main": "dist/esm/index.js",