@luca-financial/luca-schema 2.2.0 → 2.3.1

package/dist/esm/index.d.ts

@@ -405,7 +405,7 @@ export type IsLocked = boolean;
  */
 export type RecurringTransaction = Common3 & {
   accountId: AccountID1;
-  categoryId?: CategoryID;
+  categoryId: CategoryID;
   amount: Amount;
   description: Description1;
   /**
@@ -534,8 +534,6 @@ export type Transaction = Common5 & {
   currency?: Currency;
   amount: Amount1;
   description: Description2;
-  memo?: Memo;
-  counterparty?: Counterparty;
   categoryId?: CategoryID1;
   statementId?: StatementID;
   aggregationServiceId?: AggregationServiceID1;
@@ -553,7 +551,6 @@ export type Transaction = Common5 & {
     | 'DISPUTED'
     | 'REFUNDED'
     | 'DELETED';
-  deletedAt?: DeletedAt;
 };
 /**
  * UUID for the item
@@ -603,14 +600,6 @@ export type Amount1 = number;
  * Description of the transaction
  */
 export type Description2 = string;
-/**
- * Additional notes for the transaction.
- */
-export type Memo = string | null;
-/**
- * Name of the other party (merchant/payor/payee).
- */
-export type Counterparty = string | null;
 /**
  * Category UUID for this transaction
  */
@@ -623,10 +612,6 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID1 = string | null;
-/**
- * Timestamp when the transaction was soft-deleted, if applicable (UTC).
- */
-export type DeletedAt = string | null;
 /**
  * Defines a split within a transaction.
  */
@@ -635,7 +620,6 @@ export type TransactionSplit = Common6 & {
   amount: Amount2;
   categoryId: CategoryID2;
   description?: Description3;
-  memo?: Memo1;
 };
 /**
  * UUID for the item
@@ -673,10 +657,6 @@ export type CategoryID2 = string | null;
  * Optional description for the split.
  */
 export type Description3 = string | null;
-/**
- * Additional notes for this split.
- */
-export type Memo1 = string | null;
 
 /**
  * Schema for the luca ledger
@@ -791,7 +771,7 @@ export interface Common6 {
  */
 export type RecurringTransaction = Common & {
   accountId: AccountID;
-  categoryId?: CategoryID;
+  categoryId: CategoryID;
   amount: Amount;
   description: Description;
   /**
@@ -1021,8 +1001,6 @@ export type Transaction = Common & {
   currency?: Currency;
   amount: Amount;
   description: Description;
-  memo?: Memo;
-  counterparty?: Counterparty;
   categoryId?: CategoryID;
   statementId?: StatementID;
   aggregationServiceId?: AggregationServiceID;
@@ -1040,7 +1018,6 @@ export type Transaction = Common & {
     | 'DISPUTED'
     | 'REFUNDED'
     | 'DELETED';
-  deletedAt?: DeletedAt;
 };
 /**
  * UUID for the item
@@ -1090,14 +1067,6 @@ export type Amount = number;
  * Description of the transaction
  */
 export type Description = string;
-/**
- * Additional notes for the transaction.
- */
-export type Memo = string | null;
-/**
- * Name of the other party (merchant/payor/payee).
- */
-export type Counterparty = string | null;
 /**
  * Category UUID for this transaction
  */
@@ -1110,10 +1079,6 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID = string | null;
-/**
- * Timestamp when the transaction was soft-deleted, if applicable (UTC).
- */
-export type DeletedAt = string | null;
 
 /**
  * Common properties for all schemas
@@ -1134,7 +1099,6 @@ export type TransactionSplit = Common & {
   amount: Amount;
   categoryId: CategoryID;
   description?: Description;
-  memo?: Memo;
 };
 /**
  * UUID for the item
@@ -1172,10 +1136,6 @@ export type CategoryID = string | null;
  * Optional description for the split.
  */
 export type Description = string | null;
-/**
- * Additional notes for this split.
- */
-export type Memo = string | null;
 
 /**
  * Common properties for all schemas

package/dist/esm/index.js

@@ -1,6 +1,12 @@
 import * as schemaIndex from './schemas/index.js';
 import { enums, LucaSchemas } from './enums.js';
-import { validate } from './lucaValidator.js';
+import {
+  getRequiredFields,
+  getValidFields,
+  stripInvalidFields,
+  validate,
+  validateCollection
+} from './lucaValidator.js';
 
 const schemas = { ...schemaIndex, enums: schemaIndex.enums };
 
@@ -14,5 +20,14 @@ export const recurringTransactionEventSchema =
 export const transactionSchema = schemas.transaction;
 export const transactionSplitSchema = schemas.transactionSplit;
 
-export { enums, LucaSchemas, schemas, validate };
+export {
+  enums,
+  LucaSchemas,
+  schemas,
+  validate,
+  validateCollection,
+  getValidFields,
+  getRequiredFields,
+  stripInvalidFields
+};
 export default schemas;

package/dist/esm/lucaValidator.js

@@ -25,6 +25,8 @@ const schemas = {
 const supportSchemas = [commonSchemaJson, enumsSchemaJson];
 
 let sharedAjv;
+const validFieldsCache = new Map();
+const requiredFieldsCache = new Map();
 
 function getValidator() {
   if (sharedAjv) return sharedAjv;
@@ -46,14 +48,134 @@ function getValidator() {
   return sharedAjv;
 }
 
-export function validate(schemaKey, data) {
-  const ajv = getValidator();
+function getSchema(schemaKey) {
   const schema = schemas[schemaKey];
   if (!schema) {
     throw new Error(`Unknown schema: ${schemaKey}`);
   }
+  return schema;
+}
+
+function usesCommonSchema(schema) {
+  if (!Array.isArray(schema?.allOf)) return false;
+  return schema.allOf.some(entry => {
+    if (!entry || typeof entry !== 'object') return false;
+    if (typeof entry.$ref !== 'string') return false;
+    return entry.$ref.includes('common.json');
+  });
+}
+
+function getSchemaProperties(schema) {
+  const properties = schema?.properties ?? {};
+  if (!usesCommonSchema(schema)) return properties;
+  return {
+    ...commonSchemaJson.properties,
+    ...properties
+  };
+}
+
+function getSchemaRequired(schema) {
+  const required = Array.isArray(schema?.required) ? schema.required : [];
+  if (!usesCommonSchema(schema)) return required;
+  const commonRequired = Array.isArray(commonSchemaJson.required)
+    ? commonSchemaJson.required
+    : [];
+  return [...commonRequired, ...required];
+}
+
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+export function validate(schemaKey, data) {
+  const ajv = getValidator();
+  const schema = getSchema(schemaKey);
   const isValid = ajv.validate(schema, data);
   return { valid: isValid, errors: ajv.errors ?? [] };
 }
 
+/**
+ * Returns a cached Set of valid field names for the given schema key.
+ * Treat the returned Set as read-only.
+ * @param {string} schemaKey
+ * @returns {Set<string>}
+ */
+export function getValidFields(schemaKey) {
+  if (validFieldsCache.has(schemaKey)) {
+    return validFieldsCache.get(schemaKey);
+  }
+  const schema = getSchema(schemaKey);
+  const properties = getSchemaProperties(schema);
+  const fields = new Set(Object.keys(properties));
+  validFieldsCache.set(schemaKey, fields);
+  return fields;
+}
+
+/**
+ * Returns a cached Set of required field names for the given schema key.
+ * Treat the returned Set as read-only.
+ * @param {string} schemaKey
+ * @returns {Set<string>}
+ */
+export function getRequiredFields(schemaKey) {
+  if (requiredFieldsCache.has(schemaKey)) {
+    return requiredFieldsCache.get(schemaKey);
+  }
+  const schema = getSchema(schemaKey);
+  const required = getSchemaRequired(schema);
+  const fields = new Set(required);
+  requiredFieldsCache.set(schemaKey, fields);
+  return fields;
+}
+
+/**
+ * Returns a new object containing only fields defined in the schema.
+ * @param {string} schemaKey
+ * @param {object | null | undefined} data
+ * @returns {object}
+ */
+export function stripInvalidFields(schemaKey, data) {
+  if (data === null || data === undefined) return {};
+  if (!isPlainObject(data)) {
+    throw new TypeError('Expected a plain object for data');
+  }
+  const validFields = getValidFields(schemaKey);
+  const cleaned = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (validFields.has(key)) cleaned[key] = value;
+  }
+  return cleaned;
+}
+
+/**
+ * Validates an array of entities efficiently and returns structured errors.
+ * @param {string} schemaKey
+ * @param {Array<any>} arrayOfEntities
+ * @returns {{ valid: boolean, errors: Array<{ index: number, entity: any, errors: Array<any> }> }}
+ */
+export function validateCollection(schemaKey, arrayOfEntities) {
+  if (!Array.isArray(arrayOfEntities)) {
+    throw new TypeError('Expected an array of entities');
+  }
+  const ajv = getValidator();
+  const schema = getSchema(schemaKey);
+  const validateFn = ajv.getSchema(schema.$id) ?? ajv.compile(schema);
+  const errors = [];
+
+  arrayOfEntities.forEach((entity, index) => {
+    const isValid = validateFn(entity);
+    if (!isValid) {
+      errors.push({
+        index,
+        entity,
+        errors: validateFn.errors ?? []
+      });
+    }
+  });
+
+  return { valid: errors.length === 0, errors };
+}
+
 export { schemas };

package/dist/esm/schemas/account.json

@@ -19,6 +19,7 @@
       "type": "string",
       "title": "Account Type",
       "$ref": "./enums.json#/$defs/AccountType",
+      "default": "SAVINGS",
       "description": "The type of the account."
     },
     "institution": {

package/dist/esm/schemas/category.json

@@ -30,6 +30,7 @@
       "type": ["string", "null"],
       "title": "Parent Category ID",
       "format": "uuid",
+      "default": null,
       "description": "The identifier of the parent category, if any. Null if the category is top-level. Parents must be top-level (no deeper than two levels; enforced outside JSON Schema)."
     }
   },

