goldenmatch 0.1.0

package/src/node/connectors/file.ts

@@ -0,0 +1,350 @@
+/**
+ * file.ts -- CSV/JSON/JSONL file I/O connector.
+ *
+ * Node-only: uses node:fs, node:path. NOT edge-safe.
+ *
+ * CSV parser rules (CRITICAL):
+ *   - Quoted fields preserve embedded commas and newlines
+ *   - Doubled quotes inside quoted fields unescape to a single quote
+ *   - Empty unquoted fields become null
+ *   - Leading-zero strings (zip codes "01234", SSNs, phones) are NEVER
+ *     coerced to numbers
+ *   - Booleans "true"/"false" (case-insensitive) coerce to boolean
+ *   - Numeric strings coerce to number only when fully numeric and not
+ *     leading-zero
+ *   - Supports both `\n` and `\r\n` line endings
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve, extname, dirname } from "node:path";
+import type { Row } from "../../core/types.js";
+
+// ---------------------------------------------------------------------------
+// Value coercion
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce a raw CSV field string to string | number | boolean.
+ * Preserves leading-zero strings (zip codes, SSNs, phone numbers) as strings.
+ */
+function coerceValue(raw: string): string | number | boolean {
+  // Booleans (case insensitive)
+  const lower = raw.toLowerCase();
+  if (lower === "true") return true;
+  if (lower === "false") return false;
+
+  // Only try numeric coercion for strings that are already trimmed
+  if (raw.length === 0 || raw !== raw.trim()) return raw;
+
+  // NEVER coerce leading-zero strings to numbers, except "0" itself and
+  // decimals like "0.5".
+  if (raw.length > 1 && raw[0] === "0" && raw[1] !== ".") return raw;
+
+  // Also preserve negative leading-zero strings like "-0123" as strings
+  if (raw.length > 2 && raw[0] === "-" && raw[1] === "0" && raw[2] !== ".") {
+    return raw;
+  }
+
+  const n = Number(raw);
+  if (Number.isFinite(n)) return n;
+
+  return raw;
+}
+
+// ---------------------------------------------------------------------------
+// CSV parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a full CSV document honoring quoted fields, doubled quotes,
+ * embedded newlines/commas, and both CRLF/LF line endings.
+ *
+ * Returns an array of raw string rows. The caller is responsible for
+ * interpreting the first row as a header.
+ */
+function parseCsvDocument(content: string, delimiter: string): string[][] {
+  const rows: string[][] = [];
+  let current = "";
+  let row: string[] = [];
+  let inQuotes = false;
+  let i = 0;
+  const n = content.length;
+
+  while (i < n) {
+    const ch = content[i]!;
+
+    if (inQuotes) {
+      if (ch === '"') {
+        if (i + 1 < n && content[i + 1] === '"') {
+          current += '"';
+          i += 2;
+          continue;
+        }
+        inQuotes = false;
+        i++;
+        continue;
+      }
+      current += ch;
+      i++;
+      continue;
+    }
+
+    // Not in quotes
+    if (ch === '"') {
+      inQuotes = true;
+      i++;
+      continue;
+    }
+    if (ch === delimiter) {
+      row.push(current);
+      current = "";
+      i++;
+      continue;
+    }
+    if (ch === "\r") {
+      // Swallow \r, then handle \n on next iteration
+      i++;
+      continue;
+    }
+    if (ch === "\n") {
+      row.push(current);
+      current = "";
+      rows.push(row);
+      row = [];
+      i++;
+      continue;
+    }
+    current += ch;
+    i++;
+  }
+
+  // Flush trailing field/row if any
+  if (current.length > 0 || row.length > 0) {
+    row.push(current);
+    rows.push(row);
+  }
+
+  return rows;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ReadCsvOptions {
+  readonly delimiter?: string;
+  readonly hasHeader?: boolean;
+  readonly encoding?: BufferEncoding;
+}
+
+/**
+ * Read a CSV (or TSV, via `delimiter: "\t"`) file from disk.
+ *
+ * Returns an array of `Row` objects (header -> coerced value). If
+ * `hasHeader` is false, synthetic headers `col_0`, `col_1`, ... are used.
+ */
+export function readCsv(path: string, options?: ReadCsvOptions): Row[] {
+  const resolved = resolve(path);
+  if (!existsSync(resolved)) {
+    throw new Error(`File not found: ${resolved}`);
+  }
+
+  const delimiter = options?.delimiter ?? ",";
+  const hasHeader = options?.hasHeader ?? true;
+  const encoding = options?.encoding ?? "utf8";
+
+  const content = readFileSync(resolved, encoding);
+  // Strip UTF-8 BOM if present (Excel-exported CSVs often include it)
+  const cleaned = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+
+  const rawRows = parseCsvDocument(cleaned, delimiter);
+  if (rawRows.length === 0) return [];
+
+  // Skip completely empty rows (trailing newlines, blank lines between records)
+  const nonEmpty = rawRows.filter(
+    (r) => !(r.length === 1 && r[0] === ""),
+  );
+  if (nonEmpty.length === 0) return [];
+
+  let headers: string[];
+  let dataRows: string[][];
+  if (hasHeader) {
+    headers = nonEmpty[0]!.map((h) => h.trim());
+    dataRows = nonEmpty.slice(1);
+  } else {
+    const width = nonEmpty[0]!.length;
+    headers = Array.from({ length: width }, (_, i) => `col_${i}`);
+    dataRows = nonEmpty;
+  }
+
+  const rows: Row[] = [];
+  for (const raw of dataRows) {
+    const record: Record<string, unknown> = {};
+    for (let j = 0; j < headers.length; j++) {
+      const field = raw[j] ?? "";
+      record[headers[j]!] = field === "" ? null : coerceValue(field);
+    }
+    rows.push(record);
+  }
+  return rows;
+}
+
+/**
+ * Read a JSON or JSONL file.
+ *
+ * - `.json`: expects an array of objects at the top level.
+ * - `.jsonl` / `.ndjson`: one JSON object per line.
+ *
+ * Auto-detected based on whether the first non-whitespace character is `[`.
+ */
+export function readJson(path: string): Row[] {
+  const resolved = resolve(path);
+  if (!existsSync(resolved)) {
+    throw new Error(`File not found: ${resolved}`);
+  }
+  const content = readFileSync(resolved, "utf8");
+  const trimmed = content.trimStart();
+
+  // JSONL: one object per line, detected by lack of opening `[`
+  const ext = extname(resolved).toLowerCase();
+  const isJsonl =
+    ext === ".jsonl" ||
+    ext === ".ndjson" ||
+    (trimmed.length > 0 && trimmed[0] !== "[");
+
+  if (isJsonl) {
+    const rows: Row[] = [];
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]!.trim();
+      if (line === "") continue;
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+          rows.push(parsed as Row);
+        } else {
+          throw new Error(
+            `JSONL line ${i + 1}: expected an object, got ${Array.isArray(parsed) ? "array" : typeof parsed}`,
+          );
+        }
+      } catch (err) {
+        if (err instanceof SyntaxError) {
+          throw new Error(`JSONL parse error at line ${i + 1}: ${err.message}`);
+        }
+        throw err;
+      }
+    }
+    return rows;
+  }
+
+  // Standard JSON array
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`JSON parse error in ${resolved}: ${msg}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(
+      `JSON file ${resolved}: expected an array of objects at the root`,
+    );
+  }
+  return parsed as Row[];
+}
+
+/**
+ * Dispatch to readCsv / readJson based on file extension.
+ *
+ * Supported: `.csv`, `.tsv`, `.json`, `.jsonl`, `.ndjson`.
+ */
+export function readFile(path: string): Row[] {
+  const ext = extname(path).toLowerCase();
+  if (ext === ".csv") return readCsv(path, { delimiter: "," });
+  if (ext === ".tsv") return readCsv(path, { delimiter: "\t" });
+  if (ext === ".json" || ext === ".jsonl" || ext === ".ndjson") {
+    return readJson(path);
+  }
+  throw new Error(
+    `Unsupported file format: ${ext}. Supported: .csv, .tsv, .json, .jsonl, .ndjson`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Serialization
+// ---------------------------------------------------------------------------
+
+/** Escape a CSV field: quote if it contains delimiter, quote, or newline. */
+function escapeCsvField(value: unknown, delimiter: string): string {
+  if (value === null || value === undefined) return "";
+  const s = String(value);
+  const needsQuoting =
+    s.includes(delimiter) ||
+    s.includes('"') ||
+    s.includes("\n") ||
+    s.includes("\r");
+  if (!needsQuoting) return s;
+  return `"${s.replace(/"/g, '""')}"`;
+}
+
+export interface WriteCsvOptions {
+  readonly columns?: readonly string[];
+  readonly delimiter?: string;
+}
+
+/**
+ * Write rows to a CSV file. Creates parent directories as needed.
+ *
+ * If `columns` is not supplied, the union of keys from all rows is used,
+ * ordered by first appearance.
+ */
+export function writeCsv(
+  path: string,
+  rows: readonly Row[],
+  options?: WriteCsvOptions,
+): void {
+  const resolved = resolve(path);
+  const dir = dirname(resolved);
+  if (dir && dir !== "." && !existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const delimiter = options?.delimiter ?? ",";
+
+  let columns: string[];
+  if (options?.columns && options.columns.length > 0) {
+    columns = [...options.columns];
+  } else if (rows.length === 0) {
+    writeFileSync(resolved, "", "utf8");
+    return;
+  } else {
+    const seen = new Set<string>();
+    columns = [];
+    for (const row of rows) {
+      for (const key of Object.keys(row)) {
+        if (!seen.has(key)) {
+          seen.add(key);
+          columns.push(key);
+        }
+      }
+    }
+  }
+
+  const lines: string[] = [];
+  lines.push(columns.map((c) => escapeCsvField(c, delimiter)).join(delimiter));
+  for (const row of rows) {
+    const fields = columns.map((c) => escapeCsvField(row[c], delimiter));
+    lines.push(fields.join(delimiter));
+  }
+  writeFileSync(resolved, lines.join("\n") + "\n", "utf8");
+}
+
+/** Write rows to a JSON file as a pretty-printed array. */
+export function writeJson(path: string, rows: readonly Row[]): void {
+  const resolved = resolve(path);
+  const dir = dirname(resolved);
+  if (dir && dir !== "." && !existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(resolved, JSON.stringify(rows, null, 2), "utf8");
+}

package/src/node/connectors/hubspot.ts

@@ -0,0 +1,62 @@
+/**
+ * hubspot.ts -- HubSpot CRM connector via REST API + fetch().
+ *
+ * `query.table` selects the HubSpot object: "contacts", "companies", "deals", etc.
+ * SQL strings are not supported -- use object queries.
+ */
+
+import type { Row } from "../../core/types.js";
+import type { BaseConnector } from "./base.js";
+
+export interface HubSpotConfig {
+  readonly apiKey: string; // HubSpot private app access token
+  readonly apiBase?: string; // default "https://api.hubapi.com"
+}
+
+interface HubSpotResult {
+  id: string;
+  properties: Record<string, unknown>;
+}
+
+interface HubSpotPage {
+  results: HubSpotResult[];
+  paging?: { next?: { link: string } };
+}
+
+export function createHubSpotConnector(config: HubSpotConfig): BaseConnector {
+  const base = config.apiBase ?? "https://api.hubapi.com";
+
+  return {
+    name: "hubspot",
+    async connect() {
+      // No-op: stateless REST.
+    },
+    async read(query) {
+      if (typeof query === "string") {
+        throw new Error("HubSpot connector requires an object query (table/columns/limit), not SQL.");
+      }
+      const limit = query.limit ?? 100;
+      const propsParam = query.columns?.length ? `&properties=${query.columns.join(",")}` : "";
+      const endpoint = `${base}/crm/v3/objects/${query.table}?limit=${limit}${propsParam}`;
+      const rows: Row[] = [];
+      let next: string | undefined = endpoint;
+      while (next) {
+        const resp = await fetch(next, {
+          headers: { Authorization: `Bearer ${config.apiKey}` },
+        });
+        if (!resp.ok) {
+          throw new Error(`HubSpot query failed: ${resp.status} ${await resp.text()}`);
+        }
+        const j = (await resp.json()) as HubSpotPage;
+        for (const r of j.results) {
+          rows.push({ id: r.id, ...r.properties });
+        }
+        next = j.paging?.next?.link;
+      }
+      return rows;
+    },
+    async close() {
+      // Stateless.
+    },
+  };
+}

package/src/node/connectors/index.ts

@@ -0,0 +1,43 @@
+/**
+ * index.ts -- Connector registry bootstrap and re-exports.
+ */
+
+import { registerConnector, loadConnector, listConnectors } from "./base.js";
+import { createSnowflakeConnector, type SnowflakeConfig } from "./snowflake.js";
+import { createBigQueryConnector, type BigQueryConfig } from "./bigquery.js";
+import { createDatabricksConnector, type DatabricksConfig } from "./databricks.js";
+import { createSalesforceConnector, type SalesforceConfig } from "./salesforce.js";
+import { createHubSpotConnector, type HubSpotConfig } from "./hubspot.js";
+
+registerConnector("snowflake", (c) => createSnowflakeConnector(c as unknown as SnowflakeConfig));
+registerConnector("bigquery", (c) => createBigQueryConnector(c as unknown as BigQueryConfig));
+registerConnector("databricks", (c) => createDatabricksConnector(c as unknown as DatabricksConfig));
+registerConnector("salesforce", (c) => createSalesforceConnector(c as unknown as SalesforceConfig));
+registerConnector("hubspot", (c) => createHubSpotConnector(c as unknown as HubSpotConfig));
+
+export {
+  createSnowflakeConnector,
+  createBigQueryConnector,
+  createDatabricksConnector,
+  createSalesforceConnector,
+  createHubSpotConnector,
+  registerConnector,
+  loadConnector,
+  listConnectors,
+};
+
+export type {
+  BaseConnector,
+  ConnectorConfig,
+  ConnectorFactory,
+  ConnectorQuery,
+} from "./base.js";
+export type { SnowflakeConfig } from "./snowflake.js";
+export type { BigQueryConfig } from "./bigquery.js";
+export type { DatabricksConfig } from "./databricks.js";
+export type { SalesforceConfig } from "./salesforce.js";
+export type { HubSpotConfig } from "./hubspot.js";
+
+// Re-export the existing local-file connector for convenience.
+export { readFile, readCsv, readJson, writeCsv, writeJson } from "./file.js";
+export type { ReadCsvOptions, WriteCsvOptions } from "./file.js";

package/src/node/connectors/salesforce.ts

@@ -0,0 +1,93 @@
+/**
+ * salesforce.ts -- Salesforce connector using the REST API via fetch().
+ *
+ * No SDK dependency: stays edge-adjacent. Supports either a pre-issued
+ * accessToken or the OAuth 2.0 password grant flow.
+ */
+
+import type { Row } from "../../core/types.js";
+import type { BaseConnector, ConnectorQuery } from "./base.js";
+
+export interface SalesforceConfig {
+  readonly instanceUrl: string; // e.g. "https://xxx.my.salesforce.com"
+  readonly accessToken?: string;
+  readonly clientId?: string;
+  readonly clientSecret?: string;
+  readonly username?: string;
+  readonly password?: string;
+  readonly securityToken?: string;
+  readonly apiVersion?: string; // default "v61.0"
+}
+
+interface OAuthResponse {
+  access_token: string;
+  instance_url: string;
+}
+
+interface QueryResponse {
+  records: Row[];
+  done: boolean;
+  nextRecordsUrl?: string;
+}
+
+export function createSalesforceConnector(config: SalesforceConfig): BaseConnector {
+  const apiVersion = config.apiVersion ?? "v61.0";
+  let accessToken = config.accessToken;
+  let instanceUrl = config.instanceUrl;
+
+  return {
+    name: "salesforce",
+    async connect() {
+      if (accessToken) return;
+      const body = new URLSearchParams({
+        grant_type: "password",
+        client_id: config.clientId ?? "",
+        client_secret: config.clientSecret ?? "",
+        username: config.username ?? "",
+        password: (config.password ?? "") + (config.securityToken ?? ""),
+      });
+      const resp = await fetch(`${instanceUrl}/services/oauth2/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+      });
+      if (!resp.ok) {
+        throw new Error(`Salesforce auth failed: ${resp.status} ${await resp.text()}`);
+      }
+      const j = (await resp.json()) as OAuthResponse;
+      accessToken = j.access_token;
+      instanceUrl = j.instance_url;
+    },
+    async read(query) {
+      if (!accessToken) {
+        throw new Error("Salesforce connector not connected. Call connect() first.");
+      }
+      const soql = typeof query === "string" ? query : buildSOQL(query);
+      const url = `${instanceUrl}/services/data/${apiVersion}/query?q=${encodeURIComponent(soql)}`;
+      const rows: Row[] = [];
+      let next: string | undefined = url;
+      while (next) {
+        const resp = await fetch(next, {
+          headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!resp.ok) {
+          throw new Error(`Salesforce query failed: ${resp.status} ${await resp.text()}`);
+        }
+        const j = (await resp.json()) as QueryResponse;
+        rows.push(...j.records);
+        next = j.nextRecordsUrl ? `${instanceUrl}${j.nextRecordsUrl}` : undefined;
+      }
+      return rows;
+    },
+    async close() {
+      // Stateless: nothing to tear down.
+    },
+  };
+}
+
+function buildSOQL(q: ConnectorQuery): string {
+  const cols = q.columns?.length ? q.columns.join(",") : "Id";
+  let sql = `SELECT ${cols} FROM ${q.table}`;
+  if (q.limit) sql += ` LIMIT ${q.limit}`;
+  return sql;
+}

package/src/node/connectors/snowflake.ts

@@ -0,0 +1,73 @@
+/**
+ * snowflake.ts -- Snowflake connector via the optional `snowflake-sdk` peer dep.
+ */
+
+import { createRequire } from "node:module";
+import type { Row } from "../../core/types.js";
+import type { BaseConnector, ConnectorQuery } from "./base.js";
+
+export interface SnowflakeConfig {
+  readonly account: string;
+  readonly username: string;
+  readonly password?: string;
+  readonly privateKey?: string;
+  readonly warehouse?: string;
+  readonly database?: string;
+  readonly schema?: string;
+  readonly role?: string;
+}
+
+export function createSnowflakeConnector(config: SnowflakeConfig): BaseConnector {
+  const require = createRequire(import.meta.url);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let snowflake: any;
+  try {
+    snowflake = require("snowflake-sdk");
+  } catch {
+    throw new Error(
+      "'snowflake-sdk' is required for the Snowflake connector. Install: npm install snowflake-sdk",
+    );
+  }
+
+  const connection = snowflake.createConnection({
+    account: config.account,
+    username: config.username,
+    password: config.password,
+    privateKey: config.privateKey,
+    warehouse: config.warehouse,
+    database: config.database,
+    schema: config.schema,
+    role: config.role,
+  });
+
+  return {
+    name: "snowflake",
+    connect() {
+      return new Promise<void>((resolve, reject) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        connection.connect((err: any) => (err ? reject(err) : resolve()));
+      });
+    },
+    async read(query) {
+      const sql = typeof query === "string" ? query : buildSelect(query);
+      return new Promise<Row[]>((resolve, reject) => {
+        connection.execute({
+          sqlText: sql,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          complete: (err: any, _stmt: any, rows: Row[]) =>
+            err ? reject(err) : resolve(rows ?? []),
+        });
+      });
+    },
+    async close() {
+      await new Promise<void>((resolve) => connection.destroy(() => resolve()));
+    },
+  };
+}
+
+function buildSelect(q: ConnectorQuery): string {
+  const cols = q.columns?.length ? q.columns.map((c) => `"${c}"`).join(",") : "*";
+  let sql = `SELECT ${cols} FROM ${q.table}`;
+  if (q.limit) sql += ` LIMIT ${q.limit}`;
+  return sql;
+}