@pranshulsoni/flowwatch 1.0.0

package/dist/engine/workflows/workflowEngine.js

@@ -0,0 +1,112 @@
+import { insertWorkflow, insertWorkflowExecution } from "../../persistence/repositories/workflows/workflowRepository.js";
+import { addWorkflowJobToQueue } from "../background/queues/workflowQueue.js";
+export function createWorkflowEngine(options) {
+    const { pool, workflowQueue, traceEngine } = options;
+    const registry = new Map();
+    async function workflow(name, steps) {
+        return traceEngine.trace("flowwatch.workflow.register", "workflow_step", async () => {
+            validateWorkflow(name, steps);
+            const workflowSteps = [];
+            for (const step of steps) {
+                workflowSteps.push({
+                    name: step.name,
+                    maxRetries: step.retries ?? 0,
+                });
+            }
+            const insertedWorkflow = await insertWorkflow(pool, {
+                name,
+                steps: workflowSteps,
+            });
+            const registeredWorkflow = {
+                name,
+                steps,
+                dbWorkflow: insertedWorkflow.workflow,
+                dbSteps: insertedWorkflow.steps,
+            };
+            registry.set(name, registeredWorkflow);
+        }, {
+            workflowName: name,
+            stepCount: steps.length,
+        });
+    }
+    function getWorkflow(name) {
+        return registry.get(name);
+    }
+    async function trigger(name, input) {
+        return traceEngine.trace("flowwatch.workflow.trigger", "workflow_step", async () => {
+            const workflow = getWorkflow(name);
+            if (!workflow) {
+                throw new Error(`workflow not found: ${name}`);
+            }
+            const executionSteps = [];
+            for (const step of workflow.dbSteps) {
+                const registeredStep = workflow.steps.find((workflowStep) => {
+                    return workflowStep.name === step.name;
+                });
+                if (!registeredStep) {
+                    throw new Error(`workflow step not found in registry: ${step.name}`);
+                }
+                executionSteps.push({
+                    workflowStepId: step.id,
+                    stepIndex: step.stepIndex,
+                    stepName: step.name,
+                    maxRetries: step.maxRetries,
+                    input: resolveStepInput(registeredStep, input),
+                });
+            }
+            const execution = await insertWorkflowExecution(pool, {
+                workflowId: workflow.dbWorkflow.id,
+                workflowName: workflow.dbWorkflow.name,
+                workflowVersion: workflow.dbWorkflow.version,
+                input,
+                steps: executionSteps,
+            });
+            if (workflowQueue === null) {
+                console.warn(`[Flowwatch] ⚠️  Workflow "${name}" execution recorded but NOT queued — Redis queue unavailable. Upgrade to Redis ≥ 5 to enable background execution.`);
+                return { executionId: execution.executionId };
+            }
+            await addWorkflowJobToQueue(workflowQueue, execution.executionId);
+            return execution;
+        }, {
+            workflowName: name,
+        });
+    }
+    return {
+        workflow,
+        trigger,
+        getWorkflow
+    };
+}
+function resolveStepInput(step, workflowInput) {
+    if (typeof step.input === "function") {
+        return step.input(workflowInput);
+    }
+    if (step.input !== undefined) {
+        return step.input;
+    }
+    return workflowInput;
+}
+function validateWorkflow(name, steps) {
+    if (name.trim().length === 0) {
+        throw new Error("workflow name must be a non-empty string");
+    }
+    if (steps.length === 0) {
+        throw new Error("workflow steps must not be empty");
+    }
+    const stepNames = new Set();
+    for (const step of steps) {
+        if (step.name.trim().length === 0) {
+            throw new Error("workflow step name must be a non-empty string");
+        }
+        if (typeof step.run !== "function") {
+            throw new Error(`workflow step ${step.name} run must be a function`);
+        }
+        if (step.retries !== undefined && (!Number.isInteger(step.retries) || step.retries < 0)) {
+            throw new Error(`workflow step ${step.name} retries must be a non-negative integer`);
+        }
+        if (stepNames.has(step.name)) {
+            throw new Error(`workflow step name must be unique: ${step.name}`);
+        }
+        stepNames.add(step.name);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createFlowwatch } from "./createFlowwatch.js";
+export type { Flowwatch } from "./createFlowwatch.js";
+export type { FlowwatchConfig } from "./types/index.js";
+export type { TriggerWorkflow, WorkflowStep, WorkflowStepHandler } from "./engine/workflows/types.js";
+export type { EvaluateFlag, FlagContext } from "./engine/flags/types.js";
+export type { ActiveTraceSpan, TraceFunction } from "./engine/trace/traceEngine.js";
+export type { TraceSpanType, TraceStatus } from "./persistence/repositories/traces/traceRepository.js";
+export { getCurrentClientIp, getCurrentSpanId, getCurrentTraceId } from "./runtime/tracing/traceContext.js";
+export { createRequestTracingMiddleware } from "./runtime/tracing/tracingMiddleware.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createFlowwatch } from "./createFlowwatch.js";
+export { getCurrentClientIp, getCurrentSpanId, getCurrentTraceId } from "./runtime/tracing/traceContext.js";
+export { createRequestTracingMiddleware } from "./runtime/tracing/tracingMiddleware.js";

package/dist/persistence/cache/redisClient.d.ts

@@ -0,0 +1,2 @@
+import { Redis } from "ioredis";
+export declare function createRedisClient(redisUrl: string): Redis;

package/dist/persistence/cache/redisClient.js

@@ -0,0 +1,4 @@
+import { Redis } from "ioredis";
+export function createRedisClient(redisUrl) {
+    return new Redis(redisUrl);
+}

package/dist/persistence/db/postgres.d.ts

@@ -0,0 +1,3 @@
+import { Pool } from "pg";
+import type { PoolConfig } from "pg";
+export declare function createPostgresPool(config: PoolConfig): Pool;

package/dist/persistence/db/postgres.js

@@ -0,0 +1,4 @@
+import { Pool } from "pg";
+export function createPostgresPool(config) {
+    return new Pool(config);
+}

package/dist/persistence/migrations/migrationRunner.d.ts

@@ -0,0 +1,3 @@
+import type { Pool } from "pg";
+import type { Migration } from "./migrations.js";
+export declare function runMigrations(pool: Pool, migrationsToRun: Migration[]): Promise<void>;

package/dist/persistence/migrations/migrationRunner.js

@@ -0,0 +1,46 @@
+import { withTransaction } from "../transaction.js";
+export async function runMigrations(pool, migrationsToRun) {
+    await createMigrationsTable(pool);
+    await withMigrationLock(pool, async () => {
+        const appliedMigrations = await getAppliedMigrations(pool);
+        for (const migration of migrationsToRun) {
+            if (appliedMigrations.has(migration.name)) {
+                continue;
+            }
+            await withTransaction(pool, async (client) => {
+                await client.query(migration.up);
+                await client.query("INSERT INTO flowwatch_migrations (name) VALUES ($1)", [migration.name]);
+            });
+            appliedMigrations.add(migration.name);
+        }
+    });
+}
+async function withMigrationLock(pool, fn) {
+    const client = await pool.connect();
+    try {
+        await client.query("SELECT pg_advisory_lock(hashtext('flowwatch:migrations'))");
+        return await fn();
+    }
+    finally {
+        await client.query("SELECT pg_advisory_unlock(hashtext('flowwatch:migrations'))");
+        client.release();
+    }
+}
+async function createMigrationsTable(pool) {
+    await pool.query(`
+        CREATE TABLE IF NOT EXISTS flowwatch_migrations (
+            id SERIAL PRIMARY KEY,
+            name TEXT NOT NULL UNIQUE,
+            applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+    `);
+}
+async function getAppliedMigrations(pool) {
+    const result = await pool.query("SELECT name FROM flowwatch_migrations");
+    const migrationNames = [];
+    for (const row of result.rows) {
+        migrationNames.push(row.name);
+    }
+    const appliedMigrations = new Set(migrationNames);
+    return appliedMigrations;
+}

package/dist/persistence/migrations/migrations.d.ts

@@ -0,0 +1,5 @@
+export interface Migration {
+    name: string;
+    up: string;
+}
+export declare const migrations: Migration[];

package/dist/persistence/migrations/migrations.js

@@ -0,0 +1,191 @@
+export const migrations = [
+    {
+        name: "001_create_workflow_tables",
+        up: `CREATE TABLE IF NOT EXISTS flowwatch_workflows (
+  id UUID PRIMARY KEY,
+  name TEXT NOT NULL,
+  version INTEGER NOT NULL DEFAULT 1,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  CONSTRAINT flowwatch_workflows_name_version_unique UNIQUE (name, version)
+);
+
+CREATE TABLE IF NOT EXISTS flowwatch_workflow_steps (
+  id UUID PRIMARY KEY,
+  workflow_id UUID NOT NULL REFERENCES flowwatch_workflows(id) ON DELETE CASCADE,
+  step_index INTEGER NOT NULL,
+  name TEXT NOT NULL,
+  max_retries INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  CONSTRAINT flowwatch_workflow_steps_workflow_step_index_unique UNIQUE (workflow_id, step_index),
+  CONSTRAINT flowwatch_workflow_steps_workflow_name_unique UNIQUE (workflow_id, name)
+);
+
+CREATE TABLE IF NOT EXISTS flowwatch_workflow_executions (
+  id UUID PRIMARY KEY,
+  workflow_id UUID NOT NULL REFERENCES flowwatch_workflows(id),
+  workflow_name TEXT NOT NULL,
+  workflow_version INTEGER NOT NULL,
+  status TEXT NOT NULL,
+  input JSONB,
+  output JSONB,
+  error JSONB,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  started_at TIMESTAMPTZ,
+  completed_at TIMESTAMPTZ,
+  failed_at TIMESTAMPTZ
+);
+
+CREATE TABLE IF NOT EXISTS flowwatch_workflow_step_executions (
+  id UUID PRIMARY KEY,
+  execution_id UUID NOT NULL REFERENCES flowwatch_workflow_executions(id) ON DELETE CASCADE,
+  workflow_step_id UUID REFERENCES flowwatch_workflow_steps(id),
+  step_index INTEGER NOT NULL,
+  step_name TEXT NOT NULL,
+  status TEXT NOT NULL,
+  input JSONB,
+  output JSONB,
+  error JSONB,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  max_retries INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  started_at TIMESTAMPTZ,
+  completed_at TIMESTAMPTZ,
+  failed_at TIMESTAMPTZ,
+  next_retry_at TIMESTAMPTZ,
+
+  CONSTRAINT flowwatch_workflow_step_executions_execution_step_index_unique UNIQUE (execution_id, step_index)
+);
+
+CREATE INDEX IF NOT EXISTS flowwatch_workflow_executions_workflow_status_idx
+ON flowwatch_workflow_executions (workflow_name, status);
+
+CREATE INDEX IF NOT EXISTS flowwatch_workflow_executions_created_at_idx
+ON flowwatch_workflow_executions (created_at DESC);
+
+CREATE INDEX IF NOT EXISTS flowwatch_workflow_step_executions_execution_idx
+ON flowwatch_workflow_step_executions (execution_id, step_index);
+
+CREATE INDEX IF NOT EXISTS flowwatch_workflow_step_executions_status_retry_idx
+ON flowwatch_workflow_step_executions (status, next_retry_at);`
+    },
+    {
+        name: "002_create_feature_flag_tables",
+        up: `CREATE TABLE IF NOT EXISTS flowwatch_feature_flags (
+  id UUID PRIMARY KEY,
+  key TEXT NOT NULL UNIQUE,
+  description TEXT,
+  enabled BOOLEAN NOT NULL DEFAULT false,
+  rollout_percentage INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  CONSTRAINT flowwatch_feature_flags_rollout_percentage_check
+  CHECK (rollout_percentage >= 0 AND rollout_percentage <= 100)
+);
+
+CREATE TABLE IF NOT EXISTS flowwatch_feature_flag_rules (
+  id UUID PRIMARY KEY,
+  flag_id UUID NOT NULL REFERENCES flowwatch_feature_flags(id) ON DELETE CASCADE,
+  attribute TEXT NOT NULL,
+  operator TEXT NOT NULL,
+  value JSONB NOT NULL,
+  enabled BOOLEAN NOT NULL DEFAULT true,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS flowwatch_feature_flag_audit_logs (
+  id UUID PRIMARY KEY,
+  flag_id UUID REFERENCES flowwatch_feature_flags(id) ON DELETE SET NULL,
+  action TEXT NOT NULL,
+  before JSONB,
+  after JSONB,
+  changed_by TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS flowwatch_feature_flag_rules_flag_id_idx
+ON flowwatch_feature_flag_rules (flag_id);
+
+CREATE INDEX IF NOT EXISTS flowwatch_feature_flag_audit_logs_flag_id_created_at_idx
+ON flowwatch_feature_flag_audit_logs (flag_id, created_at DESC);`
+    },
+    {
+        name: "003_create_error_capture_tables",
+        up: `CREATE TABLE IF NOT EXISTS flowwatch_request_traces (
+  id UUID PRIMARY KEY,
+  method TEXT NOT NULL,
+  path TEXT NOT NULL,
+  status_code INTEGER,
+  duration_ms INTEGER,
+  user_id TEXT,
+  ip TEXT,
+  user_agent TEXT,
+  metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+  started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  ended_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS flowwatch_trace_spans (
+  id UUID PRIMARY KEY,
+  trace_id UUID NOT NULL REFERENCES flowwatch_request_traces(id) ON DELETE CASCADE,
+  parent_span_id UUID REFERENCES flowwatch_trace_spans(id) ON DELETE SET NULL,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL,
+  status TEXT NOT NULL,
+  duration_ms INTEGER,
+  metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+  started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  ended_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS flowwatch_errors (
+  id UUID PRIMARY KEY,
+  trace_id UUID REFERENCES flowwatch_request_traces(id) ON DELETE SET NULL,
+  span_id UUID REFERENCES flowwatch_trace_spans(id) ON DELETE SET NULL,
+  source TEXT NOT NULL,
+  category TEXT NOT NULL,
+  level TEXT NOT NULL DEFAULT 'error',
+  message TEXT NOT NULL,
+  stack TEXT,
+  name TEXT,
+  status_code INTEGER,
+  fingerprint TEXT,
+  metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+  occurred_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS flowwatch_request_traces_started_at_idx
+ON flowwatch_request_traces (started_at DESC);
+
+CREATE INDEX IF NOT EXISTS flowwatch_request_traces_path_status_idx
+ON flowwatch_request_traces (path, status_code);
+
+CREATE INDEX IF NOT EXISTS flowwatch_trace_spans_trace_started_at_idx
+ON flowwatch_trace_spans (trace_id, started_at ASC);
+
+CREATE INDEX IF NOT EXISTS flowwatch_trace_spans_parent_span_id_idx
+ON flowwatch_trace_spans (parent_span_id);
+
+CREATE INDEX IF NOT EXISTS flowwatch_errors_trace_id_idx
+ON flowwatch_errors (trace_id);
+
+CREATE INDEX IF NOT EXISTS flowwatch_errors_span_id_idx
+ON flowwatch_errors (span_id);
+
+CREATE INDEX IF NOT EXISTS flowwatch_errors_source_category_idx
+ON flowwatch_errors (source, category);
+
+CREATE INDEX IF NOT EXISTS flowwatch_errors_occurred_at_idx
+ON flowwatch_errors (occurred_at DESC);
+
+CREATE INDEX IF NOT EXISTS flowwatch_errors_fingerprint_idx
+ON flowwatch_errors (fingerprint);`
+    }
+];

package/dist/persistence/repositories/errors/errorRepository.d.ts

@@ -0,0 +1,38 @@
+import type { Pool } from "pg";
+export type ErrorSource = "http" | "workflow" | "feature_flag" | "background_worker" | "dashboard_api" | "unknown";
+export type ErrorCategory = "client" | "server" | "dependency" | "database" | "configuration" | "unknown";
+export type ErrorLevel = "warning" | "error" | "fatal";
+export interface ErrorRow {
+    id: string;
+    trace_id: string | null;
+    span_id: string | null;
+    source: ErrorSource;
+    category: ErrorCategory;
+    level: ErrorLevel;
+    message: string;
+    stack: string | null;
+    name: string | null;
+    status_code: number | null;
+    fingerprint: string | null;
+    metadata: unknown;
+    occurred_at: Date;
+    created_at: Date;
+}
+export interface CreateErrorInput {
+    traceId?: string;
+    spanId?: string;
+    source: ErrorSource;
+    category: ErrorCategory;
+    level?: ErrorLevel;
+    message: string;
+    stack?: string;
+    name?: string;
+    statusCode?: number;
+    fingerprint?: string;
+    metadata?: unknown;
+    occurredAt?: Date;
+}
+export declare function createError(pool: Pool, input: CreateErrorInput): Promise<ErrorRow>;
+export declare function getErrorsByTrace(pool: Pool, traceId: string): Promise<ErrorRow[]>;
+export declare function getErrorById(pool: Pool, errorId: string): Promise<ErrorRow | undefined>;
+export declare function listErrors(pool: Pool, limit?: number): Promise<ErrorRow[]>;

package/dist/persistence/repositories/errors/errorRepository.js

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+export async function createError(pool, input) {
+    const result = await pool.query(`
+        INSERT INTO flowwatch_errors (
+            id,
+            trace_id,
+            span_id,
+            source,
+            category,
+            level,
+            message,
+            stack,
+            name,
+            status_code,
+            fingerprint,
+            metadata,
+            occurred_at
+        )
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12::jsonb, $13)
+        RETURNING *
+        `, [
+        randomUUID(),
+        input.traceId ?? null,
+        input.spanId ?? null,
+        input.source,
+        input.category,
+        input.level ?? "error",
+        input.message,
+        input.stack ?? null,
+        input.name ?? null,
+        input.statusCode ?? null,
+        input.fingerprint ?? null,
+        JSON.stringify(input.metadata ?? {}),
+        input.occurredAt ?? new Date(),
+    ]);
+    return result.rows[0];
+}
+export async function getErrorsByTrace(pool, traceId) {
+    const result = await pool.query(`
+        SELECT *
+        FROM flowwatch_errors
+        WHERE trace_id = $1
+        ORDER BY occurred_at DESC
+        `, [traceId]);
+    return result.rows;
+}
+export async function getErrorById(pool, errorId) {
+    const result = await pool.query(`
+        SELECT *
+        FROM flowwatch_errors
+        WHERE id = $1
+        `, [errorId]);
+    return result.rows[0];
+}
+export async function listErrors(pool, limit = 50) {
+    const result = await pool.query(`
+        SELECT *
+        FROM flowwatch_errors
+        ORDER BY occurred_at DESC
+        LIMIT $1
+        `, [limit]);
+    return result.rows;
+}

package/dist/persistence/repositories/flags/flagRepository.d.ts

@@ -0,0 +1,72 @@
+import type { Pool } from "pg";
+export type FlagRuleOperator = "equals" | "not_equals" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | "greater_than" | "less_than";
+export interface FeatureFlagRow {
+    id: string;
+    key: string;
+    description: string | null;
+    enabled: boolean;
+    rollout_percentage: number;
+    created_at: Date;
+    updated_at: Date;
+}
+export interface FeatureFlagRuleRow {
+    id: string;
+    flag_id: string;
+    attribute: string;
+    operator: FlagRuleOperator;
+    value: unknown;
+    enabled: boolean;
+    created_at: Date;
+    updated_at: Date;
+}
+export interface FeatureFlagAuditLogRow {
+    id: string;
+    flag_id: string | null;
+    action: string;
+    before: unknown;
+    after: unknown;
+    changed_by: string | null;
+    created_at: Date;
+}
+export interface FeatureFlagWithRuleCountRow extends FeatureFlagRow {
+    rule_count: number;
+}
+export interface CreateFlagInput {
+    key: string;
+    description?: string;
+    enabled?: boolean;
+    rolloutPercentage?: number;
+    changedBy?: string;
+}
+export interface UpdateFlagInput {
+    description?: string | null;
+    enabled?: boolean;
+    rolloutPercentage?: number;
+    changedBy?: string;
+}
+export interface CreateFlagRuleInput {
+    flagKey: string;
+    attribute: string;
+    operator: FlagRuleOperator;
+    value: unknown;
+    enabled?: boolean;
+    changedBy?: string;
+}
+export interface UpdateFlagRuleInput {
+    attribute?: string;
+    operator?: FlagRuleOperator;
+    value?: unknown;
+    enabled?: boolean;
+    changedBy?: string;
+}
+export declare function createFlag(pool: Pool, input: CreateFlagInput): Promise<FeatureFlagRow>;
+export declare function listFlags(pool: Pool): Promise<FeatureFlagRow[]>;
+export declare function listFlagsWithRuleCounts(pool: Pool): Promise<FeatureFlagWithRuleCountRow[]>;
+export declare function getFlagByKey(pool: Pool, key: string): Promise<FeatureFlagRow | undefined>;
+export declare function updateFlag(pool: Pool, key: string, input: UpdateFlagInput): Promise<FeatureFlagRow | undefined>;
+export declare function deleteFlag(pool: Pool, key: string, changedBy?: string): Promise<boolean>;
+export declare function listFlagRules(pool: Pool, flagKey: string): Promise<FeatureFlagRuleRow[]>;
+export declare function createFlagRule(pool: Pool, input: CreateFlagRuleInput): Promise<FeatureFlagRuleRow | undefined>;
+export declare function updateFlagRule(pool: Pool, ruleId: string, input: UpdateFlagRuleInput): Promise<FeatureFlagRuleRow | undefined>;
+export declare function deleteFlagRule(pool: Pool, ruleId: string, changedBy?: string): Promise<boolean>;
+export declare function listFlagAuditLogs(pool: Pool, flagKey: string): Promise<FeatureFlagAuditLogRow[]>;