@luca-financial/luca-schema 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+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).
+
+## [1.3.0] - 2025-10-11
+
+### Added
+
+- Full TypeScript support with comprehensive type definitions
+- Modern CI/CD pipeline with Node.js 20.x and 22.x support
+- Comprehensive test suite with 95% code coverage
+- Pre-commit hooks with lint-staged for code quality
+- Test utilities for creating mock data objects
+- Enhanced error handling and validation interfaces
+- Dual ESM/CJS build support
+- Professional package metadata and documentation
+
+### Changed
+
+- **BREAKING**: Migrated from JavaScript to TypeScript
+- Updated minimum Node.js requirement to >=20.0.0
+- Replaced console.error statements with proper error throwing
+- Enhanced README with TypeScript examples and better documentation
+- Improved build system with TypeScript compilation
+- Updated dependencies to latest secure versions
+
+### Removed
+
+- **BREAKING**: Removed Node.js 18.x support
+- Removed deprecated Husky installation scripts
+- Removed console pollution from library code
+
+### Fixed
+
+- CI/CD pipeline compatibility with modern Node.js versions
+- Husky pre-commit hooks updated to v9 format
+- ESLint configuration optimized for TypeScript projects
+
+## [1.2.3] - Previous releases
+
+- Legacy JavaScript implementation
+- Basic schema validation functionality

package/README.md

@@ -1,6 +1,6 @@
 # LucaSchema
 
-Schema validation library for the Luca Ledger application.
+Schema validation library for the Luca Ledger application. Provides type-safe validation for financial transactions, entities, and related data structures. Supports TypeScript.
 
 ## Installation
 
@@ -10,32 +10,129 @@ npm install @luca-financial/luca-schema
 
 ## Usage
 
-```javascript
-import { lucaValidator, enums } from '@luca-financial/luca-schema';
+```typescript
+import { lucaValidator, enums, schemas } from '@luca-financial/luca-schema';
 
 // Validate a transaction
 const validateTransaction = lucaValidator.getSchema('transaction');
+const transactionData = {
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  payorId: '123e4567-e89b-12d3-a456-426614174001',
+  payeeId: '123e4567-e89b-12d3-a456-426614174002',
+  categoryId: '123e4567-e89b-12d3-a456-426614174003',
+  amount: 100.5,
+  date: '2024-01-01',
+  description: 'Test transaction',
+  transactionState: enums.TransactionStateEnum.COMPLETED,
+  createdAt: '2024-01-01T00:00:00Z',
+  updatedAt: null
+};
+
 const isValid = validateTransaction(transactionData);
 
 if (!isValid) {
   console.error('Validation errors:', validateTransaction.errors);
 }
 
-// Access schemas directly
-console.log('Available schemas:', Object.keys(schemas));
-
-// Use enums for consistency
-const transactionState = enums.TransactionStateEnum.COMPLETED;
+// Alternative: Use schemas directly with the validate method
+const isValidDirect = lucaValidator.validate(
+  schemas.transaction,
+  transactionData
+);
 ```
 
 ## Available Schemas
 
-- `transaction` - Financial transactions
-- `recurringTransaction` - Recurring transaction templates
-- `recurringTransactionEvent` - Recurring transaction events
-- `category` - Transaction categories
-- `entity` - Financial entities
-- `lucaSchema` - Complete schema structure
+### Transaction
+
+Validates financial transactions with properties like amount, date, and state.
+
+```typescript
+const transaction = {
+  id: string;
+  payorId: string;
+  payeeId: string;
+  categoryId: string | null;
+  amount: number;
+  date: string;
+  description: string;
+  transactionState: TransactionState;
+  createdAt: string;
+  updatedAt: string | null;
+};
+```
+
+### RecurringTransaction
+
+Validates recurring transaction templates with frequency and interval settings.
+
+```typescript
+const recurringTransaction = {
+  id: string;
+  payorId: string;
+  payeeId: string;
+  categoryId: string | null;
+  amount: number;
+  description: string;
+  frequency: 'DAY' | 'WEEK' | 'MONTH' | 'YEAR';
+  interval: number;
+  occurrences: number | null;
+  startOn: string;
+  endOn: string | null;
+  recurringTransactionState: 'ACTIVE' | 'PAUSED' | 'COMPLETED' | 'CANCELLED';
+  createdAt: string;
+  updatedAt: string | null;
+};
+```
+
+### Entity
+
+Validates financial entities like accounts, retailers, or individuals.
+
+```typescript
+const entity = {
+  id: string;
+  name: string;
+  description: string | null;
+  entityType: 'ACCOUNT' | 'RETAILER' | 'SERVICE' | 'INDIVIDUAL' | 'UTILITY' | 'GOVERNMENT';
+  entityStatus: 'ACTIVE' | 'INACTIVE' | 'SUSPENDED' | 'DELETED' | 'CLOSED';
+  createdAt: string;
+  updatedAt: string | null;
+};
+```
+
+### Category
+
+Validates transaction categories with optional parent relationships.
+
+```typescript
+const category = {
+  id: string;
+  name: string;
+  description: string | null;
+  parentId: string | null;
+  defaultCategoryId: string | null;
+  categoryType: 'DEFAULT' | 'MODIFIED' | 'CUSTOM';
+  createdAt: string;
+  updatedAt: string | null;
+};
+```
+
+### RecurringTransactionEvent
+
+Validates events that track changes to recurring transactions.
+
+```typescript
+const recurringTransactionEvent = {
+  id: string;
+  transactionId: string;
+  recurringTransactionId: string;
+  expectedDate: string;
+  eventState: 'MODIFIED' | 'DELETED';
+  createdAt: string;
+  updatedAt: string | null;
+};
+```
 
 ## Development
 
@@ -43,4 +140,17 @@ const transactionState = enums.TransactionStateEnum.COMPLETED;
 yarn build    # Build the library
 yarn test     # Run tests
 yarn lint     # Check code style
+yarn type-check # Check TypeScript types
 ```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/schemas/category.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/LucaFinancial/LucaSchema/main/src/schemas/category.json",
