@everystack/events 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @everystack/events
+
+PostgreSQL LISTEN/NOTIFY bridge for serverless — WebSocket fan-out, Lambda invocation, and real-time subscriptions for Expo apps.
+
+## Install
+
+```bash
+pnpm add @everystack/events
+```
+
+## Entry Points
+
+| Import | Description |
+|--------|-------------|
+| `@everystack/events` | Server: listener, event router |
+| `@everystack/events/triggers` | SQL trigger generation |
+| `@everystack/events/handler` | Lambda handler for WebSocket + event dispatch |
+| `@everystack/events/schema` | Drizzle tables (ws_connections) |
+| `@everystack/events/client` | React hooks (useSubscription) |
+| `@everystack/events/actions` | Server-side event actions |
+
+## Peer Dependencies
+
+- `drizzle-orm` — Database ORM
+- `@aws-sdk/client-apigatewaymanagementapi` — WebSocket push (optional)
+- `@aws-sdk/client-lambda` — Lambda invocation (optional)
+- `@tanstack/react-query` — Client hooks (optional)
+- `react` — Client hooks (optional)
+
+---
+
+Part of [everystack](https://github.com/scalable-technology/everystack) — a self-hosted application stack for Expo apps on AWS.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@everystack/events",
+  "version": "0.1.0",
+  "description": "PostgreSQL LISTEN/NOTIFY bridge for serverless — WebSocket fan-out + Lambda invocation",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./triggers": {
+      "types": "./src/triggers.ts",
+      "default": "./src/triggers.ts"
+    },
+    "./handler": {
+      "types": "./src/handler/index.ts",
+      "default": "./src/handler/index.ts"
+    },
+    "./schema": {
+      "types": "./src/schema.ts",
+      "default": "./src/schema.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    },
+    "./actions": {
+      "types": "./src/actions.ts",
+      "default": "./src/actions.ts"
+    }
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-apigatewaymanagementapi": ">=3.0.0",
+    "@aws-sdk/client-lambda": ">=3.0.0",
+    "@tanstack/react-query": ">=5.0.0",
+    "drizzle-orm": ">=0.30.0",
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-lambda": {
+      "optional": true
+    },
+    "@aws-sdk/client-apigatewaymanagementapi": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-apigatewaymanagementapi": "^3.700.0",
+    "@aws-sdk/client-lambda": "^3.700.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.14",
+    "drizzle-orm": "^0.41.0",
+    "jest": "^29.7.0",
+    "react": "^19.2.6",
+    "ts-jest": "^29.3.0",
+    "typescript": "^5.7.0",
+    "@everystack/auth": "0.1.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,133 @@
+import type { EventPayload, EventAction } from './types';
+
+/**
+ * Match event_actions cache against an incoming event.
+ * Returns matched actions sorted by priority DESC.
+ */
+export function matchEventActions(
+  actions: EventAction[],
+  event: EventPayload,
+): EventAction[] {
+  const eventSchema = event.schema || 'public';
+
+  return actions
+    .filter((a) =>
+      a.enabled &&
+      a.schemaName === eventSchema &&
+      a.tableName === event.table &&
+      (a.operation === '*' || a.operation === event.op)
+    )
+    .sort((a, b) => b.priority - a.priority);
+}
+
+/**
+ * Check if any matched actions need a row fetch.
+ * Row fetch is needed when:
+ * 1. Any config contains {{row.xxx}} template variables
+ * 2. Any action has a non-null tenant_id (for tenant matching)
+ * 3. Any action has a non-null filter
+ */
+export function needsRowFetch(actions: EventAction[]): boolean {
+  for (const action of actions) {
+    if (action.tenantId !== null) return true;
+    if (action.filter !== null) return true;
+    if (configContainsRowTemplate(action.config)) return true;
+  }
+  return false;
+}
+
+function configContainsRowTemplate(obj: unknown): boolean {
+  if (typeof obj === 'string') return obj.includes('{{row.');
+  if (Array.isArray(obj)) return obj.some(configContainsRowTemplate);
+  if (obj && typeof obj === 'object') {
+    return Object.values(obj).some(configContainsRowTemplate);
+  }
+  return false;
+}
+
+/**
+ * Filter actions by tenant_id matching against the fetched row.
+ * Platform-wide actions (tenant_id=null) always pass.
+ * Tenant-scoped actions require row.tenant_id to match.
+ */
+export function filterByTenant(
+  actions: EventAction[],
+  row: Record<string, unknown> | null,
+): EventAction[] {
+  return actions.filter((action) => {
+    if (action.tenantId === null) return true;
+    if (!row) return false;
+    return row.tenant_id === action.tenantId;
+  });
+}
+
+/**
+ * Apply a simple key-value filter against a row.
+ * All keys in the filter must equal the corresponding row value.
+ * Returns true if filter is null (no filtering).
+ */
+export function applyFilter(
+  action: EventAction,
+  row: Record<string, unknown> | null,
+): boolean {
+  if (action.filter === null) return true;
+  if (!row) return false;
+  for (const [key, value] of Object.entries(action.filter)) {
+    if (row[key] !== value) return false;
+  }
+  return true;
+}
+
+/**
+ * Resolve {{...}} template variables in a config value.
+ * Event-level: {{table}}, {{op}}, {{id}}, {{schema}}
+ * Row-level: {{row.fieldName}} — only if row was fetched
+ */
+export function resolveTemplate(
+  value: unknown,
+  event: EventPayload,
+  row: Record<string, unknown> | null,
+): unknown {
+  if (typeof value === 'string') {
+    return value.replace(/\{\{(\w+(?:\.\w+)?)\}\}/g, (match, key: string) => {
+      if (key === 'table') return event.table;
+      if (key === 'op') return event.op;
+      if (key === 'id') return event.id;
+      if (key === 'schema') return event.schema || 'public';
+      if (key.startsWith('row.')) {
+        const field = key.slice(4);
+        return row?.[field] != null ? String(row[field]) : '';
+      }
+      return match;
+    });
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => resolveTemplate(v, event, row));
+  }
+  if (value && typeof value === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = resolveTemplate(v, event, row);
+    }
+    return result;
+  }
+  return value;
+}
+
+/**
+ * In-memory cache for event_actions.
+ * Loaded on startup, reloaded on _event_actions NOTIFY.
+ */
+export function createActionCache(): {
+  get(): EventAction[];
+  set(actions: EventAction[]): void;
+  clear(): void;
+} {
+  let actions: EventAction[] = [];
+
+  return {
+    get(): EventAction[] { return actions; },
+    set(newActions: EventAction[]): void { actions = newActions; },
+    clear(): void { actions = []; },
+  };
+}

