@krutai/excel-comparison 0.0.6

package/AI_REFERENCE.md

@@ -0,0 +1,353 @@
+# AI Reference Guide for @krutai/excel-comparison
+
+This document provides comprehensive context for AI assistants to help users integrate and use the excel-comparison library effectively.
+
+## Library Purpose
+
+The `@krutai/excel-comparison` library compares Excel (.xlsx, .xls) and CSV files, finding:
+- Matching rows between two files
+- Different values in matching rows
+- Unique rows in each file
+- Generates downloadable Excel reports with differences highlighted
+
+## Core Classes and Exports
+
+// Main class - use this for comparing files via API
+import { krutExcelComparison, createComparisonClient } from "@krutai/excel-comparison";
+
+// Create client using convenience factory (recommended)
+const client = krutExcelComparison({
+  serverUrl: "https://api.krut.ai",
+  apiKey: "your-krut-api-key"
+});
+
+// Or using createComparisonClient
+const client2 = createComparisonClient({
+  apiKey: "..."
+});
+
+// API client class
+import { ComparisonApiClient } from "@krutai/excel-comparison";
+
+### Type Exports
+
+```typescript
+import type {
+  ComparisonApiResponse, // Result from API comparison
+  PreviewResponse,        // Preview info for files
+  CompareFilesOptions,    // Configuration options
+  DataRecord,             // Row data as object (used in reporting/engine)
+} from "@krutai/excel-comparison";
+```
+
+## Common Use Cases
+
+### 1. Basic File Comparison (via API)
+
+```typescript
+import { krutExcelComparison } from "@krutai/excel-comparison";
+
+const client = krutExcelComparison({
+  apiKey: "your-api-key"
+});
+
+// For browser - using File objects
+const result = await client.compareFilesFromFileObjects(file1, file2);
+
+// For Node.js/Server - using Buffer
+const result2 = await client.compareFiles(buffer1, "file1.xlsx", buffer2, "file2.xlsx");
+```
+
+### 2. With Comparison Options
+
+```typescript
+const result = await client.compareFilesFromFileObjects(file1, file2, {
+  matchColumn: "Invoice",      // Optional: column to match rows
+  tolerance: 0.01,             // Optional: numeric tolerance
+  caseSensitive: false,         // Optional: case insensitive
+  ignoreColumns: ["Timestamp"]  // Optional: ignore these columns
+});
+```
+
+### 3. Preview Files Before Comparison
+
+```typescript
+// Get preview metadata and suggested match columns
+const preview = await client.previewFiles(file1, file2);
+
+// Returns:
+{
+  success: true,
+  file1: { name: "sales.xlsx", rowCount: 100, columns: [...], sample: [...] },
+  file2: { name: "sales2.xlsx", rowCount: 95, columns: [...], sample: [...] },
+  suggestedMatchColumn: "Invoice"
+}
+```
+
+### 4. Generate Excel Report
+
+```typescript
+import { StyledReporter } from "@krutai/excel-comparison";
+
+const reporter = new StyledReporter({
+  headerColor: "4472C4",      // Blue header
+  differenceColor: "FFCCCC",   // Red for differences
+  matchColor: "CCFFCC",        // Green for matches
+  includeSummary: true
+});
+
+// Transform comparison results for report
+const reportData = result.results.map((r, i) => ({
+  Row: i + 1,
+  Status: r.status,
+  "Match %": `${r.matchPercentage}%`,
+  ...Object.fromEntries(
+    result.allColumns.flatMap(col => [
+      [`File1_${col}`, r.file1Row?.[col] ?? 'N/A'],
+      [`File2_${col}`, r.file2Row?.[col] ?? 'N/A'],
+    ])
+  )
+}));
+
+const report = await reporter.generateReport({
+  data: reportData,
+  summary: result.summary,
+});
+
+// Download as base64
+const downloadUrl = `data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,${report.toString('base64')}`;
+```
+
+### 5. Next.js API Route Integration (Recommended)
+
+```typescript
+// app/api/compare/route.ts
+import { NextRequest, NextResponse } from "next/server";
+import {
+    createComparisonClient,
+    type CompareFilesOptions,
+} from "@krutai/excel-comparison";
+
+const SUPPORTED_EXTENSIONS = new Set(["xlsx", "xls", "csv"]);
+
+function getFileExtension(fileName: string): string {
+    const parts = fileName.toLowerCase().split(".");
+    return parts.length > 1 ? parts[parts.length - 1] : "";
+}
+
+function isSupportedFile(file: File): boolean {
+    return SUPPORTED_EXTENSIONS.has(getFileExtension(file.name));
+}
+
+function getComparisonErrorMessage(raw: string): string {
+    const lower = raw.toLowerCase();
+    if (lower.includes("can't find end of central directory") || lower.includes("zip file")) {
+        return "One of the uploaded files is not a valid .xlsx file archive. For Excel inputs, use a valid .xlsx or .xls file.";
+    }
+    if (lower.includes("request timed out")) {
+        return "Comparison request timed out. Please try smaller files or increase the timeout.";
+    }
+    return raw;
+}
+
+function parseIgnoreColumns(value?: string): string[] | undefined {
+    if (!value?.trim()) return undefined;
+
+    if (value.trim().startsWith("[")) {
+        try {
+            const parsed = JSON.parse(value) as unknown;
+            if (Array.isArray(parsed)) {
+                return parsed
+                    .filter((item): item is string => typeof item === "string")
+                    .map((item) => item.trim())
+                    .filter(Boolean);
+            }
+        } catch { }
+    }
+
+    return value.split(",").map(i => i.trim()).filter(Boolean);
+}
+
+export async function POST(req: NextRequest) {
+    try {
+        const formData = await req.formData();
+        const file1 = formData.get("file1") as File | null;
+        const file2 = formData.get("file2") as File | null;
+        const matchColumn = formData.get("matchColumn") as string | undefined;
+        const ignoreColumns = formData.get("ignoreColumns") as string | undefined;
+        const tolerance = formData.get("tolerance") as string | undefined;
+        const caseSensitive = formData.get("caseSensitive") as string | undefined;
+
+        if (!file1 || !file2) {
+            return NextResponse.json({ error: "Both file1 and file2 are required" }, { status: 400 });
+        }
+
+        if (!isSupportedFile(file1) || !isSupportedFile(file2)) {
+            return NextResponse.json({ error: "Unsupported file type. Use .xlsx, .xls, or .csv files." }, { status: 400 });
+        }
+
+        const options: CompareFilesOptions = {};
+        if (matchColumn?.trim()) options.matchColumn = matchColumn.trim();
+        const parsedIgnore = parseIgnoreColumns(ignoreColumns);
+        if (parsedIgnore) options.ignoreColumns = parsedIgnore;
+        if (tolerance?.trim()) options.tolerance = Number(tolerance);
+        if (caseSensitive !== undefined) options.caseSensitive = caseSensitive === "true";
+
+        const client = createComparisonClient({
+            apiKey: process.env.KRUTAI_API_KEY || '',
+            serverUrl: process.env.KRUTAI_SERVER_URL || "http://localhost:8000",
+            validateOnInit: false,
+        });
+
+        const apiResponse = await client.compareFilesFromFileObjects(file1, file2, options);
+
+        if (!apiResponse.success || !apiResponse.result) {
+            return NextResponse.json({ error: apiResponse.error ?? "Comparison failed" }, { status: 500 });
+        }
+
+        return NextResponse.json({
+            success: true,
+            result: apiResponse.result,
+            results: [],
+            allColumns: [...new Set([
+                ...(apiResponse.result.metadata.file1Columns ?? []),
+                ...(apiResponse.result.metadata.file2Columns ?? []),
+            ])],
+            columnsWithDiffs: [],
+            downloadUrl: apiResponse.downloadUrl,
+            fileName: apiResponse.fileName,
+        });
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : "Comparison failed";
+        return NextResponse.json({ error: getComparisonErrorMessage(msg) }, { status: 500 });
+    }
+}
+```
+
+### 6. Express.js Integration
+
+```typescript
+import express from 'express';
+import multer from 'multer';
+import { krutExcelComparison } from "@krutai/excel-comparison";
+
+const app = express();
+const upload = multer({ storage: multer.memoryStorage() });
+const client = krutExcelComparison({ apiKey: process.env.KRUTAI_API_KEY });
+
+app.post('/compare', upload.fields([
+  { name: 'file1', maxCount: 1 },
+  { name: 'file2', maxCount: 1 }
+]), async (req, res) => {
+  const files = req.files as { [fieldname: string]: Express.Multer.File[] };
+  
+  const result = await client.compareFiles(
+    files.file1[0].buffer, files.file1[0].originalname,
+    files.file2[0].buffer, files.file2[0].originalname,
+    {
+      matchColumn: req.body.matchColumn,
+      tolerance: req.body.tolerance ? parseFloat(req.body.tolerance) : undefined
+    }
+  );
+
+  res.json(result);
+});
+```
+
+## ComparisonApiResponse Structure
+
+```typescript
+{
+  success: boolean,           // true if comparison succeeded
+  result?: {
+    summary: {
+      totalRows: number,      // Total rows compared
+      matchesFound: number,   // Rows with all values matching
+      differencesFound: number,// Rows with differences
+      uniqueToFile1: number,  // Rows only in first file
+      uniqueToFile2: number,  // Rows only in second file
+      status: 'SUCCESS' | 'PARTIAL' | 'NO_MATCH'
+    },
+    matchColumn: string,
+    metadata: {
+      file1Name: string,
+      file1Columns: string[],
+      file1RowCount: number,
+      file2Name: string,
+      file2Columns: string[],
+      file2RowCount: number
+    }
+  },
+  downloadUrl?: string,       // URL to download the Excel report
+  fileName?: string,          // Suggested file name for download
+  error?: string              // Error message if success is false
+}
+```
+
+## Key Behaviors
+
+### API Comparison
+- The package now acts as a client for a backend comparison service.
+- It offloads heavy Excel processing and comparison logic to the server.
+- It returns a summary of results and a link to a professionally styled Excel report.
+
+### Column Matching
+- If `matchColumn` is provided, uses that column to match rows
+- If not provided, auto-detects: prioritizes id, invoice, gstin, number, name, code
+- Falls back to first column if no match found
+
+### Value Comparison (Backend)
+- Done on the server side using intelligent algorithms.
+- Supports fuzzy matching, numeric tolerance, and case sensitivity.
+
+## Common Integration Patterns
+
+### Pattern 1: Basic Comparison
+```typescript
+const client = krutExcelComparison({ apiKey: "..." });
+const result = await client.compareFilesFromFileObjects(f1, f2);
+```
+
+### Pattern 2: Comparison with Options
+```typescript
+const result = await client.compareFilesFromFileObjects(f1, f2, {
+  matchColumn: "Invoice No",
+  tolerance: 0.001,
+  caseSensitive: false
+});
+```
+
+## Error Handling
+
+```typescript
+try {
+  const result = await client.compareFilesFromFileObjects(file1, file2);
+} catch (error) {
+  if (error.message.includes("Request timed out")) {
+    // Handle timeout
+  } else {
+    // Generic error
+  }
+}
+```
+
+## Package Dependencies
+
+The library is lightweight and depends on:
+- `exceljs` - For local reporting (optional)
+
+## Environment Notes
+
+- Works in Node.js (v14+) and modern browsers
+- Uses dynamic imports for xlsx to support Next.js
+- File objects from HTML inputs work in browser
+- Buffer objects work in Node.js
+
+## Contributing Guidelines for AI Assistants
+
+When helping users with this library:
+
+1. Use `krutExcelComparison` or `ComparisonApiClient`.
+2. Emphasize that comparison is done via API.
+3. Show Next.js API route as the primary integration example.
+4. Note that heavy parsing (xlsx) is done on the backend.