+  "title": "Category",
+  "description": "Defines the schema for categories used to organize transactions within a ledger application. Categories can be default, modified, or custom, providing flexibility in categorization.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "./common.json"
+    }
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "title": "Category Name",
+      "description": "The name of the category."
+    },
+    "description": {
+      "type": ["string", "null"],
+      "title": "Description",
+      "description": "A description of the category, providing additional context. Can be null if not specified."
+    },
+    "parentId": {
+      "type": ["string", "null"],
+      "title": "Parent Category ID",
+      "format": "uuid",
+      "description": "The identifier of the parent category, if any. Null if the category is top-level."
+    },
+    "defaultCategoryId": {
+      "type": ["string", "null"],
+      "title": "Default Category ID",
+      "format": "uuid",
+      "description": "For custom categories, this indicates the default category from which this was derived. Required if categoryType is MODIFIED."
+    },
+    "categoryType": {
+      "type": "string",
+      "title": "Category Type",
+      "enum": ["DEFAULT", "MODIFIED", "CUSTOM"],
+      "description": "The type of the category, indicating whether it is a default, modified, or custom category."
+    }
+  },
+  "required": [
+    "name",
+    "description",
+    "parentId",
+    "defaultCategoryId",
+    "categoryType"
+  ],
+  "if": {
+    "properties": {
+      "categoryType": {
+        "const": "MODIFIED"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "defaultCategoryId": {
+        "type": "string"
+      }
+    }
+  }
+}

package/dist/cjs/schemas/common.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/LucaFinancial/LucaSchema/main/src/schemas/common.json",
+  "title": "Common",
+  "description": "Common properties for all schemas",
+  "type": "object",
+  "required": ["id", "createdAt", "updatedAt"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "title": "ID",
+      "format": "uuid",
+      "readOnly": true,
+      "description": "UUID for the item"
+    },
+    "createdAt": {
+      "type": "string",
+      "title": "Date Created",
+      "format": "date-time",
+      "readOnly": true,
+      "description": "The timestamp of the creation of the item"
+    },
+    "updatedAt": {
+      "type": ["string", "null"],
+      "title": "Last Updated",
+      "format": "date-time",
+      "description": "The timestamp of the last update or null if the item has not been updated yet"
+    }
+  }
+}

package/dist/cjs/schemas/entity.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/LucaFinancial/LucaSchema/main/src/schemas/entity.json",
+  "title": "Entity",
+  "description": "Defines the schema for entities within the application, categorizing them into specific, predefined types such as account, retailer, business, individual, utility, and government. This schema includes basic details and timestamps for creation and updates.",
+  "type": "object",
+  "required": ["name", "description", "entityType", "entityStatus"],
+  "allOf": [
+    {
+      "$ref": "./common.json"
+    }
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "title": "Entity Name",
+      "description": "The name of the entity."
+    },
+    "description": {
+      "type": ["string", "null"],
+      "title": "Description",
+      "description": "A description of the entity. This can be null if no description is provided."
+    },
+    "entityType": {
+      "type": "string",
+      "title": "Entity Type",
+      "enum": [
+        "ACCOUNT",
+        "RETAILER",
+        "SERVICE",
+        "INDIVIDUAL",
+        "UTILITY",
+        "GOVERNMENT"
+      ],
+      "description": "The type of the entity, indicating its role or classification within the application. Controlled to specific predefined options for consistency and integrity."
+    },
+    "entityStatus": {
+      "type": "string",
+      "title": "Entity Status",
+      "enum": ["ACTIVE", "INACTIVE", "SUSPENDED", "DELETED", "CLOSED"],
+      "description": "The status of the entity, indicating whether it is active, inactive, suspended, or deleted. Controlled to specific predefined options for consistency and integrity."
+    }
+  }
+}

