@luca-financial/luca-schema 2.3.1 → 2.3.4

package/CHANGELOG.md

@@ -5,11 +5,57 @@ 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).
 
-## [v2.2.0]
+## [2.3.4] - 2026-02-06
+
+### Changed
+
+- Fixed release workflow for tag, release, and publish cycle.
+- Publish prereleases with appropriate npm dist-tag and use trusted publisher OIDC.
+
+## [2.3.3] - 2026-02-06
+
+### Changed
+
+- Update release workflow to use npm trusted publisher (OIDC) instead of an access token.
+
+## [2.3.2] - 2026-02-06
+
+### Changed
+
+- Update README schema documentation and validator utilities.
+- Update changelog entries for recent releases.
+- Add pull request template with changelog checklist item.
+
+## [v2.3.1] - 2026-02-01
+
+### Changed
+
+- Remove `applyDefaults` helper and update schemas.
+
+## [v2.3.0] - 2026-02-01
+
+### Changed
+
+- Remove `deletedAt` field and refactor validation logic.
+
+## [v2.2.0] - 2026-02-01
 
 ### Changed
 
 - Replace statement `status` with boolean `isLocked` and remove `StatementStatus` enum.
+- Breaking change from 2.1.5 to 2.2.0.
+
+## [2.1.5] - 2026-01-19
+
+### Added
+
+- Add comprehensive example JSON dataset for development and testing.
+
+## [2.1.4] - 2026-01-19
+
+### Changed
+
+- Rename copilot-rules.md to copilot-instructions.md and restructure content.
 
 ## [2.1.3] - 2026-01-18
 

package/README.md

@@ -34,6 +34,43 @@ if (!result.valid) {
 
 ## Available Schemas
 
+### Common Fields
+
+All entity schemas include common fields:
+
+```typescript
+const common = {
+  id: string;
+  createdAt: string;
+  updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
+};
+```
+
+### Account
+
+Validates financial accounts.
+
+```typescript
+const account = {
+  id: string;
+  name: string;
+  type: 'CHECKING' | 'SAVINGS' | 'CREDIT_CARD' | 'EXTERNAL';
+  institution: string | null;
+  aggregationServiceId: string | null;
+  statementClosingDay: number | null;
+  paymentDueDate: string | null;
+  creditLimit: number | null;
+  apr: number | null;
+  closedAt: string | null;
+  createdAt: string;
+  updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
+};
+```
+
 ### Transaction
 
 Validates financial transactions with properties like amount, date, and state.
@@ -44,12 +81,28 @@ const transaction = {
   accountId: string;
   categoryId: string | null;
   statementId: string | null;
+  authorizedAt: string | null;
+  postedAt: string | null;
+  currency: string | null;
   amount: number;
   date: string;
   description: string;
-  transactionState: TransactionState;
+  aggregationServiceId: string | null;
+  transactionState:
+    | 'PLANNED'
+    | 'ON_DECK'
+    | 'SCHEDULED'
+    | 'PENDING'
+    | 'COMPLETED'
+    | 'CANCELLED'
+    | 'FAILED'
+    | 'DISPUTED'
+    | 'REFUNDED'
+    | 'DELETED';
   createdAt: string;
   updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
 };
 ```
 
@@ -72,6 +125,8 @@ const recurringTransaction = {
   recurringTransactionState: 'ACTIVE' | 'PAUSED' | 'COMPLETED' | 'CANCELLED';
   createdAt: string;
   updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
 };
 ```
 
@@ -88,6 +143,8 @@ const category = {
   parentId: string | null;
   createdAt: string;
   updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
 };
 ```
 
@@ -98,12 +155,14 @@ Validates events that track changes to recurring transactions.
 ```typescript
 const recurringTransactionEvent = {
   id: string;
-  transactionId: string;
+  transactionId: string | null;
   recurringTransactionId: string;
   expectedDate: string;
   eventState: 'MODIFIED' | 'DELETED';
   createdAt: string;
   updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
 };
 ```
 
@@ -124,16 +183,79 @@ const statement = {
   isLocked: boolean;
   createdAt: string;
   updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
 };
 ```
 
+### TransactionSplit
+
+Validates splits within a transaction.
+
+```typescript
+const transactionSplit = {
+  id: string;
+  transactionId: string;
+  amount: number;
+  categoryId: string | null;
+  description: string | null;
+  createdAt: string;
+  updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
+};
+```
+
+### LucaSchema
+
+Validates the full ledger export.
+
+```typescript
+const lucaSchema = {
+  schemaVersion: string;
+  categories: Category[];
+  accounts: Account[];
+  statements: Statement[];
+  recurringTransactions: RecurringTransaction[];
+  recurringTransactionEvents: RecurringTransactionEvent[];
+  transactions: Transaction[];
+  transactionSplits: TransactionSplit[];
+};
+```
+
+## Validator Utilities
+
+This module exports helper utilities to inspect schemas and validate data:
+
+```typescript
+import {
+  validate,
+  validateCollection,
+  getValidFields,
+  getRequiredFields,
+  stripInvalidFields,
+  schemas,
+  enums,
+  LucaSchemas
+} from '@luca-financial/luca-schema';
+```
+
+- `validate(schemaKey, data)` → `{ valid: boolean, errors: AjvError[] }`
+- `validateCollection(schemaKey, array)` → `{ valid: boolean, errors: [{ index, entity, errors }] }`
+- `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
+- `schemas` → map of schema JSON objects
+- `enums` → enum definitions (including `LucaSchemas` keys)
+- `LucaSchemas` → names for schema keys (e.g., `LucaSchemas.TRANSACTION`)
+
 ## Development
 
 ```bash
-pnpm build    # Build the library
-pnpm test     # Run tests
-pnpm lint     # Check code style
-pnpm type-check # Check TypeScript types
+pnpm build
+pnpm test
+pnpm lint
+pnpm type-check
 ```
 
 ## Contributing

package/package.json

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