@fonderie/events 1.0.1 → 1.0.3

package/brain/outcomes.md

@@ -0,0 +1,34 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/events — outcomes
+
+What this package does to a running app: tables its migrations create,
+rows it seeds, routes it registers. Generated from the migration SQL and
+route tables in source — trust this file instead of reading `dist/` or
+downloading tarballs.
+
+## Database tables (after all migrations)
+
+### `fonderie_event_consumers`
+
+```sql
+event_id                 UUID NOT NULL REFERENCES fonderie_events(id) ON DELETE CASCADE
+consumer                 TEXT NOT NULL
+status                   TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'processing', 'processed', 'failed', 'dead'))
+attempts                 INT NOT NULL DEFAULT 0
+error                    TEXT
+processed_at             TIMESTAMPTZ
+-- PRIMARY KEY (event_id, consumer)
+```
+
+### `fonderie_events`
+
+```sql
+id                       UUID NOT NULL PRIMARY KEY DEFAULT gen_random_uuid()
+type                     TEXT NOT NULL
+payload                  JSONB NOT NULL DEFAULT '{}'
+meta                     JSONB NOT NULL DEFAULT '{}'
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+```
+
+Raw SQL ships in `node_modules/@fonderie/events/dist/migrations/sql/` — read it there if you must; never download tarballs.

package/brain/signatures.md

@@ -0,0 +1,91 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/events — signatures
+
+## @fonderie/events
+
+Subpath exports: `@fonderie/events/migrations`
+
+```ts
+new EventBus(transport: IEventTransport): EventBus
+  .emit<T = unknown>(type: string, payload: T, opts?: { requestId?: string; } | undefined): Promise<void>
+  .on<T = unknown>(type: string, handler: IEventHandler<T>, consumer?: string): void
+  .start(): Promise<void>
+  .stop(): Promise<void>
+
+new EventsModule(config: IEventsConfig): EventsModule
+  .name: "@fonderie/events"
+  .bus: EventBus
+  .install(_app: IFonderieApp): void
+
+interface IEventsConfig {
+    transport: EventTransportConfig;
+}
+
+type EventTransportConfig = {
+    type: 'pg';
+    connectionUrl: string;
+    maxRetries?: number;
+    batchSize?: number;
+    pollInterval?: number;
+} | IEventTransport;
+
+new MemoryTransport(): MemoryTransport
+  .publish(type: string, payload: unknown, meta: IEventMeta): Promise<void>
+  .subscribe(pattern: string, handler: IEventHandler, _consumer: string): void
+  .start(): Promise<void>
+  .stop(): Promise<void>
+
+new PGTransport(config: IPGTransportConfig): PGTransport
+  .subscribe(pattern: string, handler: IEventHandler, consumer: string): void
+  .publish(type: string, payload: unknown, meta: IEventMeta): Promise<void>
+  .start(): Promise<void>
+  .stop(): Promise<void>
+
+interface IEventTransport {
+    publish(type: string, payload: unknown, meta: IEventMeta): Promise<void>;
+    subscribe(type: string, handler: IEventHandler, consumer: string): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+
+interface IPGTransportConfig {
+    connectionUrl: string;
+    maxRetries?: number;
+    batchSize?: number;
+    pollInterval?: number;
+}
+
+function matchesPattern(pattern: string, eventType: string): boolean
+
+interface IEventMeta {
+    id: string;
+    type: string;
+    emittedAt: string;
+    attempts: number;
+    requestId?: string;
+}
+
+type IEventHandler<T = unknown> = (payload: T, meta: IEventMeta) => Promise<void>;
+
+interface IEventRecord {
+    id: string;
+    type: string;
+    payload: Record<string, unknown>;
+    meta: IEventMeta;
+    created_at: Date;
+}
+
+interface IConsumerRecord {
+    event_id: string;
+    consumer: string;
+    status: 'pending' | 'processing' | 'processed' | 'failed' | 'dead';
+    attempts: number;
+    error: string | null;
+    processed_at: Date | null;
+}
+
+const NOTIFICATION_EVENT: "fonderie.notification.send"
+
+type NotificationEvent = typeof NOTIFICATION_EVENT;
+```

package/dist/migrations/sql/001_events.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS fonderie_events (
+	id          UUID        NOT NULL PRIMARY KEY DEFAULT gen_random_uuid(),
+	type        TEXT        NOT NULL,
+	payload     JSONB       NOT NULL DEFAULT '{}',
+	meta        JSONB       NOT NULL DEFAULT '{}',
+	created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS fonderie_events_created_idx
+	ON fonderie_events (created_at);

package/dist/migrations/sql/002_event_consumers.sql

@@ -0,0 +1,25 @@
+-- Drop mutable delivery columns from fonderie_events (no-op on fresh installs)
+ALTER TABLE fonderie_events
+	DROP COLUMN IF EXISTS status,
+	DROP COLUMN IF EXISTS attempts,
+	DROP COLUMN IF EXISTS error,
+	DROP COLUMN IF EXISTS processed_at;
+
+DROP INDEX IF EXISTS fonderie_events_status_idx;
+
+-- Per-consumer delivery tracking
+CREATE TABLE IF NOT EXISTS fonderie_event_consumers (
+	event_id      UUID        NOT NULL REFERENCES fonderie_events(id) ON DELETE CASCADE,
+	consumer      TEXT        NOT NULL,
+	status        TEXT        NOT NULL DEFAULT 'pending'
+	                          CHECK (status IN ('pending', 'processing', 'processed', 'failed', 'dead')),
+	attempts      INT         NOT NULL DEFAULT 0,
+	error         TEXT,
+	processed_at  TIMESTAMPTZ,
+	PRIMARY KEY (event_id, consumer)
+);
+
+-- Partial index — each consumer's poll touches only its own pending rows
+CREATE INDEX IF NOT EXISTS fonderie_event_consumers_poll_idx
+	ON fonderie_event_consumers (consumer, status, event_id)
+	WHERE status IN ('pending', 'failed');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fonderie/events",
-	"version": "1.0.1",
+	"version": "1.0.3",
 	"description": "Event bus for @fonderie-js — memory and PostgreSQL transports built-in, adapter interface for Redis/Kafka/RabbitMQ.",
 	"keywords": [
 		"fonderie-js",
@@ -66,16 +66,17 @@
 	},
 	"files": [
 		"dist",
+		"brain",
 		"LICENSE",
 		"README.md"
 	],
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/fonderie-js/sdk.git",
+		"url": "git+https://github.com/fonderiejs/sdk.git",
 		"directory": "packages/events"
 	},
-	"homepage": "https://github.com/fonderie-js/sdk/tree/main/packages/events#readme",
+	"homepage": "https://github.com/fonderiejs/sdk/tree/main/packages/events#readme",
 	"bugs": {
-		"url": "https://github.com/fonderie-js/sdk/issues"
+		"url": "https://github.com/fonderiejs/sdk/issues"
 	}
 }