package/dist/esm/schemas/recurringTransaction.json

@@ -20,6 +20,7 @@
       "type": ["string", "null"],
       "title": "Category ID",
       "format": "uuid",
+      "default": null,
       "description": "Category identifier for organizing the transaction. Can be null if not categorized."
     },
     "amount": {
@@ -36,18 +37,21 @@
       "type": "string",
       "title": "Transaction Frequency",
       "$ref": "./enums.json#/$defs/RecurringTransactionFrequency",
+      "default": "MONTH",
       "description": "Defines the base unit of time for the repetition."
     },
     "interval": {
       "type": "integer",
       "title": "Frequency Interval",
       "minimum": 1,
+      "default": 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,
+      "default": null,
       "description": "The total number of times the transaction should occur. Can be null if not specified."
     },
     "startOn": {
@@ -66,11 +70,13 @@
       "type": "string",
       "title": "Recurring Transaction State",
       "$ref": "./enums.json#/$defs/RecurringTransactionState",
+      "default": "ACTIVE",
       "description": "Current state of the recurring transaction series."
     }
   },
   "required": [
     "accountId",
+    "categoryId",
     "amount",
     "description",
     "frequency",

package/dist/esm/schemas/transaction.json

@@ -52,20 +52,11 @@
       "minLength": 1,
       "description": "Description of the transaction"
     },
