gateops-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,725 @@
+import { Express } from 'express';
+import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
+import * as express_serve_static_core from 'express-serve-static-core';
+
+/**
+ * Traffic log entry stored in database and sent to Panel
+ */
+interface TrafficLog {
+    id?: number;
+    trace_id: string;
+    endpoint: string;
+    method: string;
+    status: number;
+    duration_ms: number;
+    req_headers?: string;
+    req_body?: string;
+    res_headers?: string;
+    res_body?: string;
+    query_params?: string;
+    ip_address?: string;
+    user_agent?: string;
+    created_at: Date;
+}
+/**
+ * Discovered endpoint/route information
+ */
+interface EndpointInfo {
+    id?: number;
+    path: string;
+    method: string;
+    detected_schema?: string;
+    middleware_names?: string;
+    last_seen: Date;
+}
+/**
+ * GateOps SDK initialization options
+ */
+interface GateOpsOptions {
+    /**
+     * Enable/disable the SDK (default: true)
+     * Can also be set via GATEOPS_ENABLED env var
+     */
+    enabled?: boolean;
+    /**
+     * Custom database path (default: .gateops/data.sqlite)
+     * Can also be set via GATEOPS_DB_PATH env var
+     */
+    dbPath?: string;
+    /**
+     * Buffer size before auto-flush (default: 50)
+     */
+    bufferSize?: number;
+    /**
+     * Buffer flush interval in ms (default: 10000)
+     */
+    flushInterval?: number;
+    /**
+     * Max body size to capture in bytes (default: 10KB)
+     */
+    maxBodySize?: number;
+    /**
+     * Additional fields to redact (merged with defaults)
+     */
+    sensitiveFields?: string[];
+    /**
+     * Paths to exclude from logging (e.g., ['/health', '/metrics'])
+     */
+    excludePaths?: string[];
+    /**
+     * Enable exposed routes for Panel queries (default: true)
+     */
+    exposeRoutes?: boolean;
+    /**
+     * Disable sending logs to Panel (local-only mode)
+     */
+    localOnly?: boolean;
+    /**
+     * Custom Panel URL (default: https://gateops.sleeksoulsmedia.com)
+     */
+    panelUrl?: string;
+}
+/**
+ * Route layer from Express router stack
+ */
+interface RouteLayer {
+    name: string;
+    handle: Function;
+    regexp: RegExp;
+    route?: {
+        path: string;
+        methods: Record<string, boolean>;
+        stack: RouteLayer[];
+    };
+    keys?: {
+        name: string;
+    }[];
+    path?: string;
+}
+/**
+ * Express app with internal router access
+ */
+interface ExpressApp {
+    _router?: {
+        stack: RouteLayer[];
+    };
+    use: Function;
+    listen: Function;
+}
+/**
+ * Panel API response for verification
+ */
+interface VerifyResponse {
+    success: boolean;
+    message?: string;
+    projectId?: string;
+    projectName?: string;
+}
+/**
+ * Panel API response for log submission
+ */
+interface LogSubmitResponse {
+    success: boolean;
+    received: number;
+    message?: string;
+}
+
+/**
+ * Sanitize data by redacting sensitive fields
+ *
+ * - Recursively traverses objects and arrays
+ * - Redacts fields matching sensitive patterns
+ * - Masks credit card numbers and SSNs
+ * - Truncates large payloads
+ */
+declare function sanitize(data: unknown, maxSize?: number, customFields?: string[]): unknown;
+/**
+ * Safely stringify an object, handling circular references
+ */
+declare function safeStringify(obj: unknown, maxSize?: number): string | undefined;
+/**
+ * Extract safe headers (remove sensitive ones)
+ */
+declare function sanitizeHeaders(headers: Record<string, string | string[] | undefined>): Record<string, string | string[] | undefined>;
+
+/**
+ * Traffic logs table - stores all captured API requests/responses
+ *
+ * TTL: 15 days (cleanup handled by SDK)
+ */
+declare const trafficLogs: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
+    name: "gateops_traffic_logs";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "id";
+            tableName: "gateops_traffic_logs";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            enumValues: undefined;
+            baseColumn: never;
+        }, object>;
+        trace_id: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "trace_id";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        endpoint: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "endpoint";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        method: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "method";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        status: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "status";
+            tableName: "gateops_traffic_logs";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+        }, object>;
+        duration_ms: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "duration_ms";
+            tableName: "gateops_traffic_logs";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+        }, object>;
+        req_headers: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "req_headers";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        res_headers: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "res_headers";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        req_body: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "req_body";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        res_body: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "res_body";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        query_params: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "query_params";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        ip_address: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "ip_address";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        user_agent: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "user_agent";
+            tableName: "gateops_traffic_logs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        created_at: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "created_at";
+            tableName: "gateops_traffic_logs";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+        }, object>;
+    };
+    dialect: "sqlite";
+}>;
+/**
+ * Endpoints table - stores discovered routes for documentation
+ *
+ * Updated on each app startup + when new routes are hit
+ */
+declare const endpoints: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
+    name: "gateops_endpoints";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "id";
+            tableName: "gateops_endpoints";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            enumValues: undefined;
+            baseColumn: never;
+        }, object>;
+        path: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "path";
+            tableName: "gateops_endpoints";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        method: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "method";
+            tableName: "gateops_endpoints";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        detected_schema: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "detected_schema";
+            tableName: "gateops_endpoints";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        middleware_names: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "middleware_names";
+            tableName: "gateops_endpoints";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        last_seen: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "last_seen";
+            tableName: "gateops_endpoints";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+        }, object>;
+    };
+    dialect: "sqlite";
+}>;
+/**
+ * Config table - key/value store for SDK configuration
+ *
+ * Used for storing latency rules, custom settings, etc.
+ */
+declare const config: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
+    name: "gateops_config";
+    schema: undefined;
+    columns: {
+        key: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "key";
+            tableName: "gateops_config";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        value: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "value";
+            tableName: "gateops_config";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+        }, object>;
+        updated_at: drizzle_orm_sqlite_core.SQLiteColumn<{
+            name: "updated_at";
+            tableName: "gateops_config";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+        }, object>;
+    };
+    dialect: "sqlite";
+}>;
+type TrafficLogInsert = typeof trafficLogs.$inferInsert;
+type TrafficLogSelect = typeof trafficLogs.$inferSelect;
+type EndpointInsert = typeof endpoints.$inferInsert;
+type EndpointSelect = typeof endpoints.$inferSelect;
+type ConfigInsert = typeof config.$inferInsert;
+type ConfigSelect = typeof config.$inferSelect;
+
+type schema_ConfigInsert = ConfigInsert;
+type schema_ConfigSelect = ConfigSelect;
+type schema_EndpointInsert = EndpointInsert;
+type schema_EndpointSelect = EndpointSelect;
+type schema_TrafficLogInsert = TrafficLogInsert;
+type schema_TrafficLogSelect = TrafficLogSelect;
+declare const schema_config: typeof config;
+declare const schema_endpoints: typeof endpoints;
+declare const schema_trafficLogs: typeof trafficLogs;
+declare namespace schema {
+  export { type schema_ConfigInsert as ConfigInsert, type schema_ConfigSelect as ConfigSelect, type schema_EndpointInsert as EndpointInsert, type schema_EndpointSelect as EndpointSelect, type schema_TrafficLogInsert as TrafficLogInsert, type schema_TrafficLogSelect as TrafficLogSelect, schema_config as config, schema_endpoints as endpoints, schema_trafficLogs as trafficLogs };
+}
+
+/**
+ * Get or create the database connection
+ */
+declare function getDatabase(dbPath?: string): BetterSQLite3Database<typeof schema>;
+/**
+ * Initialize database schema (create tables if not exist)
+ */
+declare function initializeSchema(database?: BetterSQLite3Database<typeof schema>): void;
+/**
+ * Close database connection
+ */
+declare function closeDatabase(): void;
+/**
+ * Clean up old logs based on TTL
+ */
+declare function cleanupOldLogs(ttlDays?: number): number;
+
+/**
+ * Route Scanner - Discovery Engine
+ *
+ * Scans Express app router stack to extract all registered routes.
+ * Runs on app startup to populate the endpoints table.
+ */
+/**
+ * Scan all routes from an Express app
+ */
+declare function scanRoutes(app: Express | ExpressApp): EndpointInfo[];
+/**
+ * Sync discovered routes to database
+ */
+declare function syncRoutesToDatabase(routes: EndpointInfo[]): Promise<void>;
+/**
+ * Get all endpoints from database
+ */
+declare function getEndpoints(): Promise<EndpointInfo[]>;
+
+/**
+ * Panel Sync Module
+ *
+ * Handles communication with the GateOps Panel API.
+ */
+/**
+ * Verify credentials with the Panel
+ */
+declare function verifyCredentials(username: string, apiKey: string): Promise<VerifyResponse>;
+/**
+ * Send logs to the Panel
+ */
+declare function sendLogs(logs: TrafficLog[], username: string, apiKey: string, retryCount?: number): Promise<LogSubmitResponse>;
+/**
+ * Send discovered endpoints to the Panel
+ */
+declare function sendEndpoints(routes: EndpointInfo[], username: string, apiKey: string): Promise<boolean>;
+
+/**
+ * Buffer Manager - handles in-memory buffering with disk overflow
+ *
+ * Features:
+ * - In-memory buffer with configurable size
+ * - Auto-flush on size threshold or interval
+ * - Dual write: local DB + Panel API
+ * - Disk persistence for crash recovery
+ */
+declare class BufferManager {
+    private buffer;
+    private flushInterval;
+    private isInitialized;
+    private isFlushing;
+    private maxSize;
+    private intervalMs;
+    private localOnly;
+    private username;
+    private apiKey;
+    constructor();
+    /**
+     * Initialize the buffer manager
+     */
+    initialize(options?: {
+        maxSize?: number;
+        intervalMs?: number;
+        localOnly?: boolean;
+        username?: string;
+        apiKey?: string;
+    }): void;
+    /**
+     * Push a log entry to the buffer
+     */
+    push(log: TrafficLog): void;
+    /**
+     * Flush the buffer to database and Panel
+     */
+    flush(): Promise<void>;
+    /**
+     * Write logs to local SQLite database
+     */
+    private writeToDatabase;
+    /**
+     * Send logs to Panel API
+     */
+    private sendToPanel;
+    /**
+     * Recover logs from disk buffer
+     */
+    private recoverFromDisk;
+    /**
+     * Start the periodic flush interval
+     */
+    private startFlushInterval;
+    /**
+     * Register handlers for graceful shutdown
+     */
+    private registerShutdownHandlers;
+    /**
+     * Get current buffer size
+     */
+    getSize(): number;
+    /**
+     * Shutdown the buffer manager
+     */
+    shutdown(): void;
+}
+declare const buffer: BufferManager;
+
+/**
+ * GateOps Exposed Routes
+ *
+ * Routes exposed on the user's Express app for Panel to query.
+ * All routes are prefixed with /.well-known/gateops/
+ *
+ * Authentication: x-gateops-username + x-gateops-api-key headers
+ */
+declare const router: express_serve_static_core.Router;
+
+/**
+ * Panel API Endpoints
+ *
+ * Modify these paths if the Panel API structure changes.
+ * All paths are relative to PANEL_BASE_URL.
+ */
+declare const PANEL_ENDPOINTS: {
+    readonly VERIFY: "/api/sdk/verify";
+    readonly LOGS: "/api/sdk/logs";
+    readonly CONFIG: "/api/sdk/config";
+    readonly ENDPOINTS: "/api/sdk/endpoints";
+    readonly HEARTBEAT: "/api/sdk/heartbeat";
+};
+/**
+ * SDK Default Configuration
+ */
+declare const SDK_DEFAULTS: {
+    readonly BUFFER_MAX_SIZE: 50;
+    readonly BUFFER_FLUSH_INTERVAL: 10000;
+    readonly MAX_BODY_SIZE: 10240;
+    readonly LOG_TTL_DAYS: 15;
+    readonly MAX_RETRY_ATTEMPTS: 3;
+    readonly RETRY_DELAY_BASE: 1000;
+    readonly DEFAULT_DB_PATH: ".gateops/data.sqlite";
+    readonly BUFFER_FILE_PATH: ".gateops/buffer.json";
+    readonly ROUTE_PREFIX: "/.well-known/gateops";
+};
+/**
+ * Get full Panel endpoint URL
+ */
+declare function getPanelUrl(endpoint: keyof typeof PANEL_ENDPOINTS): string;
+
+/**
+ * GateOps SDK - Lightweight API Observability for Express.js
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import gateops from 'gateops-core';
+ *
+ * const app = express();
+ *
+ * // Initialize GateOps middleware
+ * app.use(gateops.init());
+ *
+ * // Your routes...
+ * app.get('/api/users', (req, res) => { ... });
+ *
+ * app.listen(3000);
+ * ```
+ */
+
+/**
+ * Initialize GateOps SDK
+ *
+ * Returns an Express middleware that captures all API traffic.
+ *
+ * @param options - Configuration options
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * app.use(gateops.init());
+ *
+ * // With options
+ * app.use(gateops.init({
+ *   excludePaths: ['/health', '/metrics'],
+ *   sensitiveFields: ['customSecret'],
+ *   localOnly: true // Don't send to Panel
+ * }));
+ * ```
+ */
+declare function init(options?: GateOpsOptions): (req: any, res: any, next: any) => void;
+/**
+ * Scan and register all routes from an Express app
+ *
+ * Call this after all routes are registered, typically
+ * right before `app.listen()`.
+ *
+ * @param app - Express application instance
+ *
+ * @example
+ * ```typescript
+ * // Register routes first
+ * app.use('/api', apiRouter);
+ *
+ * // Then scan
+ * gateops.scan(app);
+ *
+ * app.listen(3000);
+ * ```
+ */
+declare function scan(app: Express): Promise<void>;
+/**
+ * Manually flush the log buffer
+ *
+ * Useful for testing or before graceful shutdown.
+ */
+declare function flush(): Promise<void>;
+/**
+ * Shutdown GateOps SDK
+ *
+ * Call this before application exit for graceful shutdown.
+ */
+declare function shutdown(): void;
+declare const gateops: {
+    init: typeof init;
+    scan: typeof scan;
+    flush: typeof flush;
+    shutdown: typeof shutdown;
+};
+
+export { type EndpointInfo, type GateOpsOptions, PANEL_ENDPOINTS, SDK_DEFAULTS, type TrafficLog, buffer, cleanupOldLogs, closeDatabase, gateops as default, flush, router as gateopsRouter, getDatabase, getEndpoints, getPanelUrl, init, initializeSchema, safeStringify, sanitize, sanitizeHeaders, scan, scanRoutes, sendEndpoints, sendLogs, shutdown, syncRoutesToDatabase, verifyCredentials };