@almadar/integrations 2.19.0 → 2.20.0

package/dist/{BaseIntegration-B9lSTRQm.d.ts → BaseIntegration-MA-b4fh8.d.ts}

@@ -146,4 +146,4 @@ declare abstract class BaseIntegration {
     protected executeWithRetry<T>(fn: () => Promise<T>): Promise<T>;
 }
 
-export { BaseIntegration as B, type IntegrationConfig as I, type ValidationError as V, IntegrationError as a, type IntegrationErrorCode as b, type IntegrationLogger as c, type IntegrationParams as d, type IntegrationResult as e, type ValidationResult as f, validateParams as v };
+export { BaseIntegration as B, type IntegrationConfig as I, type ValidationError as V, IntegrationError as a, type IntegrationErrorCode as b, type IntegrationLogger as c, type IntegrationParamValue as d, type IntegrationParams as e, type IntegrationResult as f, type ValidationResult as g, validateParams as v };

package/dist/{contracts-B28G_7ur.d.ts → contracts-DaVfyPnd.d.ts}

@@ -1,5 +1,29 @@
 import { ServiceParamsValue, ServiceParams } from '@almadar/core';
-import { d as IntegrationParams } from './BaseIntegration-B9lSTRQm.js';
+import { d as IntegrationParamValue, e as IntegrationParams } from './BaseIntegration-MA-b4fh8.js';
+
+/** Scalar value admissible as a SQL bind parameter. */
+type DatabaseQueryParamValue = string | number | boolean | Date | null;
+/** Params for the `query` action. */
+type DatabaseQueryParams = {
+    connectionRef: string;
+    sql: string;
+    params?: DatabaseQueryParamValue[];
+};
+/** One result row, keyed by column name. */
+type DatabaseRow = Record<string, IntegrationParamValue>;
+/** Result of a read-only query. */
+interface DatabaseQueryResult {
+    rows: DatabaseRow[];
+    rowCount: number;
+}
+/**
+ * Driver seam behind the `query` action. Postgres is the first
+ * implementation; MySQL/SQLite slot behind this interface later.
+ */
+interface DatabaseDriver {
+    query(sql: string, params: readonly DatabaseQueryParamValue[]): Promise<DatabaseQueryResult>;
+    end(): Promise<void>;
+}
 
 /**
  * ServiceContract type definitions for all @almadar/integrations.
@@ -848,6 +872,19 @@ type DeepAgentActions = {
         };
     };
 };
+type DatabaseActions = {
+    query: {
+        params: {
+            connectionRef: string;
+            sql: string;
+            params?: DatabaseQueryParamValue[];
+        };
+        result: {
+            rows: DatabaseRow[];
+            rowCount: number;
+        };
+    };
+};
 /**
  * Maps each integration name (as used in `registerIntegration`) to its action
  * map type. Use with `ServiceContract<IntegrationContracts[K]>` to get a fully
@@ -877,6 +914,7 @@ type IntegrationContracts = {
     otel: OtelActions;
     cli: CLIActions;
     deepagent: DeepAgentActions;
+    database: DatabaseActions;
 };
 /** Integration name literal union. */
 type IntegrationName = keyof IntegrationContracts;
@@ -891,4 +929,4 @@ type IntegrationName = keyof IntegrationContracts;
  */
 type IntegrationActionName<K extends IntegrationName> = keyof IntegrationContracts[K] & string;
 
-export type { CLIActions as C, DeepAgentActions as D, EmailActions as E, GitHubActions as G, IntegrationActionName as I, LLMIntegrationActions as L, MLActions as M, OAuthActions as O, QueueActions as Q, RedisActions as R, StorageActions as S, TwilioActions as T, YouTubeActions as Y, DockerActions as a, IntegrationContracts as b, IntegrationName as c, OtelActions as d, StripeActions as e };
+export type { CLIActions as C, DatabaseActions as D, EmailActions as E, GitHubActions as G, IntegrationActionName as I, LLMIntegrationActions as L, MLActions as M, OAuthActions as O, QueueActions as Q, RedisActions as R, StorageActions as S, TwilioActions as T, YouTubeActions as Y, DatabaseDriver as a, DatabaseQueryParamValue as b, DatabaseQueryParams as c, DatabaseQueryResult as d, DatabaseRow as e, DeepAgentActions as f, DockerActions as g, IntegrationContracts as h, IntegrationName as i, OtelActions as j, StripeActions as k };