package/src/client/index.ts

@@ -0,0 +1,198 @@
+import { createContext, createElement, useContext, useEffect, useRef } from 'react';
+import type { EventsClient, EventsClientOptions, EventSignal } from '../types';
+
+// --- Core WebSocket client (framework-agnostic) ---
+
+export function createEventsClient(options: EventsClientOptions): EventsClient {
+  const {
+    url,
+    getToken,
+    reconnectDelay = 1000,
+    pingInterval = 300000, // 5 minutes
+  } = options;
+
+  // channel → Set<callback>
+  const listeners = new Map<string, Set<(signal: EventSignal) => void>>();
+  let ws: WebSocket | null = null;
+  let intentionalClose = false;
+  let pingTimer: ReturnType<typeof setInterval> | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function getChannels(): string[] {
+    return [...listeners.keys()];
+  }
+
+  function handleMessage(event: { data: string }) {
+    try {
+      const signal = JSON.parse(event.data) as EventSignal;
+      const callbacks = listeners.get(signal.channel);
+      if (callbacks) {
+        for (const cb of callbacks) {
+          cb(signal);
+        }
+      }
+    } catch {
+      // Malformed message — skip
+    }
+  }
+
+  function startPing() {
+    if (pingTimer) clearInterval(pingTimer);
+    pingTimer = setInterval(() => {
+      if (ws?.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ action: 'ping' }));
+      }
+    }, pingInterval);
+  }
+
+  function stopPing() {
+    if (pingTimer) {
+      clearInterval(pingTimer);
+      pingTimer = null;
+    }
+  }
+
+  function scheduleReconnect() {
+    if (intentionalClose) return;
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, reconnectDelay);
+  }
+
+  function connect() {
+    const token = getToken();
+    if (!token) return;
+
+    intentionalClose = false;
+
+    const channels = getChannels();
+    const params = new URLSearchParams({ token });
+    if (channels.length > 0) {
+      params.set('subscribe', channels.join(','));
+    }
+
+    ws = new WebSocket(`${url}?${params.toString()}`);
+
+    ws.onopen = () => {
+      startPing();
+    };
+
+    ws.onmessage = handleMessage;
+
+    ws.onclose = () => {
+      stopPing();
+      scheduleReconnect();
+    };
+
+    ws.onerror = () => {
+      // onclose will fire after onerror
+    };
+  }
+
+  function disconnect() {
+    intentionalClose = true;
+    stopPing();
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    ws?.close();
+  }
+
+  function on(channel: string, callback: (signal: EventSignal) => void): () => void {
+    let callbacks = listeners.get(channel);
+    if (!callbacks) {
+      callbacks = new Set();
+      listeners.set(channel, callbacks);
+    }
+    callbacks.add(callback);
+
+    return () => {
+      callbacks!.delete(callback);
+      if (callbacks!.size === 0) {
+        listeners.delete(channel);
+      }
+    };
+  }
+
+  function subscribe(channels: string[]) {
+    if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ action: 'subscribe', channels }));
+    }
+  }
+
+  function unsubscribe(channels: string[]) {
+    if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ action: 'unsubscribe', channels }));
+    }
+  }
+
+  return { connect, disconnect, on, subscribe, unsubscribe };
+}
+
+// --- React Context ---
+
+const EventsContext = createContext<EventsClient | null>(null);
+
+export function EventsProvider(props: {
+  client: EventsClient;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return createElement(EventsContext.Provider, { value: props.client }, props.children);
+}
+
+export function useEventsClient(): EventsClient | null {
+  return useContext(EventsContext);
+}
+
+// --- useSignal: call a callback when a channel signal arrives ---
+
+export function useSignal(
+  channel: string,
+  callback: (signal: EventSignal) => void,
+): void {
+  const client = useContext(EventsContext);
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!client) return;
+
+    const unsub = client.on(channel, (signal) => {
+      callbackRef.current(signal);
+    });
+
+    return unsub;
+  }, [client, channel]);
+}
+
+// --- useSubscription: React Query cache invalidation on signal ---
+
+export function useSubscription(channel: string, queryKeys: string[]): void {
+  const client = useContext(EventsContext);
+
+  useEffect(() => {
+    if (!client) return;
+
+    // Lazy import — only loaded when useSubscription is actually called
+    let unsub: (() => void) | undefined;
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { useQueryClient } = require('@tanstack/react-query');
+      const queryClient = useQueryClient();
+
+      unsub = client.on(channel, () => {
+        for (const key of queryKeys) {
+          queryClient.invalidateQueries({ queryKey: [key] });
+        }
+      });
+    } catch {
+      // @tanstack/react-query not available — no-op
+    }
+
+    return () => unsub?.();
+  }, [client, channel, ...queryKeys]);
+}

