@everystack/events 0.1.0

package/src/schema.ts

@@ -0,0 +1,140 @@
+/**
+ * Events schema — WebSocket connections are now auth.sessions
+ *
+ * A WebSocket connection IS a session: domain='ws', status='active',
+ * data={connectionId, channels}, lastUsedAt=lastPingAt.
+ *
+ * On disconnect: status='disconnected', endedAt=now().
+ *
+ * Table definition copied locally to avoid TS6059 rootDir issues
+ * with cross-package re-exports during ts-jest compilation.
+ *
+ * @see everyschema — canonical schema definitions
+ */
+
+import {
+  pgSchema,
+  text,
+  timestamp,
+  uuid,
+  integer,
+  index,
+  uniqueIndex,
+  jsonb,
+  boolean,
+} from 'drizzle-orm/pg-core';
+
+const authSchema = pgSchema('auth');
+
+// =============================================================================
+// SESSIONS (auth.sessions — unified STI)
+// =============================================================================
+
+/**
+ * Unified sessions table. Copied from @everystack/auth/schema.
+ *
+ * For events package: domain='ws'
+ *   data: { connectionId, channels }
+ */
+export const sessions = authSchema.table(
+  'sessions',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+
+    // STI discriminator
+    domain: text('domain').notNull(), // 'auth' | 'work' | 'agent' | 'ws'
+    type: text('type'), // auth sub-types: 'device' | 'web' | 'refresh' (NULL for work/agent/ws)
+
+    // Actor
+    userId: uuid('user_id'),
+    agentId: text('agent_id'),
+
+    // Context
+    repositoryId: uuid('repository_id'),
+    deviceId: uuid('device_id'),
+
+    // Auth: session token
+    tokenHash: text('token_hash').unique(),
+
+    // Status (shared across domains, different values per domain)
+    status: text('status').notNull().default('active'),
+
+    // Auth: lifecycle timestamps
+    expiresAt: timestamp('expires_at', { withTimezone: true }),
+    lastUsedAt: timestamp('last_used_at', { withTimezone: true }),
+    revokedAt: timestamp('revoked_at', { withTimezone: true }),
+
+    // Auth: security context
+    ipAddress: text('ip_address'),
+    userAgent: text('user_agent'),
+
+    // Work/agent: lifecycle
+    startedAt: timestamp('started_at', { withTimezone: true }),
+    endedAt: timestamp('ended_at', { withTimezone: true }),
+
+    // Agent: counters
+    toolCallCount: integer('tool_call_count'),
+    errorCount: integer('error_count'),
+
+    // Domain-specific data
+    data: jsonb('data'),
+
+    // Timestamps
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => ({
+    domainIdx: index('sessions_domain_idx').on(table.domain),
+    domainUserIdx: index('sessions_domain_user_idx').on(table.domain, table.userId),
+    domainAgentStatusIdx: index('sessions_domain_agent_status_idx').on(table.domain, table.agentId, table.status),
+    typeIdx: index('sessions_type_idx').on(table.type),
+    userIdx: index('sessions_user_idx').on(table.userId),
+    deviceIdx: index('sessions_device_idx').on(table.deviceId),
+    tokenIdx: uniqueIndex('sessions_token_idx').on(table.tokenHash),
+    statusIdx: index('sessions_status_idx').on(table.status),
+    expiresIdx: index('sessions_expires_idx').on(table.expiresAt),
+    repoIdx: index('sessions_repo_idx').on(table.repositoryId),
+    createdIdx: index('sessions_created_idx').on(table.createdAt),
+  })
+);
+
+// =============================================================================
+// EVENT ACTIONS (ops.event_actions — data-driven event routing)
+// =============================================================================
+
+const opsSchema = pgSchema('ops');
+
+/**
+ * Event actions define what happens when a database event occurs.
+ * Loaded by the listener on startup, cached in memory, reloaded on change.
+ *
+ * tenant_id: NULL = platform-wide, non-NULL = tenant-scoped
+ * operation: 'insert' | 'update' | 'delete' | '*'
+ * action_type: 'rpc' | 'job' | 'cache_purge' | 'webhook'
+ * config: action-specific JSONB (discriminated union keyed by action_type)
+ * filter: optional row conditions for conditional firing
+ */
+export const eventActions = opsSchema.table(
+  'event_actions',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    tenantId: uuid('tenant_id'),
+    name: text('name').notNull(),
+    schemaName: text('schema_name').notNull().default('public'),
+    tableName: text('table_name').notNull(),
+    operation: text('operation').notNull(),
+    actionType: text('action_type').notNull(),
+    config: jsonb('config').notNull().default('{}'),
+    filter: jsonb('filter'),
+    enabled: boolean('enabled').notNull().default(true),
+    priority: integer('priority').notNull().default(0),
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow(),
+  },
+  (table) => ({
+    lookupIdx: index('event_actions_lookup_idx').on(
+      table.schemaName, table.tableName, table.operation, table.enabled
+    ),
+    tenantIdx: index('event_actions_tenant_idx').on(table.tenantId),
+    enabledIdx: index('event_actions_enabled_idx').on(table.enabled),
+  })
+);

package/src/triggers.ts