package/dist/{factory-TNgVDujm.d.ts → factory-DTdVeyAi.d.ts}

@@ -1,4 +1,4 @@
-import { I as IntegrationConfig, B as BaseIntegration, d as IntegrationParams, e as IntegrationResult } from './BaseIntegration-B9lSTRQm.js';
+import { I as IntegrationConfig, B as BaseIntegration, e as IntegrationParams, f as IntegrationResult } from './BaseIntegration-MA-b4fh8.js';
 
 /**
  * Factory for creating and managing integration instances

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { c as IntegrationLogger, b as IntegrationErrorCode, I as IntegrationConfig, B as BaseIntegration, d as IntegrationParams, e as IntegrationResult } from './BaseIntegration-B9lSTRQm.js';
-export { a as IntegrationError, V as ValidationError, f as ValidationResult, v as validateParams } from './BaseIntegration-B9lSTRQm.js';
-export { C as CLIActions, D as DeepAgentActions, a as DockerActions, E as EmailActions, G as GitHubActions, I as IntegrationActionName, b as IntegrationContracts, c as IntegrationName, L as LLMIntegrationActions, M as MLActions, O as OAuthActions, d as OtelActions, Q as QueueActions, R as RedisActions, S as StorageActions, e as StripeActions, T as TwilioActions, Y as YouTubeActions } from './contracts-B28G_7ur.js';
+import { c as IntegrationLogger, b as IntegrationErrorCode, I as IntegrationConfig, B as BaseIntegration, e as IntegrationParams, f as IntegrationResult } from './BaseIntegration-MA-b4fh8.js';
+export { a as IntegrationError, d as IntegrationParamValue, V as ValidationError, g as ValidationResult, v as validateParams } from './BaseIntegration-MA-b4fh8.js';
+export { C as CLIActions, D as DatabaseActions, a as DatabaseDriver, b as DatabaseQueryParamValue, c as DatabaseQueryParams, d as DatabaseQueryResult, e as DatabaseRow, f as DeepAgentActions, g as DockerActions, E as EmailActions, G as GitHubActions, I as IntegrationActionName, h as IntegrationContracts, i as IntegrationName, L as LLMIntegrationActions, M as MLActions, O as OAuthActions, j as OtelActions, Q as QueueActions, R as RedisActions, S as StorageActions, k as StripeActions, T as TwilioActions, Y as YouTubeActions } from './contracts-DaVfyPnd.js';
 import { LogMeta } from '@almadar/core';
-export { I as IntegrationFactory, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-TNgVDujm.js';
+export { I as IntegrationFactory, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-DTdVeyAi.js';
 export { GitHubIntegration } from './integrations/github/index.js';
 
 /**
@@ -560,4 +560,44 @@ declare class DockerIntegration extends BaseIntegration {
     private list;
 }
 
-export { type AlmadarCheckoutSession, type AlmadarCustomer, type AlmadarInvoiceFailure, type AlmadarInvoicePayment, type AlmadarPortalSession, type AlmadarStripeEvent, type AlmadarStripeEventOk, type AlmadarSubscription, type AlmadarSubscriptionStatus, type AlmadarTier, BaseIntegration, CLIIntegration, type CancelSubscriptionInput, ConsoleLogger, type CreateCheckoutInput, type CreateCustomerInput, type CreatePortalInput, DeepAgentIntegration, DockerIntegration, EmailIntegration, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationLogger, IntegrationResult, LLMIntegration, MLIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, type RetryConfig, StorageIntegration, StripeIntegration, type StripePriceMap, TwilioIntegration, type UpdateSubscriptionInput, type VerifyAndParseInput, YouTubeIntegration, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, verifyAndParseStripeEvent, withRetry };
+/**
+ * Read-only SQL enforcement for the database integration.
+ *
+ * The guard accepts exactly one SELECT statement (optionally CTE-led) and
+ * nothing else. Comments are stripped and string/identifier contents are
+ * blanked before keyword checks, so denied keywords inside literals (e.g.
+ * `WHERE note = 'delete this'`) never false-positive, and comment/quote
+ * tricks cannot smuggle a second statement past the check.
+ */
+interface SqlGuardResult {
+    ok: boolean;
+    reason?: string;
+}
+/**
+ * Verify `sql` is a single read-only SELECT statement.
+ * Returns `{ ok: false, reason }` for anything else.
+ */
+declare function assertReadOnlySelect(sql: string): SqlGuardResult;
+
+/**
+ * Database Integration for Almadar
+ * Read-only SQL queries over external connections (migration fetch seam).
+ */
+
+/**
+ * Generic database integration. One action — `query` — with read-only
+ * enforced in the integration itself (single SELECT only, statement
+ * timeout). `connectionRef` is an environment variable NAME, never the
+ * secret; the connection string is resolved from `process.env` at run time.
+ */
+declare class DatabaseIntegration extends BaseIntegration {
+    private drivers;
+    private statementTimeoutMs;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private runQuery;
+    /** Resolve (and cache) the driver for a connection reference. */
+    private driverFor;
+}
+
+export { type AlmadarCheckoutSession, type AlmadarCustomer, type AlmadarInvoiceFailure, type AlmadarInvoicePayment, type AlmadarPortalSession, type AlmadarStripeEvent, type AlmadarStripeEventOk, type AlmadarSubscription, type AlmadarSubscriptionStatus, type AlmadarTier, BaseIntegration, CLIIntegration, type CancelSubscriptionInput, ConsoleLogger, type CreateCheckoutInput, type CreateCustomerInput, type CreatePortalInput, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, EmailIntegration, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationLogger, IntegrationParams, IntegrationResult, LLMIntegration, MLIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, type RetryConfig, type SqlGuardResult, StorageIntegration, StripeIntegration, type StripePriceMap, TwilioIntegration, type UpdateSubscriptionInput, type VerifyAndParseInput, YouTubeIntegration, assertReadOnlySelect, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, verifyAndParseStripeEvent, withRetry };