-    "memo": {
-      "type": ["string", "null"],
-      "title": "Memo",
-      "description": "Additional notes for the transaction."
-    },
-    "counterparty": {
-      "type": ["string", "null"],
-      "title": "Counterparty",
-      "description": "Name of the other party (merchant/payor/payee)."
-    },
     "categoryId": {
       "type": ["string", "null"],
       "title": "Category ID",
       "format": "uuid",
+      "default": null,
       "description": "Category UUID for this transaction"
     },
     "statementId": {
@@ -83,14 +74,8 @@
       "type": "string",
       "title": "Transaction State",
       "$ref": "./enums.json#/$defs/TransactionState",
+      "default": "PLANNED",
       "description": "The current state of the transaction."
-    },
-    "deletedAt": {
-      "type": ["string", "null"],
-      "title": "Deleted At",
-      "format": "date-time",
-      "pattern": "Z$",
-      "description": "Timestamp when the transaction was soft-deleted, if applicable (UTC)."
     }
   },
   "required": ["accountId", "date", "amount", "description", "transactionState"]

package/dist/esm/schemas/transactionSplit.json

@@ -26,17 +26,13 @@
       "type": ["string", "null"],
       "title": "Category ID",
       "format": "uuid",
+      "default": null,
       "description": "The identifier of the category for this split."
     },
     "description": {
       "type": ["string", "null"],
       "title": "Description",
       "description": "Optional description for the split."
-    },
-    "memo": {
-      "type": ["string", "null"],
-      "title": "Memo",
-      "description": "Additional notes for this split."
     }
   },
   "required": ["transactionId", "amount", "categoryId"]

