nosible 0.1.5

package/src/utils/browser.ts

@@ -0,0 +1,21 @@
+/**
+ * Downloads a blob in the browser by creating a temporary link and triggering a download
+ * @param data - The data string to download
+ * @param mimeType - The MIME type of the file (e.g., 'application/json', 'text/csv')
+ * @param fileName - The name of the file to download
+ */
+export const downloadBlob = (
+  data: string,
+  mimeType: string,
+  fileName: string
+): void => {
+  const blob = new Blob([data], {type: mimeType});
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = fileName;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+};

package/src/utils/fernet.ts

@@ -0,0 +1,47 @@
+import {createDecipheriv, createHmac, timingSafeEqual} from "crypto";
+
+/**
+ * Decrypt data using Fernet-compatible decryption
+ * Fernet uses: version (1 byte) | timestamp (8 bytes) | iv (16 bytes) | ciphertext | hmac (32 bytes)
+ */
+export const fernetDecrypt = (token: Buffer, key: string): Buffer => {
+  try {
+    // Decode the base64 key and derive encryption and signing keys
+    const keyBuffer = Buffer.from(key, "base64");
+    const signingKey = keyBuffer.subarray(0, 16);
+    const encryptionKey = keyBuffer.subarray(16, 32);
+
+    // Verify HMAC (last 32 bytes)
+    const hmac = token.subarray(token.length - 32);
+    const payload = token.subarray(0, token.length - 32);
+
+    const expectedHmac = createHmac("sha256", signingKey)
+      .update(payload)
+      .digest();
+
+    if (!timingSafeEqual(hmac, expectedHmac)) {
+      throw new Error("HMAC verification failed");
+    }
+
+    // Extract components
+    const version = payload[0];
+    if (version !== 0x80) {
+      throw new Error(`Unsupported Fernet version: ${version}`);
+    }
+
+    const iv = payload.subarray(9, 25); // Skip version (1) + timestamp (8)
+    const ciphertext = payload.subarray(25);
+
+    // Decrypt using AES-128-CBC
+    const decipher = createDecipheriv("aes-128-cbc", encryptionKey, iv);
+    const decrypted = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final(),
+    ]);
+
+    return decrypted;
+  } catch (error) {
+    console.error("Error decrypting data:", error);
+    throw error;
+  }
+};

package/src/utils/file.test.ts

@@ -0,0 +1,81 @@
+import {describe, test, expect, afterEach} from "bun:test";
+import {importCsv, exportCsv} from "./file";
+import {writeFile, unlink} from "node:fs/promises";
+
+describe("importCsv", () => {
+  const testFiles: string[] = [];
+
+  afterEach(async () => {
+    // Clean up test files
+    for (const file of testFiles) {
+      try {
+        await unlink(file);
+      } catch (error) {
+        // Ignore errors if file doesn't exist
+      }
+    }
+    testFiles.length = 0; // Clear the array
+  });
+
+  test("should import CSV data from file path", async () => {
+    const csvContent = `name,age,city
+John Doe,30,New York
+Jane Smith,25,Los Angeles
+Bob Johnson,35,Chicago`;
+
+    const testFilePath = "/tmp/test-import.csv";
+    testFiles.push(testFilePath);
+    
+    await writeFile(testFilePath, csvContent);
+
+    const result = await importCsv({filePath: testFilePath});
+
+    expect(result).toEqual([
+      {name: "John Doe", age: 30, city: "New York"},
+      {name: "Jane Smith", age: 25, city: "Los Angeles"},
+      {name: "Bob Johnson", age: 35, city: "Chicago"},
+    ]);
+  });
+
+  test("should handle empty CSV file", async () => {
+    const testFilePath = "/tmp/test-empty.csv";
+    testFiles.push(testFilePath);
+    
+    await writeFile(testFilePath, "");
+
+    const result = await importCsv({filePath: testFilePath});
+
+    expect(result).toEqual([]);
+  });
+
+  test("should handle CSV with only headers", async () => {
+    const csvContent = "name,age,city";
+    const testFilePath = "/tmp/test-headers-only.csv";
+    testFiles.push(testFilePath);
+    
+    await writeFile(testFilePath, csvContent);
+
+    const result = await importCsv({filePath: testFilePath});
+
+    expect(result).toEqual([]);
+  });
+
+  test("should round trip CSV data", async () => {
+    const testData = [
+      {name: "Alice", age: 28, city: "Boston"},
+      {name: "Charlie", age: 32, city: "Seattle"},
+    ];
+
+    const exportPath = "/tmp/test-roundtrip.csv";
+    testFiles.push(exportPath);
+
+    // Export to CSV
+    await exportCsv(testData, exportPath);
+
+    // Import from CSV
+    const importedData = await importCsv({filePath: exportPath});
+
+    // Data should match (note: papaparse converts numbers to numbers)
+    expect(importedData).toEqual(testData);
+  });
+});

