@pranshulsoni/flowwatch 1.0.0

package/dist/search/elasticsearch/indexSetup.js

@@ -0,0 +1,43 @@
+export async function createErrorMapping(client) {
+    await client.indices.create({
+        index: "flowwatch_errors",
+        mappings: {
+            properties: {
+                id: { type: "keyword" },
+                traceId: { type: "keyword" },
+                spanId: { type: "keyword" },
+                source: { type: "keyword" },
+                category: { type: "keyword" },
+                level: { type: "keyword" },
+                name: { type: "keyword" },
+                fingerprint: { type: "keyword" },
+                message: { type: "text" },
+                stack: { type: "text" },
+                statusCode: { type: "integer" },
+                metadata: { type: "object", enabled: true },
+                occurredAt: { type: "date" },
+                createdAt: { type: "date" },
+            },
+        },
+    });
+}
+export async function createTraceMapping(client) {
+    await client.indices.create({
+        index: "flowwatch_trace_spans",
+        mappings: {
+            properties: {
+                id: { type: "keyword" },
+                traceId: { type: "keyword" },
+                parentSpanId: { type: "keyword" },
+                name: { type: "text" },
+                type: { type: "keyword" },
+                status: { type: "keyword" },
+                durationMs: { type: "integer" },
+                metadata: { type: "object", enabled: true },
+                startedAt: { type: "date" },
+                endedAt: { type: "date" },
+                createdAt: { type: "date" },
+            },
+        },
+    });
+}

package/dist/search/elasticsearch/indexer.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from "@elastic/elasticsearch";
+import type { ErrorRow } from "../../persistence/repositories/errors/errorRepository.js";
+import type { TraceSpanRow } from "../../persistence/repositories/traces/traceRepository.js";
+export declare const errorIndex = "flowwatch_errors";
+export declare const traceSpanIndex = "flowwatch_trace_spans";
+export declare function indexError(client: Client, error: ErrorRow): Promise<void>;
+export declare function indexTraceSpan(client: Client, span: TraceSpanRow): Promise<void>;
+export declare function createErrorMapping(client: Client): Promise<void>;
+export declare function createTraceMapping(client: Client): Promise<void>;

package/dist/search/elasticsearch/indexer.js

@@ -0,0 +1,86 @@
+export const errorIndex = "flowwatch_errors";
+export const traceSpanIndex = "flowwatch_trace_spans";
+export async function indexError(client, error) {
+    await client.index({
+        index: errorIndex,
+        id: error.id,
+        document: {
+            id: error.id,
+            traceId: error.trace_id,
+            spanId: error.span_id,
+            source: error.source,
+            category: error.category,
+            level: error.level,
+            message: error.message,
+            stack: error.stack,
+            name: error.name,
+            statusCode: error.status_code,
+            fingerprint: error.fingerprint,
+            metadata: error.metadata,
+            occurredAt: error.occurred_at,
+            createdAt: error.created_at,
+        },
+    });
+}
+export async function indexTraceSpan(client, span) {
+    await client.index({
+        index: traceSpanIndex,
+        id: span.id,
+        document: {
+            id: span.id,
+            traceId: span.trace_id,
+            parentSpanId: span.parent_span_id,
+            name: span.name,
+            type: span.type,
+            status: span.status,
+            durationMs: span.duration_ms,
+            metadata: span.metadata,
+            startedAt: span.started_at,
+            endedAt: span.ended_at,
+            createdAt: span.created_at,
+        },
+    });
+}
+export async function createErrorMapping(client) {
+    await client.indices.create({
+        index: "flowwatch_errors",
+        mappings: {
+            properties: {
+                id: { type: "keyword" },
+                traceId: { type: "keyword" },
+                spanId: { type: "keyword" },
+                source: { type: "keyword" },
+                category: { type: "keyword" },
+                level: { type: "keyword" },
+                name: { type: "keyword" },
+                fingerprint: { type: "keyword" },
+                message: { type: "text" },
+                stack: { type: "text" },
+                statusCode: { type: "integer" },
+                metadata: { type: "object", enabled: true },
+                occurredAt: { type: "date" },
+                createdAt: { type: "date" },
+            },
+        },
+    });
+}
+export async function createTraceMapping(client) {
+    await client.indices.create({
+        index: "flowwatch_trace_spans",
+        mappings: {
+            properties: {
+                id: { type: "keyword" },
+                traceId: { type: "keyword" },
+                parentSpanId: { type: "keyword" },
+                name: { type: "text" },
+                type: { type: "keyword" },
+                status: { type: "keyword" },
+                durationMs: { type: "integer" },
+                metadata: { type: "object", enabled: true },
+                startedAt: { type: "date" },
+                endedAt: { type: "date" },
+                createdAt: { type: "date" },
+            },
+        },
+    });
+}

