@luca-financial/luca-schema 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.3.0] - 2026-04-05
+
+### Added
+
+- Add support for linking related recurring transactions with a new `recurringTransactionLink` schema.
+- Add optional `recurringTransactionLinks` support to the aggregate Luca Schema, schema exports, enums, validator metadata, generated types, and bundled example data.
+- Add validation coverage for recurring transaction links in both entity-level and aggregate/example tests.
+
+### Changed
+
+- Update README and example documentation to describe recurring transaction links and their scheduled-transfer use cases.
+
 ## [3.2.0] - 2026-04-04
 
 ### Added

package/README.md

@@ -210,6 +210,22 @@ const transactionSplit = {
 };
 ```
 
+### RecurringTransactionLink
+
+Validates links between related recurring transactions, such as scheduled transfer legs recorded in separate accounts.
+
+```typescript
+const recurringTransactionLink = {
+  id: string;
+  sourceRecurringTransactionId: string;
+  destinationRecurringTransactionId: string;
+  createdAt: string;
+  updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
+};
+```
+
 ### TransactionLink
 
 Validates links between related transactions, such as transfers recorded in separate accounts.
@@ -240,6 +256,7 @@ const lucaSchema = {
   statements: Statement[];
   recurringTransactions: RecurringTransaction[];
   recurringTransactionEvents: RecurringTransactionEvent[];
+  recurringTransactionLinks?: RecurringTransactionLink[];
   transactions: Transaction[];
   transactionLinks?: TransactionLink[];
   transactionSplits: TransactionSplit[];
@@ -270,7 +287,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, transactionLinks, transactionSplits }`
+- `getDateFieldPathsByCollection()` → `{ accounts, categories, statements, recurringTransactions, recurringTransactionEvents, recurringTransactionLinks, 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

@@ -526,7 +526,42 @@ export type RecurringTransactionID = string;
  * The date when the occurrence is expected.
  */
 export type ExpectedDate = string;
-export type Transaction = Common5 & {
+/**
+ * Links two related recurring transactions, such as mirrored transfer schedules recorded in separate accounts.
+ */
+export type RecurringTransactionLink = Common5 & {
+  sourceRecurringTransactionId: SourceRecurringTransactionID;
+  destinationRecurringTransactionId: DestinationRecurringTransactionID;
+};
+/**
+ * UUID for the item
+ */
+export type ID5 = string;
+/**
+ * The timestamp of the creation of the item
+ */
+export type DateCreated5 = string;
+/**
+ * The timestamp of the last update or null if the item has not been updated yet
+ */
+export type LastUpdated5 = string | null;
+/**
+ * The timestamp of when the item was soft-deleted
+ */
+export type DateDeleted5 = string | null;
+/**
+ * Version number for optimistic concurrency control
+ */
+export type Version5 = number;
+/**
+ * UUID of the source recurring transaction in the link.
+ */
+export type SourceRecurringTransactionID = string;
+/**
+ * UUID of the destination recurring transaction in the link.
+ */
+export type DestinationRecurringTransactionID = string;
+export type Transaction = Common6 & {
   accountId: AccountID2;
   date: Date;
   authorizedAt?: AuthorizedAt;
@@ -556,23 +591,23 @@ export type Transaction = Common5 & {
 /**
  * UUID for the item
  */
-export type ID5 = string;
+export type ID6 = string;
 /**
  * The timestamp of the creation of the item
  */
-export type DateCreated5 = string;
+export type DateCreated6 = string;
 /**
  * The timestamp of the last update or null if the item has not been updated yet
  */
-export type LastUpdated5 = string | null;
+export type LastUpdated6 = string | null;
 /**
  * The timestamp of when the item was soft-deleted
  */
-export type DateDeleted5 = string | null;
+export type DateDeleted6 = string | null;
 /**
  * Version number for optimistic concurrency control
  */
-export type Version5 = number;
+export type Version6 = number;
 /**
  * ID of the account this transaction belongs to
  */
@@ -620,30 +655,30 @@ export type AggregationServiceID1 = string | null;
 /**
  * Links two related transactions, such as transfer legs recorded in separate accounts.
  */
-export type TransactionLink = Common6 & {
+export type TransactionLink = Common7 & {
   sourceTransactionId: SourceTransactionID;
   destinationTransactionId: DestinationTransactionID;
 };
 /**
  * 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;
 /**
  * UUID of the source transaction in the link.
  */
@@ -655,7 +690,7 @@ export type DestinationTransactionID = string;
 /**
  * Defines a split within a transaction.
  */
-export type TransactionSplit = Common7 & {
+export type TransactionSplit = Common8 & {
   transactionId: TransactionID;
   amount: Amount2;
   categoryId: CategoryID2;
@@ -665,23 +700,23 @@ export type TransactionSplit = Common7 & {
 /**
  * UUID for the item
  */
-export type ID7 = string;
+export type ID8 = string;
 /**
  * The timestamp of the creation of the item
  */
-export type DateCreated7 = string;
+export type DateCreated8 = string;
 /**
  * The timestamp of the last update or null if the item has not been updated yet
  */
-export type LastUpdated7 = string | null;
+export type LastUpdated8 = string | null;
 /**
  * The timestamp of when the item was soft-deleted
  */
-export type DateDeleted7 = string | null;
+export type DateDeleted8 = string | null;
 /**
  * Version number for optimistic concurrency control
  */
-export type Version7 = number;
+export type Version8 = number;
 /**
  * The identifier of the parent transaction.
  */
@@ -731,6 +766,10 @@ export interface LucaSchema {
    * List of recurring transaction events
    */
   recurringTransactionEvents: RecurringTransactionEvent[];
+  /**
+   * List of links between related recurring transactions
+   */
+  recurringTransactionLinks?: RecurringTransactionLink[];
   /**
    * List of transactions
    */
@@ -824,6 +863,16 @@ export interface Common7 {
   deletedAt?: DateDeleted7;
   version?: Version7;
 }
+/**
+ * Common properties for all schemas
+ */
+export interface Common8 {
+  id: ID8;
+  createdAt: DateCreated8;
+  updatedAt: LastUpdated8;
+  deletedAt?: DateDeleted8;
+  version?: Version8;
+}
 
 /**
  * Defines recurring financial transactions within the application.
@@ -975,6 +1024,53 @@ export interface Common {
   version?: Version;
 }
 
+/**
+ * Links two related recurring transactions, such as mirrored transfer schedules recorded in separate accounts.
+ */
+export type RecurringTransactionLink = Common & {
+  sourceRecurringTransactionId: SourceRecurringTransactionID;
+  destinationRecurringTransactionId: DestinationRecurringTransactionID;
+};
+/**
+ * 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 recurring transaction in the link.
+ */
+export type SourceRecurringTransactionID = string;
+/**
+ * UUID of the destination recurring transaction in the link.
+ */
+export type DestinationRecurringTransactionID = string;
+
+/**
+ * Common properties for all schemas
+ */
+export interface Common {
+  id: ID;
+  createdAt: DateCreated;
+  updatedAt: LastUpdated;
+  deletedAt?: DateDeleted;
+  version?: Version;
+}
+
 /**
  * Defines the schema for credit card statements.
  */

package/dist/esm/index.js

@@ -6,6 +6,7 @@ import {
   lucaSchema as lucaSchemaJson,
   recurringTransaction,
   recurringTransactionEvent,
+  recurringTransactionLink,
   statement,
   transaction,
   transactionLink,
@@ -30,6 +31,7 @@ const schemas = {
   statement,
   recurringTransaction,
   recurringTransactionEvent,
+  recurringTransactionLink,
   transaction,
   transactionLink,
   transactionSplit,
@@ -44,6 +46,7 @@ export const statementSchema = schemas.statement;
 export const recurringTransactionSchema = schemas.recurringTransaction;
 export const recurringTransactionEventSchema =
   schemas.recurringTransactionEvent;
+export const recurringTransactionLinkSchema = schemas.recurringTransactionLink;
 export const transactionSchema = schemas.transaction;
 export const transactionLinkSchema = schemas.transactionLink;
 export const transactionSplitSchema = schemas.transactionSplit;

package/dist/esm/lucaValidator.js

@@ -8,6 +8,7 @@ import lucaSchemaJson from './schemas/lucaSchema.json' with { type: 'json' };
 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 recurringTransactionLinkSchemaJson from './schemas/recurringTransactionLink.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' };
@@ -19,6 +20,7 @@ const schemas = {
   statement: statementSchemaJson,
   recurringTransaction: recurringTransactionSchemaJson,
   recurringTransactionEvent: recurringTransactionEventSchemaJson,
+  recurringTransactionLink: recurringTransactionLinkSchemaJson,
   transaction: transactionSchemaJson,
   transactionLink: transactionLinkSchemaJson,
   transactionSplit: transactionSplitSchemaJson
@@ -194,6 +196,7 @@ export function getDateFieldPaths(schemaKey) {
  *   statements: Array<string>,
  *   recurringTransactions: Array<string>,
  *   recurringTransactionEvents: Array<string>,
+ *   recurringTransactionLinks: Array<string>,
  *   transactions: Array<string>,
  *   transactionLinks: Array<string>,
  *   transactionSplits: Array<string>
@@ -206,6 +209,7 @@ export function getDateFieldPathsByCollection() {
     statements: getDateFieldPaths('statement'),
     recurringTransactions: getDateFieldPaths('recurringTransaction'),
     recurringTransactionEvents: getDateFieldPaths('recurringTransactionEvent'),
+    recurringTransactionLinks: getDateFieldPaths('recurringTransactionLink'),
     transactions: getDateFieldPaths('transaction'),
     transactionLinks: getDateFieldPaths('transactionLink'),
     transactionSplits: getDateFieldPaths('transactionSplit')

package/dist/esm/schemas/enums.json

@@ -10,6 +10,7 @@
     "STATEMENT": "statement",
     "RECURRING_TRANSACTION": "recurringTransaction",
     "RECURRING_TRANSACTION_EVENT": "recurringTransactionEvent",
+    "RECURRING_TRANSACTION_LINK": "recurringTransactionLink",
     "TRANSACTION": "transaction",
     "TRANSACTION_LINK": "transactionLink",
     "TRANSACTION_SPLIT": "transactionSplit"

package/dist/esm/schemas/index.js

@@ -5,6 +5,7 @@ import lucaSchema from './lucaSchema.json' with { type: 'json' };
 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 recurringTransactionLink from './recurringTransactionLink.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' };
@@ -18,6 +19,7 @@ export {
   statement,
   recurringTransaction,
   recurringTransactionEvent,
+  recurringTransactionLink,
   transaction,
   transactionLink,
   transactionSplit,
@@ -32,6 +34,7 @@ export default {
   statement,
   recurringTransaction,
   recurringTransactionEvent,
+  recurringTransactionLink,
   transaction,
   transactionLink,
   transactionSplit,

package/dist/esm/schemas/lucaSchema.json

@@ -60,6 +60,14 @@
         "$ref": "./recurringTransactionEvent.json"
       }
     },
+    "recurringTransactionLinks": {
+      "type": "array",
+      "description": "List of links between related recurring transactions",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "./recurringTransactionLink.json"
+      }
+    },
     "transactions": {
       "type": "array",
       "description": "List of transactions",

package/dist/esm/schemas/recurringTransactionLink.json

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

package/dist/index.d.ts

@@ -526,7 +526,42 @@ export type RecurringTransactionID = string;
  * The date when the occurrence is expected.
  */
 export type ExpectedDate = string;
-export type Transaction = Common5 & {
+/**
+ * Links two related recurring transactions, such as mirrored transfer schedules recorded in separate accounts.
+ */
+export type RecurringTransactionLink = Common5 & {
+  sourceRecurringTransactionId: SourceRecurringTransactionID;
+  destinationRecurringTransactionId: DestinationRecurringTransactionID;
+};
+/**
+ * UUID for the item
+ */
+export type ID5 = string;
+/**
+ * The timestamp of the creation of the item
+ */
+export type DateCreated5 = string;
+/**
+ * The timestamp of the last update or null if the item has not been updated yet
+ */
+export type LastUpdated5 = string | null;
+/**
+ * The timestamp of when the item was soft-deleted
+ */
+export type DateDeleted5 = string | null;
+/**
+ * Version number for optimistic concurrency control
+ */
+export type Version5 = number;
+/**
+ * UUID of the source recurring transaction in the link.
+ */
+export type SourceRecurringTransactionID = string;
+/**
+ * UUID of the destination recurring transaction in the link.
+ */
+export type DestinationRecurringTransactionID = string;
+export type Transaction = Common6 & {
   accountId: AccountID2;
   date: Date;
   authorizedAt?: AuthorizedAt;
@@ -556,23 +591,23 @@ export type Transaction = Common5 & {
 /**
  * UUID for the item
  */
-export type ID5 = string;
+export type ID6 = string;
 /**
  * The timestamp of the creation of the item
  */
-export type DateCreated5 = string;
+export type DateCreated6 = string;
 /**
  * The timestamp of the last update or null if the item has not been updated yet
  */
-export type LastUpdated5 = string | null;
+export type LastUpdated6 = string | null;
 /**
  * The timestamp of when the item was soft-deleted
  */
-export type DateDeleted5 = string | null;
+export type DateDeleted6 = string | null;
 /**
  * Version number for optimistic concurrency control
  */
-export type Version5 = number;
+export type Version6 = number;
 /**
  * ID of the account this transaction belongs to
  */
@@ -620,30 +655,30 @@ export type AggregationServiceID1 = string | null;
 /**
  * Links two related transactions, such as transfer legs recorded in separate accounts.
  */
-export type TransactionLink = Common6 & {
+export type TransactionLink = Common7 & {
   sourceTransactionId: SourceTransactionID;
   destinationTransactionId: DestinationTransactionID;
 };
 /**
  * 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;
 /**
  * UUID of the source transaction in the link.
  */
@@ -655,7 +690,7 @@ export type DestinationTransactionID = string;
 /**
  * Defines a split within a transaction.
  */
-export type TransactionSplit = Common7 & {
+export type TransactionSplit = Common8 & {
   transactionId: TransactionID;
   amount: Amount2;
   categoryId: CategoryID2;
@@ -665,23 +700,23 @@ export type TransactionSplit = Common7 & {
 /**
  * UUID for the item
  */
-export type ID7 = string;
+export type ID8 = string;
 /**
  * The timestamp of the creation of the item
  */
-export type DateCreated7 = string;
+export type DateCreated8 = string;
 /**
  * The timestamp of the last update or null if the item has not been updated yet
  */
-export type LastUpdated7 = string | null;
+export type LastUpdated8 = string | null;
 /**
  * The timestamp of when the item was soft-deleted
  */
-export type DateDeleted7 = string | null;
+export type DateDeleted8 = string | null;
 /**
  * Version number for optimistic concurrency control
  */
-export type Version7 = number;
+export type Version8 = number;
 /**
  * The identifier of the parent transaction.
  */
@@ -731,6 +766,10 @@ export interface LucaSchema {
    * List of recurring transaction events
    */
   recurringTransactionEvents: RecurringTransactionEvent[];
+  /**
+   * List of links between related recurring transactions
+   */
+  recurringTransactionLinks?: RecurringTransactionLink[];
   /**
    * List of transactions
    */
@@ -824,6 +863,16 @@ export interface Common7 {
   deletedAt?: DateDeleted7;
   version?: Version7;
 }
+/**
+ * Common properties for all schemas
+ */
+export interface Common8 {
+  id: ID8;
+  createdAt: DateCreated8;
+  updatedAt: LastUpdated8;
+  deletedAt?: DateDeleted8;
+  version?: Version8;
+}
 
 /**
  * Defines recurring financial transactions within the application.
@@ -975,6 +1024,53 @@ export interface Common {
   version?: Version;
 }
 
+/**
+ * Links two related recurring transactions, such as mirrored transfer schedules recorded in separate accounts.
+ */
+export type RecurringTransactionLink = Common & {
+  sourceRecurringTransactionId: SourceRecurringTransactionID;
+  destinationRecurringTransactionId: DestinationRecurringTransactionID;
+};
+/**
+ * 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 recurring transaction in the link.
+ */
+export type SourceRecurringTransactionID = string;
+/**
+ * UUID of the destination recurring transaction in the link.
+ */
+export type DestinationRecurringTransactionID = string;
+
+/**
+ * Common properties for all schemas
+ */
+export interface Common {
+  id: ID;
+  createdAt: DateCreated;
+  updatedAt: LastUpdated;
+  deletedAt?: DateDeleted;
+  version?: Version;
+}
+
 /**
  * Defines the schema for credit card statements.
  */

package/package.json

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