package/src/utils/file.ts

@@ -0,0 +1,195 @@
+import {isBrowser} from ".";
+import {downloadBlob} from "./browser";
+import Papa from "papaparse";
+
+/**
+ * Exports data to a JSON file
+ * @param data - The data to export
+ * @param outputPath - Path to write the JSON file (or filename for browser)
+ */
+export const exportJson = async (
+  data: any,
+  outputPath: string
+): Promise<void> => {
+  try {
+    if (isBrowser()) {
+      // Extract filename from outputPath or use default
+      const filename = outputPath.split("/").pop() || "export.json";
+      const jsonString = JSON.stringify(data);
+      const finalFilename = filename.endsWith(".json")
+        ? filename
+        : `${filename}.json`;
+
+      downloadBlob(jsonString, "application/json", finalFilename);
+    } else {
+      const {writeFile} = await import("node:fs/promises");
+      await writeFile(outputPath, JSON.stringify(data));
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to write JSON: ${errorMessage}`);
+  }
+};
+
+/**
+ * Imports JSON data from a file
+ * @param options - Either {filePath: string} for server-side or {file: File} for browser-side
+ * @returns Parsed JSON data
+ */
+export const importJson = async (
+  options: {filePath: string} | {file: File}
+): Promise<any> => {
+  try {
+    if ("file" in options) {
+      // Browser-side: read from File object
+      const text = await options.file.text();
+      return JSON.parse(text);
+    } else {
+      // Server-side: read from file path
+      if (isBrowser()) {
+        throw new Error(
+          "File path import is not supported in browser. Use {file: File} instead."
+        );
+      }
+      const {readFile} = await import("node:fs/promises");
+      const data = await readFile(options.filePath, "utf-8");
+      return JSON.parse(data);
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to read JSON: ${errorMessage}`);
+  }
+};
+
+/**
+ * Imports CSV data from a file
+ * @param options - Either {filePath: string} for server-side or {file: File} for browser-side
+ * @returns Parsed CSV data as an array of objects
+ */
+export const importCsv = async (
+  options: {filePath: string} | {file: File}
+): Promise<any[]> => {
+  try {
+    let csvText: string;
+
+    if ("file" in options) {
+      // Browser-side: read from File object
+      csvText = await options.file.text();
+    } else {
+      // Server-side: read from file path
+      if (isBrowser()) {
+        throw new Error(
+          "File path import is not supported in browser. Use {file: File} instead."
+        );
+      }
+      const {readFile} = await import("node:fs/promises");
+      csvText = await readFile(options.filePath, "utf-8");
+    }
+
+    // Handle empty CSV
+    if (!csvText.trim()) {
+      return [];
+    }
+
+    // Parse CSV using papaparse
+    const result = Papa.parse(csvText, {
+      header: true,
+      skipEmptyLines: true,
+      dynamicTyping: true,
+    });
+
+    // Filter out delimiter detection errors for empty/whitespace-only content
+    const significantErrors = result.errors.filter(
+      (error) =>
+        !error.message.includes("Unable to auto-detect delimiting character")
+    );
+
+    if (significantErrors.length > 0) {
+      const errorMessages = significantErrors
+        .map((err) => err.message)
+        .join(", ");
+      throw new Error(`CSV parsing errors: ${errorMessages}`);
+    }
+
+    return result.data as any[];
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to read CSV: ${errorMessage}`);
+  }
+};
+
+/**
+ * Exports data to an NDJSON file (newline-delimited JSON)
+ * @param data - Array of objects to export
+ * @param outputPath - Path to write the NDJSON file (or filename for browser)
+ */
+export const exportNdjson = async (
+  data: any[],
+  outputPath: string
+): Promise<void> => {
+  try {
+    if (isBrowser()) {
+      // Extract filename from outputPath or use default
+      const filename = outputPath.split("/").pop() || "export.ndjson";
+
+      // Create NDJSON string (one JSON object per line)
+      const ndjsonString = data.map((item) => JSON.stringify(item)).join("\n");
+
+      const finalFilename = filename.endsWith(".ndjson")
+        ? filename
+        : `${filename}.ndjson`;
+
+      downloadBlob(ndjsonString, "application/x-ndjson", finalFilename);
+    } else {
+      const pl = await import("nodejs-polars");
+      const df = pl.DataFrame(data);
+      await df.writeJSON(outputPath, {format: "lines"});
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to write NDJSON: ${errorMessage}`);
+  }
+};
+
+/**
+ * Exports data to a CSV file
+ * @param data - Array of objects to export
+ * @param outputPath - Path to write the CSV file (or filename for browser)
+ */
+export const exportCsv = async (
+  data: any[],
+  outputPath: string
+): Promise<void> => {
+  try {
+    // Validate input
+    if (!Array.isArray(data) || data.length === 0) {
+      throw new Error("Data must be a non-empty array");
+    }
+
+    if (!outputPath || typeof outputPath !== "string") {
+      throw new Error("Output path must be a non-empty string");
+    }
+
+    // Use papaparse to convert data to CSV
+    const csvString = Papa.unparse(data, {
+      header: true,
+      newline: "\n",
+    });
+
+    if (isBrowser()) {
+      // Extract filename from outputPath or use default
+      const filename = outputPath.split("/").pop() || "export.csv";
+      const finalFilename = filename.endsWith(".csv")
+        ? filename
+        : `${filename}.csv`;
+
+      downloadBlob(csvString, "text/csv", finalFilename);
+    } else {
+      const {writeFile} = await import("node:fs/promises");
+      await writeFile(outputPath, csvString);
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to write CSV: ${errorMessage}`);
+  }
+};

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if the code is running in a browser environment
+ * @returns {boolean} True if running in a browser, false otherwise
+ */
+export const isBrowser = () => {
+  return typeof window !== "undefined";
+};

package/src/utils/llm.test.ts

@@ -0,0 +1,279 @@
+import {describe, test, expect, beforeAll, mock} from "bun:test";
+import {getSentiment, generateExpansions} from "./llm";
+import OpenAI from "openai";
+
+// Helper to create a mock LLM client
+const createMockLLMClient = (mockResponse: string): OpenAI => {
+  return {
+    chat: {
+      completions: {
+        create: mock(async () => ({
+          choices: [
+            {
+              message: {
+                content: mockResponse,
+              },
+            },
+          ],
+        })),
+      },
+    },
+  } as unknown as OpenAI;
+};
+
+describe("getSentiment", () => {
+  let realLlmClient: OpenAI;
+
+  beforeAll(() => {
+    const llmApiKeyToUse = process.env.LLM_API_KEY;
+    if (!llmApiKeyToUse) {
+      throw new Error("LLM_API_KEY environment variable is required for tests");
+    }
+
+    realLlmClient = new OpenAI({
+      apiKey: llmApiKeyToUse,
+      baseURL: "https://openrouter.ai/api/v1",
+    });
+  });
+
+  // Integration test - uses real API
+  test("should return positive sentiment for positive text (integration)", async () => {
+    const positiveText =
+      "I absolutely love this product! It's amazing and works perfectly. Best purchase ever!";
+
+    const score = await getSentiment({
+      text: positiveText,
+      llmClient: realLlmClient,
+    });
+
+    expect(score).toBeGreaterThanOrEqual(0.5);
+    expect(score).toBeLessThanOrEqual(1.0);
+  }, 30000);
+
+  // Mocked tests
+  test("should return negative sentiment for negative text", async () => {
+    const mockClient = createMockLLMClient("-0.85");
+    const negativeText =
+      "This is terrible. I hate it and it completely failed. Worst experience ever.";
+
+    const score = await getSentiment({
+      text: negativeText,
+      llmClient: mockClient,
+    });
+
+    expect(score).toBe(-0.85);
+    expect(score).toBeGreaterThanOrEqual(-1.0);
+    expect(score).toBeLessThanOrEqual(-0.5);
+  });
+
+  test("should return neutral sentiment for neutral text", async () => {
+    const mockClient = createMockLLMClient("0.1");
+    const neutralText =
+      "The product is a widget that performs basic functions. It has standard features.";
+
+    const score = await getSentiment({
+      text: neutralText,
+      llmClient: mockClient,
+    });
+
+    expect(score).toBe(0.1);
+    expect(score).toBeGreaterThanOrEqual(-0.5);
+    expect(score).toBeLessThanOrEqual(0.5);
+  });
+
+  test("should throw error when no client is provided", async () => {
+    const text = "Some test text";
+
+    await expect(
+      getSentiment({
+        text,
+        llmClient: undefined,
+      })
+    ).rejects.toThrow(
+      "A OpenAI client instance must be provided as 'llmClient'."
+    );
+  });
+
+  test("should handle empty string", async () => {
+    const mockClient = createMockLLMClient("0.5");
+    const text = "";
+
+    await expect(
+      getSentiment({
+        text,
+        llmClient: mockClient,
+      })
+    ).rejects.toThrow("Text must not be empty or whitespace.");
+  });
+
+  test("should parse valid float responses", async () => {
+    const mockClient = createMockLLMClient("0.75");
+    const text = "This is reasonably good";
+
+    const score = await getSentiment({
+      text,
+      llmClient: mockClient,
+    });
+
+    expect(typeof score).toBe("number");
+    expect(Number.isFinite(score)).toBe(true);
+    expect(score).toBe(0.75);
+  });
+
+  test("should throw error for invalid sentiment response", async () => {
+    const mockClient = createMockLLMClient("not a number");
+    const text = "Some text";
+
+    await expect(
+      getSentiment({
+        text,
+        llmClient: mockClient,
+      })
+    ).rejects.toThrow("Sentiment response is not a float");
+  });
+
+  test("should throw error for out of range sentiment", async () => {
+    const mockClient = createMockLLMClient("1.5");
+    const text = "Some text";
+
+    await expect(
+      getSentiment({
+        text,
+        llmClient: mockClient,
+      })
+    ).rejects.toThrow("Sentiment 1.5 outside valid range [-1.0, 1.0]");
+  });
+});
+
+describe("generateExpansions", () => {
+  let realLlmClient: OpenAI;
+
+  beforeAll(() => {
+    const llmApiKeyToUse = process.env.LLM_API_KEY;
+    if (!llmApiKeyToUse) {
+      throw new Error("LLM_API_KEY environment variable is required for tests");
+    }
+
+    realLlmClient = new OpenAI({
+      apiKey: llmApiKeyToUse,
+      baseURL: "https://openrouter.ai/api/v1",
+    });
+  });
+
+  // Integration test - uses real API
+  test("should return 10 expansion strings for a typical question (integration)", async () => {
+    const question = "What are effective treatments for type 2 diabetes?";
+
+    const expansions = await generateExpansions({
+      question,
+      llmClient: realLlmClient,
+    });
+
+    expect(Array.isArray(expansions)).toBe(true);
+    expect(expansions.length).toBe(10);
+    expect(expansions.every((q) => typeof q === "string")).toBe(true);
+  }, 30000);
+
+  // Mocked tests
+  test("should parse valid JSON array response", async () => {
+    const mockExpansions = [
+      "What are the best treatments for managing type 2 diabetes?",
+      "How can type 2 diabetes be effectively treated?",
+      "What medications are used to treat type 2 diabetes?",
+      "What are the recommended therapies for type 2 diabetes?",
+      "How to control type 2 diabetes with treatment?",
+      "What treatment options exist for type 2 diabetes patients?",
+      "How is type 2 diabetes managed medically?",
+      "What are effective interventions for type 2 diabetes?",
+      "Which treatments work best for type 2 diabetes?",
+      "What are proven methods to treat type 2 diabetes?",
+    ];
+    const mockClient = createMockLLMClient(JSON.stringify(mockExpansions));
+    const question = "What are effective treatments for type 2 diabetes?";
+
+    const expansions = await generateExpansions({
+      question,
+      llmClient: mockClient,
+    });
+
+    expect(Array.isArray(expansions)).toBe(true);
+    expect(expansions.length).toBe(10);
+    expect(expansions).toEqual(mockExpansions);
+  });
+
+  test("should handle JSON wrapped in markdown code blocks", async () => {
+    const mockExpansions = [
+      "Question 1",
+      "Question 2",
+      "Question 3",
+      "Question 4",
+      "Question 5",
+      "Question 6",
+      "Question 7",
+      "Question 8",
+      "Question 9",
+      "Question 10",
+    ];
+    const mockClient = createMockLLMClient(
+      `\`\`\`json\n${JSON.stringify(mockExpansions)}\n\`\`\``
+    );
+    const question = "Test question";
+
+    const expansions = await generateExpansions({
+      question,
+      llmClient: mockClient,
+    });
+
+    expect(expansions).toEqual(mockExpansions);
+  });
+
+  test("should throw error when no client is provided", async () => {
+    const question = "What are the symptoms of seasonal allergies?";
+
+    await expect(
+      generateExpansions({
+        question,
+        llmClient: undefined,
+      })
+    ).rejects.toThrow(
+      "A OpenAI client instance must be provided as 'llmClient'."
+    );
+  });
+
+  test("should throw on empty question", async () => {
+    const mockClient = createMockLLMClient("[]");
+
+    await expect(
+      generateExpansions({
+        question: "",
+        llmClient: mockClient,
+      })
+    ).rejects.toThrow("Question must not be empty or whitespace.");
+  });
+
+  test("should throw error for invalid JSON response", async () => {
+    const mockClient = createMockLLMClient("not valid json");
+    const question = "Test question";
+
+    await expect(
+      generateExpansions({
+        question,
+        llmClient: mockClient,
+      })
+    ).rejects.toThrow("OpenRouter response was not valid JSON");
+  });
+
+  test("should throw error for invalid array length", async () => {
+    const mockClient = createMockLLMClient(
+      JSON.stringify(["Question 1", "Question 2"])
+    );
+    const question = "Test question";
+
+    await expect(
+      generateExpansions({
+        question,
+        llmClient: mockClient,
+      })
+    ).rejects.toThrow("Invalid response");
+  });
+});