package/dist/search/elasticsearch/mappingChecker.d.ts

@@ -0,0 +1,2 @@
+import type { Client } from "@elastic/elasticsearch";
+export declare function createMissingMappings(client: Client): Promise<void>;

package/dist/search/elasticsearch/mappingChecker.js

@@ -0,0 +1,28 @@
+import { createErrorMapping, createTraceMapping, errorIndex, traceSpanIndex } from "./indexer.js";
+export async function createMissingMappings(client) {
+    try {
+        await createErrorMappingIfMissing(client);
+        await createTraceMappingIfMissing(client);
+    }
+    catch (err) {
+        console.warn(`[Flowwatch] ⚠️  Elasticsearch unavailable on startup (${err?.message ?? err}). Search indexing will be skipped until Elasticsearch is reachable.`);
+    }
+}
+async function createErrorMappingIfMissing(client) {
+    const exists = await client.indices.exists({
+        index: errorIndex,
+    });
+    if (exists) {
+        return;
+    }
+    await createErrorMapping(client);
+}
+async function createTraceMappingIfMissing(client) {
+    const exists = await client.indices.exists({
+        index: traceSpanIndex,
+    });
+    if (exists) {
+        return;
+    }
+    await createTraceMapping(client);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,48 @@
+import type { PoolConfig } from "pg";
+import type { Request } from "express";
+export interface FlowwatchConfig {
+    db: PoolConfig;
+    redis: FlowwatchRedisConfig;
+    elasticsearch: FlowwatchElasticsearchConfig;
+    dashboard?: FlowwatchDashboardConfig;
+    worker?: boolean | FlowwatchWorkerConfig;
+    migrations?: FlowwatchMigrationConfig;
+    runtime?: FlowwatchRuntimeConfig;
+}
+export interface FlowwatchRedisConfig {
+    url: string;
+}
+export interface FlowwatchElasticsearchConfig {
+    node: string;
+}
+export interface FlowwatchDashboardConfig {
+    path?: string;
+    token?: string;
+    auth?: (req: Request) => boolean | Promise<boolean>;
+    enabled?: boolean;
+}
+export interface FlowwatchWorkerConfig {
+    enabled?: boolean;
+    workflowConcurrency?: number;
+    errorIndexingConcurrency?: number;
+    maintenanceConcurrency?: number;
+    queuePrefix?: string;
+}
+export interface FlowwatchMigrationConfig {
+    autoRun?: boolean;
+    tableName?: string;
+}
+export interface FlowwatchRuntimeConfig {
+    environment?: "development" | "test" | "staging" | "production" | string;
+    serviceName?: string;
+    debug?: boolean;
+}
+export interface NormalizedFlowwatchConfig {
+    db: PoolConfig;
+    redis: FlowwatchRedisConfig;
+    elasticsearch: FlowwatchElasticsearchConfig;
+    dashboard: Required<Pick<FlowwatchDashboardConfig, "path" | "enabled">> & Pick<FlowwatchDashboardConfig, "token" | "auth">;
+    worker: Required<FlowwatchWorkerConfig>;
+    migrations: Required<FlowwatchMigrationConfig>;
+    runtime: Required<FlowwatchRuntimeConfig>;
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/flowwatchEnvStore.d.ts

@@ -0,0 +1,27 @@
+interface FlowwatchEnv {
+    groqApiKey?: string;
+    groqModel?: string;
+}
+/**
+ * Load AI credentials into the in-memory store on startup.
+ *
+ * Resolution order (both are checked; process.env fills gaps not in the file):
+ *   1. .fw.env at process.cwd()   — written by dashboard Settings
+ *   2. process.env.FLOWWATCH_GROQ_API_KEY / GROQ_API_KEY   — set by consumer
+ *
+ * If the key is found only in process.env it is immediately persisted to
+ * .fw.env so the next restart doesn't need process.env anymore.
+ */
+export declare function loadFlowwatchEnv(): Promise<void>;
+/**
+ * Persist settings to .fw.env and update the in-memory store.
+ * Called from the dashboard Settings API when the user saves their key.
+ */
+export declare function saveFlowwatchEnv(updates: Partial<FlowwatchEnv>): Promise<void>;
+/** API key from store or process.env. Never log or send this to the client. */
+export declare function getGroqApiKey(): string | undefined;
+/** Model from store or process.env. */
+export declare function getGroqModel(): string | undefined;
+/** True if any API key source is available. Safe to send to the client. */
+export declare function isGroqApiKeyConfigured(): boolean;
+export {};

package/dist/utils/flowwatchEnvStore.js

@@ -0,0 +1,145 @@
+/**
+ * Flowwatch environment store — persists AI credentials to `.fw.env` in the
+ * consumer's working directory (process.cwd()), i.e. their project root.
+ *
+ * Priority order on startup:
+ *   1. FLOWWATCH_GROQ_API_KEY / FLOWWATCH_GROQ_MODEL   already in process.env
+ *   2. .fw.env at process.cwd()           written by this module
+ *   → whichever is found first wins; the result is persisted to .fw.env
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const FLOWWATCH_ENV_FILE = ".fw.env";
+/** Single in-memory store for the lifetime of this process. */
+const store = {};
+// ─── Path ────────────────────────────────────────────────────────────────────
+function getFlowwatchEnvPath() {
+    return join(process.cwd(), FLOWWATCH_ENV_FILE);
+}
+// ─── File helpers ─────────────────────────────────────────────────────────────
+function parseEnvFile(content) {
+    const result = {};
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        const value = line.slice(eq + 1).trim();
+        if (key === "FLOWWATCH_GROQ_API_KEY")
+            result.groqApiKey = value;
+        if (key === "FLOWWATCH_GROQ_MODEL")
+            result.groqModel = value;
+    }
+    return result;
+}
+function buildEnvFile(existing, updated) {
+    const kept = existing
+        .split(/\r?\n/)
+        .filter((l) => {
+        const t = l.trim();
+        return !t.startsWith("FLOWWATCH_GROQ_API_KEY=") && !t.startsWith("FLOWWATCH_GROQ_MODEL=");
+    });
+    while (kept.length && !kept[kept.length - 1].trim())
+        kept.pop();
+    if (!kept.length) {
+        kept.push("# Flowwatch AI configuration — auto-generated, do not commit to version control");
+    }
+    if (updated.groqApiKey)
+        kept.push(`FLOWWATCH_GROQ_API_KEY=${updated.groqApiKey}`);
+    if (updated.groqModel)
+        kept.push(`FLOWWATCH_GROQ_MODEL=${updated.groqModel}`);
+    kept.push("");
+    return kept.join("\n");
+}
+async function readEnvFile() {
+    try {
+        return await readFile(getFlowwatchEnvPath(), "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Load AI credentials into the in-memory store on startup.
+ *
+ * Resolution order (both are checked; process.env fills gaps not in the file):
+ *   1. .fw.env at process.cwd()   — written by dashboard Settings
+ *   2. process.env.FLOWWATCH_GROQ_API_KEY / GROQ_API_KEY   — set by consumer
+ *
+ * If the key is found only in process.env it is immediately persisted to
+ * .fw.env so the next restart doesn't need process.env anymore.
+ */
+export async function loadFlowwatchEnv() {
+    const filePath = getFlowwatchEnvPath();
+    // Step 1 — read whatever the file has (may be partial or missing)
+    const raw = await readEnvFile();
+    const parsed = parseEnvFile(raw);
+    if (parsed.groqApiKey)
+        store.groqApiKey = parsed.groqApiKey;
+    if (parsed.groqModel)
+        store.groqModel = parsed.groqModel;
+    // Step 2 — fill any gaps from process.env (ALWAYS checked, even if file exists)
+    const envKey = process.env.FLOWWATCH_GROQ_API_KEY || process.env.GROQ_API_KEY;
+    const envModel = process.env.FLOWWATCH_GROQ_MODEL || process.env.GROQ_MODEL;
+    let needsSave = false;
+    if (!store.groqApiKey && envKey) {
+        store.groqApiKey = envKey;
+        needsSave = true;
+    }
+    if (!store.groqModel && envModel) {
+        store.groqModel = envModel;
+        needsSave = true;
+    }
+    if (store.groqApiKey) {
+        console.log(`[Flowwatch] ✅  Groq API key loaded (config: ${filePath})`);
+        // Persist back so future restarts find the key in the file
+        if (needsSave) {
+            try {
+                await writeFile(filePath, buildEnvFile(raw, store), "utf-8");
+                console.log(`[Flowwatch] ✅  API key saved to ${filePath}`);
+            }
+            catch (err) {
+                console.warn(`[Flowwatch] ⚠️  Could not write ${filePath}: ${err?.message}`);
+            }
+        }
+    }
+    else {
+        console.log(`[Flowwatch] ⚠️  No Groq API key found.\n` +
+            `         • Enter it in the dashboard → Settings → AI Configuration\n` +
+            `         • OR set FLOWWATCH_GROQ_API_KEY in your environment\n` +
+            `         • Config will be saved to: ${filePath}`);
+    }
+}
+/**
+ * Persist settings to .fw.env and update the in-memory store.
+ * Called from the dashboard Settings API when the user saves their key.
+ */
+export async function saveFlowwatchEnv(updates) {
+    if (updates.groqApiKey !== undefined)
+        store.groqApiKey = updates.groqApiKey || undefined;
+    if (updates.groqModel !== undefined)
+        store.groqModel = updates.groqModel || undefined;
+    const existing = await readEnvFile();
+    await writeFile(getFlowwatchEnvPath(), buildEnvFile(existing, store), "utf-8");
+}
+/** API key from store or process.env. Never log or send this to the client. */
+export function getGroqApiKey() {
+    return (store.groqApiKey ||
+        process.env.FLOWWATCH_GROQ_API_KEY ||
+        process.env.GROQ_API_KEY);
+}
+/** Model from store or process.env. */
+export function getGroqModel() {
+    return (store.groqModel ||
+        process.env.FLOWWATCH_GROQ_MODEL ||
+        process.env.GROQ_MODEL ||
+        undefined);
+}
+/** True if any API key source is available. Safe to send to the client. */
+export function isGroqApiKeyConfigured() {
+    return Boolean(getGroqApiKey());
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@pranshulsoni/flowwatch",
+  "version": "1.0.0",
+  "description": "Embedded operations dashboard, workflow runner, feature flags, tracing, error capture, health checks, and AI diagnostics for Express backends.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "express",
+    "backend",
+    "observability",
+    "dashboard",
+    "workflow",
+    "workflows",
+    "feature-flags",
+    "tracing",
+    "error-monitoring",
+    "health-checks",
+    "bullmq",
+    "postgres",
+    "redis",
+    "elasticsearch",
+    "groq",
+    "ai-diagnostics"
+  ],
+  "author": "Pranshul Soni",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-dashboard-static.cjs"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PranshulSoni/FlowWatch.git",
+    "directory": "packages/flowwatch"
+  },
+  "bugs": {
+    "url": "https://github.com/PranshulSoni/FlowWatch/issues"
+  },
+  "homepage": "https://github.com/PranshulSoni/FlowWatch#readme",
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@elastic/elasticsearch": "^8.19.1",
+    "bullmq": "^5.78.1",
+    "express": "^5.2.1",
+    "ioredis": "^5.11.1",
+    "pg": "^8.21.0",
+    "zod": "^4.4.3"
+  }
+}