package/dist/cjs/schemas/index.ts

@@ -0,0 +1,30 @@
+import { AnySchema } from 'ajv';
+import category from './category.json';
+import common from './common.json';
+import entity from './entity.json';
+import lucaSchema from './lucaSchema.json';
+import recurringTransaction from './recurringTransaction.json';
+import recurringTransactionEvent from './recurringTransactionEvent.json';
+import transaction from './transaction.json';
+
+export interface Schemas {
+  category: AnySchema;
+  common: AnySchema;
+  entity: AnySchema;
+  lucaSchema: AnySchema;
+  recurringTransaction: AnySchema;
+  recurringTransactionEvent: AnySchema;
+  transaction: AnySchema;
+}
+
+const schemas: Schemas = {
+  category,
+  common,
+  entity,
+  lucaSchema,
+  recurringTransaction,
+  recurringTransactionEvent,
+  transaction
+};
+
+export default schemas;

package/dist/cjs/schemas/lucaSchema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/LucaFinancial/LucaSchema/main/src/schemas/lucaSchema.json",
+  "title": "Luca Schema",
+  "description": "Schema for the luca ledger",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "categories",
+    "entities",
+    "recurringTransactions",
+    "recurringTransactionEvents",
+    "transactions"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "description": "Schema version of the luca ledger"
+    },
+    "categories": {
+      "type": "array",
+      "description": "List of categories",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "./category.json"
+      }
+    },
+    "entities": {
+      "type": "array",
+      "description": "List of entities",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "./entity.json"
+      }
+    },
+    "recurringTransactions": {
+      "type": "array",
+      "description": "List of recurring transactions",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "./recurringTransaction.json"
+      }
+    },
+    "recurringTransactionEvents": {
+      "type": "array",
+      "description": "List of recurring transaction events",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "./recurringTransactionEvent.json"
+      }
+    },
+    "transactions": {
+      "type": "array",
+      "description": "List of transactions",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "./transaction.json"
+      }
+    }
+  }
+}

package/dist/cjs/schemas/recurringTransaction.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/LucaFinancial/LucaSchema/main/src/schemas/recurringTransaction.json",
+  "title": "Recurring Transaction",
+  "description": "Defines recurring financial transactions within the application, including their scheduling, frequency, interval, and optional constraints like total occurrences or an end date.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "./common.json"
+    }
+  ],
+  "properties": {
+    "payorId": {
+      "type": "string",
+      "title": "Payor ID",
+      "format": "uuid",
+      "description": "Identifier for the payor in the transaction."
+    },
+    "payeeId": {
+      "type": "string",
+      "title": "Payee ID",
+      "format": "uuid",
+      "description": "Identifier for the payee in the transaction."
+    },
+    "categoryId": {
+      "type": ["string", "null"],
+      "title": "Category ID",
+      "format": "uuid",
+      "description": "Category identifier for organizing the transaction. Can be null if not categorized."
+    },
+    "amount": {
+      "type": "number",
+      "title": "Amount",
+      "minimum": 0,
+      "multipleOf": 0.01,
+      "description": "The monetary value of the transaction."
+    },
+    "frequency": {
+      "type": "string",
+      "title": "Transaction Frequency",
+      "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
+      "description": "Defines the base unit of time for the repetition."
+    },
+    "interval": {
+      "type": "integer",
+      "title": "Frequency Interval",
+      "minimum": 1,
+      "description": "Specifies the number of frequency units between each occurrence (e.g., every 2 weeks)."
+    },
+    "occurrences": {
+      "type": ["integer", "null"],
+      "title": "Total Occurrences",
+      "minimum": 1,
+      "description": "The total number of times the transaction should occur. Can be null if not specified."
+    },
+    "startOn": {
+      "type": "string",
+      "title": "Start Date",
+      "format": "date",
+      "description": "The date on which the recurring transaction series should begin."
+    },
+    "endOn": {
+      "type": ["string", "null"],
+      "title": "End Date",
+      "format": "date",
+      "description": "The date on which the recurring transaction series should end. Can be null."
+    },
+    "recurringTransactionState": {
+      "type": "string",
+      "title": "Recurring Transaction State",
+      "enum": ["ACTIVE", "PAUSED", "COMPLETED", "CANCELLED"],
+      "description": "Current state of the recurring transaction series."
+    }
+  },
+  "required": [
+    "payorId",
+    "payeeId",
+    "amount",
+    "frequency",
+    "interval",
+    "occurrences",
+    "startOn",
+    "endOn",
+    "recurringTransactionState"
+  ]
+}

