@f-o-t/ofx 2.0.0 → 2.2.0

package/README.md

@@ -11,11 +11,17 @@ bun add @fot/ofx
 ## Quick Start
 
 ```typescript
-import { parse, getTransactions, getBalance } from "@fot/ofx";
+import { parse, parseBuffer, getTransactions, getBalance } from "@fot/ofx";
+import { readFileSync } from "node:fs";
 
-const ofxContent = fs.readFileSync("statement.ofx", "utf-8");
+// For files with known UTF-8 encoding
+const ofxContent = readFileSync("statement.ofx", "utf-8");
 const result = parse(ofxContent);
 
+// For files with unknown encoding (recommended for Brazilian banks)
+const buffer = readFileSync("statement.ofx");
+const result = parseBuffer(new Uint8Array(buffer));
+
 if (result.success) {
   const transactions = getTransactions(result.data);
   const balances = getBalance(result.data);
@@ -56,6 +62,31 @@ try {
 }
 ```
 
+#### `parseBuffer(buffer: Uint8Array): ParseResult<OFXDocument>`
+
+Parses an OFX file from binary data with automatic encoding detection. This is the recommended method for files from Brazilian banks or any file with non-UTF-8 encoding.
+
+```typescript
+import { readFileSync } from "node:fs";
+
+const buffer = readFileSync("extrato.ofx");
+const result = parseBuffer(new Uint8Array(buffer));
+
+if (result.success) {
+  // Portuguese characters like "Cartão" are correctly preserved
+  console.log(result.data);
+}
+```
+
+#### `parseBufferOrThrow(buffer: Uint8Array): OFXDocument`
+
+Parses an OFX file from binary data and throws on validation errors.
+
+```typescript
+const buffer = readFileSync("extrato.ofx");
+const doc = parseBufferOrThrow(new Uint8Array(buffer));
+```
+
 ### Extraction Functions
 
 #### `getTransactions(document: OFXDocument): OFXTransaction[]`
@@ -229,6 +260,95 @@ 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.
+
+### Supported Charsets
+
+| OFX CHARSET Value | Encoding Used |
+| ----------------- | ------------- |
+| `1252`, `WINDOWS-1252`, `CP1252` | windows-1252 |
+| `8859-1`, `ISO-8859-1`, `LATIN1`, `LATIN-1` | iso-8859-1 |
+| `UTF-8`, `UTF8`, `NONE`, (empty) | utf-8 |
+
+### UTF-8 Auto-Detection
+
+Some OFX files declare `CHARSET:1252` but are actually encoded as UTF-8. The library automatically detects this and uses UTF-8 when appropriate, ensuring characters like `Transação` are correctly preserved.
+
+### Best Practices
+
+For files from Brazilian banks or any file with unknown encoding, use `parseBuffer()` instead of `parse()`:
+
+```typescript
+import { parseBuffer } from "@fot/ofx";
+import { readFileSync } from "node:fs";
+
+// Correct: Read as binary, let the library detect encoding
+const buffer = readFileSync("extrato.ofx");
+const result = parseBuffer(new Uint8Array(buffer));
+
+// Avoid: Reading as UTF-8 string may corrupt Windows-1252 characters
+// const content = readFileSync("extrato.ofx", "utf-8");
+// const result = parse(content);
+```
+
 ## Types
 
 ### OFXTransaction
@@ -238,7 +358,7 @@ interface OFXTransaction {
   TRNTYPE: OFXTransactionType;
   DTPOSTED: OFXDate;
   TRNAMT: number;
-  FITID: string;
+  FITID?: string; // Optional, auto-generated if missing
   NAME?: string;
   MEMO?: string;
   CHECKNUM?: string;