@f-o-t/ofx 2.1.0 → 2.3.0

package/README.md

@@ -260,6 +260,62 @@ console.log("Accounts:", result.accounts);
 console.log("Balances:", result.balances);
 ```
 
+### Batch Streaming Functions
+
+For processing multiple OFX files in a single operation with progress tracking.
+
+#### `parseBatchStream(files): AsyncGenerator<BatchStreamEvent>`
+
+Parses multiple OFX files sequentially, yielding events as they are parsed. Ideal for importing multiple bank statements at once.
+
+```typescript
+import { parseBatchStream, type BatchFileInput } from "@fot/ofx";
+import { readFileSync } from "node:fs";
+
+const files: BatchFileInput[] = [
+  { filename: "january.ofx", buffer: new Uint8Array(readFileSync("january.ofx")) },
+  { filename: "february.ofx", buffer: new Uint8Array(readFileSync("february.ofx")) },
+  { filename: "march.ofx", buffer: new Uint8Array(readFileSync("march.ofx")) },
+];
+
+for await (const event of parseBatchStream(files)) {
+  switch (event.type) {
+    case "file_start":
+      console.log(`Processing: ${event.filename}`);
+      break;
+    case "transaction":
+      console.log(`File ${event.fileIndex}: ${event.data.NAME} - ${event.data.TRNAMT}`);
+      break;
+    case "file_complete":
+      console.log(`Completed ${event.filename}: ${event.transactionCount} transactions`);
+      break;
+    case "file_error":
+      console.error(`Error in ${event.filename}: ${event.error}`);
+      break;
+    case "batch_complete":
+      console.log(`Batch done: ${event.totalTransactions} transactions from ${event.totalFiles} files`);
+      break;
+  }
+}
+```
+
+#### `parseBatchStreamToArray(files): Promise<BatchParsedFile[]>`
+
+Collects all batch results into an array for easier processing.
+
+```typescript
+import { parseBatchStreamToArray } from "@fot/ofx";
+
+const results = await parseBatchStreamToArray(files);
+
+for (const file of results) {
+  console.log(`${file.filename}: ${file.transactions.length} transactions`);
+  if (file.error) {
+    console.error(`  Error: ${file.error}`);
+  }
+}
+```
+
 ## Encoding Support
 
 The library automatically detects and handles various character encodings commonly used in OFX files, especially from Brazilian banks.
@@ -408,36 +464,95 @@ type StreamEvent =
   | { type: "complete"; transactionCount: number };
 ```
 
-## Schemas
+## Validation & Schemas
+
+All parsing and generation functions use Zod schemas for runtime validation, ensuring type safety and data integrity.
 
-All Zod schemas are exported for custom validation:
+### Input Validation for Generation
+
+When generating OFX files, you can validate your inputs using the exported schemas:
 
 ```typescript
-import { schemas } from "@fot/ofx";
+import {
+  generateBankStatement,
+  generateBankStatementOptionsSchema,
+  type GenerateBankStatementOptions,
+} from "@fot/ofx";
+
+// Validate options before generating
+const options: GenerateBankStatementOptions = {
+  bankId: "123456",
+  accountId: "987654321",
+  accountType: "CHECKING",
+  currency: "USD",
+  startDate: new Date("2025-01-01"),
+  endDate: new Date("2025-01-31"),
+  transactions: [],
+};
+
+// Runtime validation
+const validatedOptions = generateBankStatementOptionsSchema.parse(options);
+const statement = generateBankStatement(validatedOptions);
+```
 
-const customTransactionSchema = schemas.transaction.extend({
+### Available Schemas
+
+All Zod schemas are exported for custom validation and extension:
+
+```typescript
+import {
+  transactionSchema,
+  bankAccountSchema,
+  ofxDocumentSchema,
+} from "@fot/ofx";
+
+// Extend schemas for custom validation
+const customTransactionSchema = transactionSchema.extend({
   customField: z.string(),
 });
 ```
 
-Available schemas:
-
-- `schemas.transaction`
-- `schemas.transactionType`
-- `schemas.transactionList`
-- `schemas.bankAccount`
-- `schemas.creditCardAccount`
-- `schemas.accountType`
-- `schemas.balance`
-- `schemas.status`
-- `schemas.financialInstitution`
-- `schemas.signOnResponse`
-- `schemas.bankStatementResponse`
-- `schemas.creditCardStatementResponse`
-- `schemas.ofxDocument`
-- `schemas.ofxHeader`
-- `schemas.ofxResponse`
-- `schemas.ofxDate`
+**Parsing Schemas:**
+- `ofxDocumentSchema` - Complete OFX document
+- `ofxHeaderSchema` - OFX file header
+- `ofxResponseSchema` - OFX response body
+- `transactionSchema` - Individual transaction
+- `transactionTypeSchema` - Transaction type enum
+- `transactionListSchema` - List of transactions
+- `bankAccountSchema` - Bank account information
+- `creditCardAccountSchema` - Credit card account information
+- `accountTypeSchema` - Account type enum
+- `balanceSchema` - Balance information
+- `statusSchema` - Status response
+- `financialInstitutionSchema` - Financial institution info
+- `signOnResponseSchema` - Sign-on response
+- `ofxDateSchema` - OFX date with timezone
+
+**Generation Schemas:**
+- `generateHeaderOptionsSchema` - OFX header generation options
+- `generateTransactionInputSchema` - Transaction input for generation
+- `generateBankStatementOptionsSchema` - Bank statement generation options
+- `generateCreditCardStatementOptionsSchema` - Credit card statement generation options
+
+## Security
+
+This library includes several security features to protect against malicious OFX files:
+
+### Prototype Pollution Protection
+
+The SGML parser is protected against prototype pollution attacks. Malicious OFX files attempting to inject `__proto__`, `constructor`, or `prototype` tags are safely ignored, preventing potential remote code execution.
+
+### Input Validation
+
+All parsing functions validate input data against strict Zod schemas, rejecting malformed or invalid OFX data before processing. This prevents:
+- Type confusion attacks
+- Invalid date/number formats
+- Missing required fields
+- Unexpected data structures
+
+### Safe Entity Decoding
+
+HTML entities in OFX text fields are decoded using a whitelist approach, preventing XSS-style attacks through crafted entity sequences
 
 ## Performance