package/README.md

@@ -0,0 +1,161 @@
+# @krutai/excel-comparison
+
+A powerful library for comparing Excel and CSV files by leveraging Backend APIs for high-performance processing.
+
+## Features
+
+- **API-Driven Comparison**: Offloads heavy Excel processing to a dedicated comparison service.
+- **Smart Column Matching**: Automatically detects matching columns between files on the server.
+- **Detailed Summaries**: Get row counts, matches, and differences instantly.
+- **Professional Reports**: Automatically generates styled Excel reports with highlighted differences.
+- **Next.js & Serverless Ready**: Optimized for modern web frameworks with zero heavy dependencies like `xlsx`.
+
+## Installation
+
+```bash
+npm install @krutai/excel-comparison
+```
+
+## Quick Start
+
+### Basic Usage (Server-side)
+
+```typescript
+import { krutExcelComparison } from "@krutai/excel-comparison";
+
+// Create client
+const client = krutExcelComparison({
+  apiKey: process.env.KRUTAI_API_KEY,
+  serverUrl: process.env.KRUTAI_SERVER_URL || "https://api.krut.ai"
+});
+
+// Compare files using buffers
+const result = await client.compareFiles(
+  file1Buffer, "file1.xlsx",
+  file2Buffer, "file2.xlsx",
+  { matchColumn: "Invoice" }
+);
+
+if (result.success) {
+  console.log('Report URL:', result.downloadUrl);
+}
+```
+
+### Next.js API Route Integration
+
+This is the recommended way to use the library in a Next.js application.
+
+```typescript
+// app/api/compare/route.ts
+import { NextRequest, NextResponse } from "next/server";
+import {
+    createComparisonClient,
+    type CompareFilesOptions,
+} from "@krutai/excel-comparison";
+
+const SUPPORTED_EXTENSIONS = new Set(["xlsx", "xls", "csv"]);
+
+function getFileExtension(fileName: string): string {
+    const parts = fileName.toLowerCase().split(".");
+    return parts.length > 1 ? parts[parts.length - 1] : "";
+}
+
+function isSupportedFile(file: File): boolean {
+    return SUPPORTED_EXTENSIONS.has(getFileExtension(file.name));
+}
+
+function parseIgnoreColumns(value?: string): string[] | undefined {
+    if (!value?.trim()) return undefined;
+    if (value.trim().startsWith("[")) {
+        try {
+            const parsed = JSON.parse(value);
+            if (Array.isArray(parsed)) return parsed.filter(i => typeof i === "string");
+        } catch { }
+    }
+    return value.split(",").map(i => i.trim()).filter(Boolean);
+}
+
+export async function POST(req: NextRequest) {
+    try {
+        const formData = await req.formData();
+        const file1 = formData.get("file1") as File | null;
+        const file2 = formData.get("file2") as File | null;
+        const matchColumn = formData.get("matchColumn") as string | undefined;
+
+        if (!file1 || !file2) {
+            return NextResponse.json({ error: "Both file1 and file2 are required" }, { status: 400 });
+        }
+
+        const client = createComparisonClient({
+            apiKey: process.env.KRUTAI_API_KEY || '',
+            serverUrl: process.env.KRUTAI_SERVER_URL || "http://localhost:8000"
+        });
+
+        const apiResponse = await client.compareFilesFromFileObjects(file1, file2, {
+            matchColumn: matchColumn?.trim()
+        });
+
+        return NextResponse.json(apiResponse);
+    } catch (err: unknown) {
+        return NextResponse.json({ error: "Comparison failed" }, { status: 500 });
+    }
+}
+```
+
+## API Reference
+
+### krutExcelComparison(config)
+
+Convenience factory to create a `ComparisonApiClient`.
+
+### ComparisonApiClient
+
+#### `compareFiles(buffer1, name1, buffer2, name2, options)`
+Compare files using Node.js Buffers.
+
+#### `compareFilesFromFileObjects(file1, file2, options)`
+Compare files using Web File objects (useful in Browser or Next.js).
+
+#### `previewFiles(file1, file2)`
+Get a preview of the files (columns, row counts, and sample data) before committing to a full comparison.
+
+### Types
+
+#### ComparisonApiResponse
+```typescript
+interface ComparisonApiResponse {
+  success: boolean;
+  result?: {
+    summary: {
+      totalRows: number;
+      matchesFound: number;
+      differencesFound: number;
+      uniqueToFile1: number;
+      uniqueToFile2: number;
+      status: 'SUCCESS' | 'PARTIAL' | 'NO_MATCH';
+    };
+    matchColumn: string;
+    metadata: {
+      file1Name: string;
+      file1Columns: string[];
+      file1RowCount: number;
+      file2Name: string;
+      file2Columns: string[];
+      file2RowCount: number;
+    };
+  };
+  downloadUrl?: string; // Link to the Excel report
+  fileName?: string;
+  error?: string;
+}
+```
+
+## Supported File Formats
+
+- `.xlsx` (Excel 2007+)
+- `.xls` (Excel 97-2003)
+- `.csv` (Comma Separated Values)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,187 @@
+interface ComparisonClientConfig {
+    /**
+     * KrutAI API key.
+     * Optional: defaults to process.env.KRUTAI_API_KEY
+     */
+    apiKey?: string;
+    /**
+     * Base URL of your deployed comparison backend server.
+     * @default "http://localhost:8000"
+     * @example "https://api.krut.ai"
+     */
+    serverUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 60000
+     */
+    timeout?: number;
+    /**
+     * Whether to validate the API key against the server on initialization.
+     * @default true
+     */
+    validateOnInit?: boolean;
+}
+interface CompareFilesOptions {
+    matchColumn?: string;
+    ignoreColumns?: string[];
+    tolerance?: number;
+    caseSensitive?: boolean;
+}
+interface FilePreview {
+    name: string;
+    rowCount: number;
+    columns: string[];
+    sample: Record<string, unknown>[];
+}
+interface PreviewResponse {
+    success: boolean;
+    file1?: FilePreview;
+    file2?: FilePreview;
+    suggestedMatchColumn?: string;
+    error?: string;
+}
+interface ComparisonApiResponse {
+    success: boolean;
+    result?: {
+        summary: {
+            totalRows: number;
+            matchesFound: number;
+            differencesFound: number;
+            uniqueToFile1: number;
+            uniqueToFile2: number;
+            status: 'SUCCESS' | 'PARTIAL' | 'NO_MATCH';
+        };
+        matchColumn: string;
+        metadata: {
+            file1Name: string;
+            file1Columns: string[];
+            file1RowCount: number;
+            file2Name: string;
+            file2Columns: string[];
+            file2RowCount: number;
+        };
+    };
+    downloadUrl?: string;
+    fileName?: string;
+    error?: string;
+}
+declare class ComparisonApiClient {
+    private serverUrl;
+    private apiKey?;
+    private timeout;
+    private initialized;
+    private validateOnInit;
+    private initializationPromise;
+    constructor(config: ComparisonClientConfig);
+    /**
+     * Initialize the client.
+     * Validates the API key against the server if validateOnInit is true.
+     * @throws {Error} If validation fails or API key is missing
+     */
+    initialize(): Promise<void>;
+    private getHeaders;
+    private request;
+    compareFiles(file1Buffer: Buffer, file1Name: string, file2Buffer: Buffer, file2Name: string, compareOptions?: CompareFilesOptions): Promise<ComparisonApiResponse>;
+    compareFilesFromFileObjects(file1: File, file2: File, compareOptions?: CompareFilesOptions): Promise<ComparisonApiResponse>;
+    previewFiles(file1: File, file2: File): Promise<PreviewResponse>;
+    previewFilesFromBuffers(file1Buffer: Buffer, file1Name: string, file2Buffer: Buffer, file2Name: string): Promise<PreviewResponse>;
+}
+declare function createComparisonClient(config: ComparisonClientConfig): ComparisonApiClient;
+
+interface DataRecord {
+    [key: string]: unknown;
+}
+interface ComparisonResult {
+    data: DataRecord[];
+    summary: {
+        totalRows: number;
+        differencesFound: number;
+        matchesFound: number;
+        status: 'SUCCESS' | 'PARTIAL' | 'NO_MATCH';
+    };
+    metadata?: {
+        file1Columns?: string[];
+        file2Columns?: string[];
+        executionTime?: number;
+    };
+}
+interface ExcelLoaderOptions {
+    sheetIndex?: number;
+    sheetName?: string;
+    headerRow?: number;
+    skipRows?: number;
+    sampleRows?: number;
+}
+interface LoaderOptions {
+    sheetName?: string;
+    headerRow?: number;
+    skipRows?: number;
+}
+interface ReporterOptions {
+    headerColor?: string;
+    differenceColor?: string;
+    matchColor?: string;
+    sheetName?: string;
+    includeSummary?: boolean;
+}
+interface EngineOptions {
+    timeout?: number;
+    maxMemory?: number;
+}
+interface CodeGenerationResult {
+    code: string;
+    humanExplanation: string[];
+    constants?: Record<string, unknown>;
+}
+interface ComparisonRequest {
+    file1Data: DataRecord[];
+    file2Data: DataRecord[];
+    file1Columns?: string[];
+    file2Columns?: string[];
+    file1Sample?: DataRecord[];
+    file2Sample?: DataRecord[];
+    prompt?: string;
+}
+interface ExcelSchema {
+    headers: string[];
+    rowCount: number;
+    columnCount: number;
+    sample: DataRecord[];
+    data: DataRecord[];
+}
+
+declare class StyledReporter {
+    private options;
+    constructor(options?: ReporterOptions);
+    generateReport(result: ComparisonResult, _file1Columns?: string[], _file2Columns?: string[]): Promise<Buffer>;
+    private addSummarySheet;
+    private addResultSheet;
+    private formatValue;
+    generateDetailedReport(result: ComparisonResult, file1Columns?: string[], file2Columns?: string[]): Promise<Buffer>;
+    private addDataSheet;
+}
+
+interface ExcelDataFrame {
+    headers: string[];
+    data: DataRecord[];
+    rowCount: number;
+    columnCount: number;
+    sample: DataRecord[];
+}
+declare class DataLoader {
+    static loadFromBuffer(buffer: Buffer, fileName: string, options?: ExcelLoaderOptions): Promise<ExcelDataFrame>;
+    static getColumnNames(data: DataRecord[]): string[];
+    static getSampleData(data: DataRecord[], count?: number): DataRecord[];
+}
+
+/**
+ * krutExcelComparison — convenience factory.
+ *
+ * Creates a `ComparisonApiClient` instance configured to call the Krut comparison server.
+ *
+ * @param config - Client configuration (apiKey and serverUrl)
+ * @returns A `ComparisonApiClient` instance
+ */
+declare function krutExcelComparison(config: ComparisonClientConfig): ComparisonApiClient;
+
+export { type FilePreview as ApiFilePreview, type CodeGenerationResult, type CompareFilesOptions, ComparisonApiClient, type ComparisonApiResponse, type ComparisonClientConfig, type ComparisonRequest, type ComparisonResult, DataLoader, type DataRecord, type EngineOptions, type ExcelLoaderOptions, type ExcelSchema, type LoaderOptions, type PreviewResponse, type ReporterOptions, StyledReporter, createComparisonClient, krutExcelComparison };