package/dist/cjs/schemas/recurringTransactionEvent.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/LucaFinancial/LucaSchema/main/src/schemas/recurringTransactionEvent.json",
+  "title": "Recurring Transaction Event",
+  "description": "Manages occurrences of recurring transactions, including tracking their modifications or logical deletions. 'transactionId' is required when an occurrence is modified to link it to an actual transaction.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "./common.json"
+    }
+  ],
+  "properties": {
+    "transactionId": {
+      "type": ["string", "null"],
+      "title": "Associated Transaction ID",
+      "format": "uuid",
+      "description": "Identifier of the actual transaction, required if the occurrence is modified."
+    },
+    "recurringTransactionId": {
+      "type": "string",
+      "title": "Recurring Transaction ID",
+      "format": "uuid",
+      "description": "Identifier of the associated recurring transaction."
+    },
+    "expectedDate": {
+      "type": "string",
+      "title": "Expected Date",
+      "format": "date",
+      "description": "The date when the occurrence is expected."
+    },
+    "eventState": {
+      "type": "string",
+      "title": "Event State",
+      "enum": ["MODIFIED", "DELETED"],
+      "description": "State of the occurrence, indicating if it has been modified or logically deleted."
+    }
+  },
+  "required": [
+    "transactionId",
+    "recurringTransactionId",
+    "expectedDate",
+    "eventState"
+  ],
+  "if": {
+    "properties": {
+      "eventState": {
+        "const": "MODIFIED"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "transactionId": {
+        "type": "string"
+      }
+    }
+  }
+}

package/dist/cjs/schemas/transaction.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/LucaFinancial/LucaSchema/main/src/schemas/transaction.json",
+  "title": "Transaction",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "./common.json"
+    }
+  ],
+  "properties": {
+    "date": {
+      "type": "string",
+      "title": "Transaction Date",
+      "format": "date",
+      "description": "The date the transaction took place."
+    },
+    "payorId": {
+      "type": "string",
+      "title": "Payor ID",
+      "format": "uuid",
+      "description": "Identifier for the payor in the transaction."
+    },
+    "payeeId": {
+      "type": "string",
+      "title": "Payee ID",
+      "format": "uuid",
+      "description": "Identifier for the payee in the transaction."
+    },
+    "categoryId": {
+      "type": ["string", "null"],
+      "title": "Category ID",
+      "format": "uuid",
+      "description": "Category identifier for organizing the transaction. Can be null if not categorized."
+    },
+    "amount": {
+      "type": "number",
+      "title": "Amount",
+      "minimum": 0,
+      "multipleOf": 0.01,
+      "description": "The monetary value of the transaction."
+    },
+    "description": {
+      "type": "string",
+      "title": "Description",
+      "maxLength": 500,
+      "description": "A brief description of the transaction."
+    },
+    "transactionState": {
+      "type": "string",
+      "title": "Transaction State",
+      "enum": [
+        "PLANNED",
+        "SCHEDULED",
+        "PENDING",
+        "COMPLETED",
+        "CANCELLED",
+        "FAILED",
+        "DISPUTED",
+        "REFUNDED",
+        "TENTATIVE",
+        "UPCOMING",
+        "DELETED"
+      ],
+      "description": "The current state of the transaction."
+    }
+  },
+  "required": [
+    "date",
+    "payorId",
+    "payeeId",
+    "amount",
+    "description",
+    "transactionState"
+  ]
+}

package/dist/enums.d.ts

@@ -0,0 +1,12 @@
+import { SchemaType, TransactionState, CategoryType, EntityType, EntityStatus, RecurringTransactionFrequency, RecurringTransactionState, RecurringTransactionEventStatus } from './types/enums';
+declare const enums: {
+    readonly CategoryTypeEnum: Record<string, CategoryType>;
+    readonly EntityTypeEnum: Record<string, EntityType>;
+    readonly EntityStatusEnum: Record<string, EntityStatus>;
+    readonly RecurringTransactionFrequencyEnum: Record<string, RecurringTransactionFrequency>;
+    readonly RecurringTransactionStateEnum: Record<string, RecurringTransactionState>;
+    readonly RecurringTransactionEventStatusEnum: Record<string, RecurringTransactionEventStatus>;
+    readonly SchemasEnum: Record<string, SchemaType>;
+    readonly TransactionStateEnum: Record<string, TransactionState>;
+};
+export default enums;