package/dist/index.js

@@ -11,8 +11,27 @@ import { execSync, spawn } from 'child_process';
 import { mkdtempSync, writeFileSync, rmSync, promises } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import { Pool } from 'pg';
 
-// src/core/logger.ts
+// src/types.ts
+var IntegrationError = class extends Error {
+  constructor(message, code = "UNKNOWN_ERROR", details) {
+    super(message);
+    this.name = "IntegrationError";
+    this.code = code;
+    this.details = details;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      integration: this.integration,
+      action: this.action,
+      details: this.details
+    };
+  }
+};
 var ConsoleLogger = class {
   constructor(_level = "info") {
     this.log = createLogger("almadar:integrations");
@@ -1121,26 +1140,6 @@ Return ONLY valid JSON matching the schema.`,
 };
 registerIntegration("llm", LLMIntegration);
 
-// src/types.ts
-var IntegrationError = class extends Error {
-  constructor(message, code = "UNKNOWN_ERROR", details) {
-    super(message);
-    this.name = "IntegrationError";
-    this.code = code;
-    this.details = details;
-  }
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      code: this.code,
-      integration: this.integration,
-      action: this.action,
-      details: this.details
-    };
-  }
-};
-
 // src/integrations/ml/index.ts
 var INFERRED_EVENT = "INFERRED";
 var INFER_FAILED_EVENT = "INFER_FAILED";
@@ -3172,6 +3171,249 @@ var DockerIntegration = class extends BaseIntegration {
 };
 registerIntegration("docker", DockerIntegration);
 
-export { BaseIntegration, CLIIntegration, ConsoleLogger, DeepAgentIntegration, DockerIntegration, EmailIntegration, GitHubIntegration, IntegrationFactory, LLMIntegration, MLIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, YouTubeIntegration, getIntegration, getIntegrationFactory, getRegisteredIntegrations, isKnownIntegration, registerIntegration, resetIntegrationFactory, validateParams, verifyAndParseStripeEvent, withRetry };
+// src/integrations/database/sql-guard.ts
+var DENIED_KEYWORDS = /* @__PURE__ */ new Set(["INSERT", "UPDATE", "DELETE", "MERGE", "INTO", "FOR"]);
+function isWordChar(ch) {
+  return ch >= "a" && ch <= "z" || ch >= "A" && ch <= "Z" || ch >= "0" && ch <= "9" || ch === "_" || ch === "$";
+}
+function skipSingleQuoted(sql, start, eString) {
+  let i = start + 1;
+  while (i < sql.length) {
+    if (eString && sql[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (sql[i] === "'") {
+      if (sql[i + 1] === "'") {
+        i += 2;
+        continue;
+      }
+      return i + 1;
+    }
+    i++;
+  }
+  return sql.length;
+}
+function skipDoubleQuoted(sql, start) {
+  let i = start + 1;
+  while (i < sql.length) {
+    if (sql[i] === '"') {
+      if (sql[i + 1] === '"') {
+        i += 2;
+        continue;
+      }
+      return i + 1;
+    }
+    i++;
+  }
+  return sql.length;
+}
+function matchDollarTag(sql, start) {
+  let i = start + 1;
+  if (sql[i] === "$") return "$$";
+  const first = sql[i];
+  if (!first || !(first >= "a" && first <= "z" || first >= "A" && first <= "Z" || first === "_")) {
+    return void 0;
+  }
+  i++;
+  while (i < sql.length && isWordChar(sql[i]) && sql[i] !== "$") i++;
+  if (sql[i] !== "$") return void 0;
+  return sql.slice(start, i + 1);
+}
+function sanitizeSql(sql) {
+  const out = [];
+  let i = 0;
+  while (i < sql.length) {
+    const ch = sql[i];
+    if (ch === "-" && sql[i + 1] === "-") {
+      while (i < sql.length && sql[i] !== "\n") i++;
+      out.push(" ");
+      continue;
+    }
+    if (ch === "/" && sql[i + 1] === "*") {
+      let depth = 1;
+      i += 2;
+      while (i < sql.length && depth > 0) {
+        if (sql[i] === "/" && sql[i + 1] === "*") {
+          depth++;
+          i += 2;
+        } else if (sql[i] === "*" && sql[i + 1] === "/") {
+          depth--;
+          i += 2;
+        } else {
+          i++;
+        }
+      }
+      out.push(" ");
+      continue;
+    }
+    if (ch === "'") {
+      let j = i - 1;
+      while (j >= 0 && (sql[j] === " " || sql[j] === "	" || sql[j] === "\n" || sql[j] === "\r")) j--;
+      const prev = j >= 0 ? sql[j] : "";
+      const eString = (prev === "e" || prev === "E") && (j === 0 || !isWordChar(sql[j - 1]));
+      i = skipSingleQuoted(sql, i, eString);
+      out.push("''");
+      continue;
+    }
+    if (ch === '"') {
+      i = skipDoubleQuoted(sql, i);
+      out.push('""');
+      continue;
+    }
+    if (ch === "$") {
+      const tag = matchDollarTag(sql, i);
+      if (tag) {
+        const close = sql.indexOf(tag, i + tag.length);
+        i = close === -1 ? sql.length : close + tag.length;
+        out.push("$$");
+        continue;
+      }
+    }
+    out.push(ch);
+    i++;
+  }
+  return out.join("");
+}
+function assertReadOnlySelect(sql) {
+  const sanitized = sanitizeSql(sql);
+  const statements = sanitized.split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (statements.length === 0) {
+    return { ok: false, reason: "Empty statement" };
+  }
+  if (statements.length > 1) {
+    return { ok: false, reason: "Only a single statement is allowed" };
+  }
+  const words = (statements[0].match(/\b[A-Za-z_][A-Za-z0-9_]*\b/g) ?? []).map(
+    (w) => w.toUpperCase()
+  );
+  const first = words[0];
+  if (first !== "SELECT" && first !== "WITH") {
+    return { ok: false, reason: "Only SELECT statements are allowed" };
+  }
+  const denied = words.find((w) => DENIED_KEYWORDS.has(w));
+  if (denied) {
+    return { ok: false, reason: `Keyword not allowed in a read-only query: ${denied}` };
+  }
+  return { ok: true };
+}
+
+// src/integrations/database/index.ts
+var DEFAULT_STATEMENT_TIMEOUT_MS = 1e4;
+var PG_QUERY_CANCELED = "57014";
+var PostgresDriver = class {
+  constructor(connectionString, statementTimeoutMs) {
+    this.pool = new Pool({
+      connectionString,
+      statement_timeout: statementTimeoutMs,
+      query_timeout: statementTimeoutMs
+    });
+  }
+  async query(sql, params) {
+    const result = await this.pool.query(sql, [...params]);
+    return {
+      rows: result.rows,
+      rowCount: result.rowCount ?? result.rows.length
+    };
+  }
+  async end() {
+    await this.pool.end();
+  }
+};
+function mapDriverError(error) {
+  if (error instanceof IntegrationError) return error;
+  const code = error.code;
+  if (code === PG_QUERY_CANCELED) {
+    return new IntegrationError("Statement timeout exceeded", "TIMEOUT_ERROR");
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return new IntegrationError(message, "SERVICE_ERROR");
+}
+var DatabaseIntegration = class extends BaseIntegration {
+  constructor(config) {
+    super(config);
+    this.drivers = /* @__PURE__ */ new Map();
+    const fromEnv = config.env.DATABASE_STATEMENT_TIMEOUT_MS;
+    if (fromEnv) {
+      const parsed = Number(fromEnv);
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid DATABASE_STATEMENT_TIMEOUT_MS: ${fromEnv}`);
+      }
+      this.statementTimeoutMs = parsed;
+    } else {
+      this.statementTimeoutMs = config.timeout ?? DEFAULT_STATEMENT_TIMEOUT_MS;
+    }
+    this.logger.info("Database integration initialized", {
+      statementTimeoutMs: this.statementTimeoutMs
+    });
+  }
+  async execute(action, params) {
+    const validation = this.validateParams(action, params);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          name: "IntegrationError",
+          message: "Validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        },
+        metadata: this.createMetadata(action, 0)
+      };
+    }
+    const startTime = Date.now();
+    try {
+      let data;
+      switch (action) {
+        case "query":
+          data = await this.executeWithRetry(() => this.runQuery(params));
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+      return {
+        success: true,
+        data,
+        metadata: this.createMetadata(action, Date.now() - startTime)
+      };
+    } catch (error) {
+      return this.handleError(action, error);
+    }
+  }
+  async runQuery(params) {
+    const guard = assertReadOnlySelect(params.sql);
+    if (!guard.ok) {
+      throw new IntegrationError(
+        `Read-only violation: ${guard.reason ?? "not a SELECT statement"}`,
+        "VALIDATION_ERROR"
+      );
+    }
+    const driver = this.driverFor(params.connectionRef);
+    this.logger.debug("Database QUERY", { connectionRef: params.connectionRef });
+    try {
+      return await driver.query(params.sql, params.params ?? []);
+    } catch (error) {
+      throw mapDriverError(error);
+    }
+  }
+  /** Resolve (and cache) the driver for a connection reference. */
+  driverFor(connectionRef) {
+    const connectionString = process.env[connectionRef];
+    if (!connectionString) {
+      throw new IntegrationError(
+        `Connection reference "${connectionRef}" is not set in the environment`,
+        "AUTH_ERROR"
+      );
+    }
+    const cached = this.drivers.get(connectionString);
+    if (cached) return cached;
+    const driver = new PostgresDriver(connectionString, this.statementTimeoutMs);
+    this.drivers.set(connectionString, driver);
+    return driver;
+  }
+};
+registerIntegration("database", DatabaseIntegration);
+
+export { BaseIntegration, CLIIntegration, ConsoleLogger, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, EmailIntegration, GitHubIntegration, IntegrationError, IntegrationFactory, LLMIntegration, MLIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, YouTubeIntegration, assertReadOnlySelect, getIntegration, getIntegrationFactory, getRegisteredIntegrations, isKnownIntegration, registerIntegration, resetIntegrationFactory, validateParams, verifyAndParseStripeEvent, withRetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map