package/dist/index.d.ts

@@ -405,7 +405,7 @@ export type IsLocked = boolean;
  */
 export type RecurringTransaction = Common3 & {
   accountId: AccountID1;
-  categoryId?: CategoryID;
+  categoryId: CategoryID;
   amount: Amount;
   description: Description1;
   /**
@@ -534,8 +534,6 @@ export type Transaction = Common5 & {
   currency?: Currency;
   amount: Amount1;
   description: Description2;
-  memo?: Memo;
-  counterparty?: Counterparty;
   categoryId?: CategoryID1;
   statementId?: StatementID;
   aggregationServiceId?: AggregationServiceID1;
@@ -553,7 +551,6 @@ export type Transaction = Common5 & {
     | 'DISPUTED'
     | 'REFUNDED'
     | 'DELETED';
-  deletedAt?: DeletedAt;
 };
 /**
  * UUID for the item
@@ -603,14 +600,6 @@ export type Amount1 = number;
  * Description of the transaction
  */
 export type Description2 = string;
-/**
- * Additional notes for the transaction.
- */
-export type Memo = string | null;
-/**
- * Name of the other party (merchant/payor/payee).
- */
-export type Counterparty = string | null;
 /**
  * Category UUID for this transaction
  */
@@ -623,10 +612,6 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID1 = string | null;
-/**
- * Timestamp when the transaction was soft-deleted, if applicable (UTC).
- */
-export type DeletedAt = string | null;
 /**
  * Defines a split within a transaction.
  */
@@ -635,7 +620,6 @@ export type TransactionSplit = Common6 & {
   amount: Amount2;
   categoryId: CategoryID2;
   description?: Description3;
-  memo?: Memo1;
 };
 /**
  * UUID for the item
@@ -673,10 +657,6 @@ export type CategoryID2 = string | null;
  * Optional description for the split.
  */
 export type Description3 = string | null;
-/**
- * Additional notes for this split.
- */
-export type Memo1 = string | null;
 
 /**
  * Schema for the luca ledger
@@ -791,7 +771,7 @@ export interface Common6 {
  */
 export type RecurringTransaction = Common & {
   accountId: AccountID;
-  categoryId?: CategoryID;
+  categoryId: CategoryID;
   amount: Amount;
   description: Description;
   /**
@@ -1021,8 +1001,6 @@ export type Transaction = Common & {
   currency?: Currency;
   amount: Amount;
   description: Description;
-  memo?: Memo;
-  counterparty?: Counterparty;
   categoryId?: CategoryID;
   statementId?: StatementID;
   aggregationServiceId?: AggregationServiceID;
@@ -1040,7 +1018,6 @@ export type Transaction = Common & {
     | 'DISPUTED'
     | 'REFUNDED'
     | 'DELETED';
-  deletedAt?: DeletedAt;
 };
 /**
  * UUID for the item
@@ -1090,14 +1067,6 @@ export type Amount = number;
  * Description of the transaction
  */
 export type Description = string;
-/**
- * Additional notes for the transaction.
- */
-export type Memo = string | null;
-/**
- * Name of the other party (merchant/payor/payee).
- */
-export type Counterparty = string | null;
 /**
  * Category UUID for this transaction
  */
@@ -1110,10 +1079,6 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID = string | null;
-/**
- * Timestamp when the transaction was soft-deleted, if applicable (UTC).
- */
-export type DeletedAt = string | null;
 
 /**
  * Common properties for all schemas
@@ -1134,7 +1099,6 @@ export type TransactionSplit = Common & {
   amount: Amount;
   categoryId: CategoryID;
   description?: Description;
-  memo?: Memo;
 };
 /**
  * UUID for the item
@@ -1172,10 +1136,6 @@ export type CategoryID = string | null;
  * Optional description for the split.
  */
 export type Description = string | null;
-/**
- * Additional notes for this split.
- */
-export type Memo = string | null;
 
 /**
  * Common properties for all schemas

package/package.json

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