package/src/dispatchers.ts

@@ -0,0 +1,176 @@
+import type {
+  EventPayload, EventAction,
+  RpcActionConfig, JobActionConfig, CachePurgeActionConfig,
+} from './types';
+import { resolveTemplate, filterByTenant, needsRowFetch, applyFilter } from './actions';
+
+// --- Interfaces for injectable dependencies ---
+
+export interface PgClient {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+export interface LambdaClient {
+  invoke(params: unknown): Promise<unknown>;
+}
+
+export interface KvsClient {
+  describe(kvsArn: string): Promise<{ ETag: string }>;
+  put(kvsArn: string, key: string, value: string, etag: string): Promise<void>;
+}
+
+export interface DispatchOptions {
+  workerFunctionName?: string;
+  defaultKvsArn?: string | null;
+}
+
+// --- Individual dispatchers ---
+
+/**
+ * Dispatch an RPC action: invoke worker Lambda with the action payload.
+ */
+export async function dispatchRpc(
+  action: EventAction,
+  event: EventPayload,
+  row: Record<string, unknown> | null,
+  lambdaClient: LambdaClient,
+  workerFunctionName: string,
+): Promise<void> {
+  const resolved = resolveTemplate(action.config, event, row) as RpcActionConfig;
+  await lambdaClient.invoke({
+    FunctionName: workerFunctionName,
+    InvocationType: 'Event',
+    Payload: JSON.stringify({
+      action_type: 'rpc',
+      function: resolved.function,
+      args: resolved.args || {},
+      event,
+      event_action_id: action.id,
+    }),
+  });
+}
+
+/**
+ * Dispatch a Job action: insert into ops.runs with type='job'.
+ */
+export async function dispatchJob(
+  action: EventAction,
+  event: EventPayload,
+  row: Record<string, unknown> | null,
+  pgClient: PgClient,
+): Promise<void> {
+  const resolved = resolveTemplate(action.config, event, row) as JobActionConfig;
+  await pgClient.query(
+    `INSERT INTO ops.runs (type, name, status, priority, queued_at, data)
+     VALUES ('job', $1, 'pending', $2, NOW(), $3)`,
+    [
+      resolved.jobType,
+      resolved.priority ?? 0,
+      JSON.stringify({
+        payload: resolved.payload || {},
+        attempts: 0,
+        maxAttempts: resolved.maxAttempts ?? 3,
+        event_action_id: action.id,
+        source_event: event,
+      }),
+    ]
+  );
+}
+
+/**
+ * Dispatch a cache_purge action: invalidate CloudFront KVS paths.
+ * Lightweight — runs directly in the listener, no Lambda invocation.
+ */
+export async function dispatchCachePurge(
+  action: EventAction,
+  event: EventPayload,
+  row: Record<string, unknown> | null,
+  kvsClient: KvsClient | null,
+  defaultKvsArn: string | null,
+): Promise<void> {
+  const resolved = resolveTemplate(action.config, event, row) as CachePurgeActionConfig;
+  const kvsArn = resolved.kvsArn || defaultKvsArn;
+  if (!kvsArn || !kvsClient) return;
+
+  const desc = await kvsClient.describe(kvsArn);
+  let etag = desc.ETag;
+
+  for (const path of resolved.paths) {
+    await kvsClient.put(kvsArn, path, String(Math.floor(Date.now() / 1000)), etag);
+    // KVS etag changes after each put — re-describe for next iteration
+    const newDesc = await kvsClient.describe(kvsArn);
+    etag = newDesc.ETag;
+  }
+}
+
+// --- Orchestrator ---
+
+/**
+ * Orchestrator: fetch row if needed, filter by tenant + row filter,
+ * dispatch all matched actions.
+ *
+ * Actions are already sorted by priority DESC from matchEventActions.
+ */
+export async function dispatchActions(
+  matched: EventAction[],
+  event: EventPayload,
+  pgClient: PgClient,
+  lambdaClient: LambdaClient,
+  kvsClient: KvsClient | null,
+  options: DispatchOptions,
+): Promise<void> {
+  if (matched.length === 0) return;
+
+  // Lazy row fetch — only if any action needs it
+  let row: Record<string, unknown> | null = null;
+  if (needsRowFetch(matched) && event.op !== 'delete') {
+    const schema = event.schema || 'public';
+    try {
+      const { rows } = await pgClient.query(
+        `SELECT * FROM "${schema}"."${event.table}" WHERE id = $1 LIMIT 1`,
+        [event.id]
+      );
+      row = (rows[0] as Record<string, unknown>) ?? null;
+    } catch {
+      // Table might not have standard id column — skip row fetch
+    }
+  }
+
+  // Tenant filtering
+  let filtered = filterByTenant(matched, row);
+
+  // Row filter
+  filtered = filtered.filter((action) => applyFilter(action, row));
+
+  // Dispatch each action (already sorted by priority)
+  const tasks: Promise<void>[] = [];
+  for (const action of filtered) {
+    switch (action.actionType) {
+      case 'rpc':
+        if (options.workerFunctionName) {
+          tasks.push(
+            dispatchRpc(action, event, row, lambdaClient, options.workerFunctionName)
+              .catch(() => {})
+          );
+        }
+        break;
+      case 'job':
+        tasks.push(
+          dispatchJob(action, event, row, pgClient)
+            .catch(() => {})
+        );
+        break;
+      case 'cache_purge':
+        tasks.push(
+          dispatchCachePurge(action, event, row, kvsClient, options.defaultKvsArn ?? null)
+            .catch(() => {})
+        );
+        break;
+      case 'webhook':
+        // Future: not implemented yet
+        break;
+    }
+  }
+
+  await Promise.allSettled(tasks);
+}