@@ -0,0 +1,54 @@
+const NOTIFY_FUNCTION = `\
+CREATE OR REPLACE FUNCTION everystack_notify() RETURNS trigger AS $$
+BEGIN
+  PERFORM pg_notify(
+    'events',
+    json_build_object(
+      'schema', TG_TABLE_SCHEMA,
+      'table', TG_TABLE_NAME,
+      'op', lower(TG_OP),
+      'id', COALESCE(NEW.id, OLD.id)
+    )::text
+  );
+  RETURN COALESCE(NEW, OLD);
+END;
+$$ LANGUAGE plpgsql;`;
+
+function triggerSQL(table: string): string {
+  const name = `${table}_events`;
+  return `\
+DROP TRIGGER IF EXISTS ${name} ON ${table};
+CREATE TRIGGER ${name}
+  AFTER INSERT OR UPDATE OR DELETE ON ${table}
+  FOR EACH ROW EXECUTE FUNCTION everystack_notify();`;
+}
+
+export function generateTriggerSQL(tables: string[]): string {
+  if (tables.length === 0) {
+    throw new Error('generateTriggerSQL requires at least one table');
+  }
+
+  const parts = [NOTIFY_FUNCTION, ''];
+  for (const table of tables) {
+    parts.push(triggerSQL(table));
+    parts.push('');
+  }
+
+  return parts.join('\n').trimEnd() + '\n';
+}
+
+export function generateEventActionsTriggerSQL(): string {
+  return `\
+CREATE OR REPLACE FUNCTION everystack_event_actions_notify() RETURNS trigger AS $$
+BEGIN
+  PERFORM pg_notify('_event_actions', '{}');
+  RETURN COALESCE(NEW, OLD);
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS event_actions_notify ON ops.event_actions;
+CREATE TRIGGER event_actions_notify
+  AFTER INSERT OR UPDATE OR DELETE ON ops.event_actions
+  FOR EACH ROW EXECUTE FUNCTION everystack_event_actions_notify();
+`;
+}

package/src/types.ts

@@ -0,0 +1,129 @@
+// --- Core ---
+
+export interface EventPayload {
+  schema?: string; // defaults to 'public' if absent (backwards compat)
+  table: string;
+  op: 'insert' | 'update' | 'delete' | string;
+  id: string;
+}
+
+export interface EventSignal extends EventPayload {
+  channel: string;
+  ts: number;
+}
+
+// --- Listener ---
+
+export interface WebSocketRoute {
+  endpoint: string;
+  region: string;
+}
+
+export interface LambdaRoute {
+  functionName?: string;
+  functionArn?: string;
+}
+
+export interface ListenerRoutes {
+  websocket?: WebSocketRoute;
+  lambda?: Record<string, LambdaRoute>;
+  callbacks?: Record<string, (event: EventPayload) => Promise<void>>;
+}
+
+export interface EventActionsOptions {
+  workerFunctionName?: string;
+  defaultKvsArn?: string | null;
+}
+
+export interface ListenerOptions {
+  connectionString: string;
+  channels?: string[];
+  lockId?: number;
+  routes: ListenerRoutes;
+  reconcile?: (db: unknown) => Promise<void>;
+  heartbeatInterval?: number;
+  eventActions?: EventActionsOptions;
+}
+
+// --- Subscription (internal NOTIFY payloads) ---
+
+export type SubAction =
+  | { action: 'connect'; connectionId: string; channels: string[] }
+  | { action: 'disconnect'; connectionId: string }
+  | { action: 'subscribe'; connectionId: string; channels: string[] }
+  | { action: 'unsubscribe'; connectionId: string; channels: string[] };
+
+// --- Client ---
+
+export interface EventsClientOptions {
+  url: string;
+  getToken: () => string | null;
+  reconnectDelay?: number;
+  pingInterval?: number;
+}
+
+export interface EventsClient {
+  connect(): void;
+  disconnect(): void;
+  on(channel: string, callback: (signal: EventSignal) => void): () => void;
+  subscribe(channels: string[]): void;
+  unsubscribe(channels: string[]): void;
+}
+
+// --- WebSocket Handler ---
+
+export interface WebSocketHandlerOptions {
+  db: unknown;
+  verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+}
+
+// --- Job Handler ---
+
+export type JobHandler<T = unknown> = (payload: T, job: { id: string; type: string }) => Promise<void>;
+
+export interface JobHandlerOptions {
+  db: unknown;
+  handlers: Record<string, JobHandler>;
+}
+
+// --- Event Actions (data-driven routing) ---
+
+export type EventActionType = 'rpc' | 'job' | 'cache_purge' | 'webhook';
+export type EventOperation = 'insert' | 'update' | 'delete' | '*';
+
+export interface EventAction {
+  id: string;
+  tenantId: string | null;
+  name: string;
+  schemaName: string;
+  tableName: string;
+  operation: EventOperation;
+  actionType: EventActionType;
+  config: Record<string, unknown>;
+  filter: Record<string, unknown> | null;
+  enabled: boolean;
+  priority: number;
+}
+
+export interface RpcActionConfig {
+  function: string;
+  args?: Record<string, unknown>;
+}
+
+export interface JobActionConfig {
+  jobType: string;
+  payload?: Record<string, unknown>;
+  priority?: number;
+  maxAttempts?: number;
+}
+
+export interface CachePurgeActionConfig {
+  paths: string[];
+  kvsArn?: string;
+}
+
+export interface WebhookActionConfig {
+  url: string;
+  method?: string;
+  headers?: Record<string, string>;
+}