@spfn/core 0.2.0-beta.11 → 0.2.0-beta.13

package/docs/event.md

@@ -1,116 +1,423 @@
 # Event
 
-In-process event system for decoupled communication.
+Decoupled pub/sub event system with SSE support for real-time frontend updates.
 
 ## Define Events
 
 ```typescript
 // src/server/events/index.ts
-import { defineEvent, defineEventHandler } from '@spfn/core/event';
+import { defineEvent } from '@spfn/core/event';
+import { Type } from '@sinclair/typebox';
 
-// Define event types
-export const userCreated = defineEvent<{
-    userId: string;
-    email: string;
-}>('user.created');
+// Event with typed payload
+export const userCreated = defineEvent('user.created', Type.Object({
+    userId: Type.String(),
+    email: Type.String(),
+}));
 
-export const userUpdated = defineEvent<{
-    userId: string;
-    changes: Record<string, any>;
-}>('user.updated');
+export const orderPlaced = defineEvent('order.placed', Type.Object({
+    orderId: Type.String(),
+    amount: Type.Number(),
+}));
 
-export const userDeleted = defineEvent<{
-    userId: string;
-}>('user.deleted');
+// Event without payload
+export const serverStarted = defineEvent('server.started');
 ```
 
-## Emit Events
+## Subscribe & Emit
 
 ```typescript
-import { emit } from '@spfn/core/event';
-import { userCreated } from './events';
+import { userCreated, serverStarted } from './events';
 
-// In repository or service
-async function createUser(data: NewUser)
-{
-    const user = await this._create(users, data);
+// Subscribe to event
+const unsubscribe = userCreated.subscribe((payload) => {
+    console.log('User created:', payload.userId);
+});
 
-    await emit(userCreated, {
-        userId: user.id,
-        email: user.email
-    });
+// Emit event
+await userCreated.emit({ userId: '123', email: 'user@example.com' });
 
-    return user;
-}
+// Emit event without payload
+await serverStarted.emit();
+
+// Unsubscribe when done
+unsubscribe();
+```
+
+## Multiple Subscribers
+
+```typescript
+// Multiple independent handlers
+userCreated.subscribe(async (payload) => {
+    await sendWelcomeEmail(payload.email);
+});
+
+userCreated.subscribe(async (payload) => {
+    await createDefaultSettings(payload.userId);
+});
+
+userCreated.subscribe(async (payload) => {
+    await notifyAdmins(payload.userId);
+});
+
+// All handlers execute when event is emitted
+await userCreated.emit({ userId: '123', email: 'user@example.com' });
+```
+
+## Event Router for SSE
+
+```typescript
+// src/server/events/router.ts
+import { defineEventRouter } from '@spfn/core/event';
+import { userCreated, orderPlaced } from './index';
+
+export const eventRouter = defineEventRouter({
+    userCreated,
+    orderPlaced,
+});
+
+export type EventRouter = typeof eventRouter;
+```
+
+## Server Setup
+
+```typescript
+// server.config.ts
+import { defineServerConfig } from '@spfn/core/server';
+import { eventRouter } from './events/router';
+
+export default defineServerConfig()
+    .routes(appRouter)
+    .jobs(jobRouter)
+    .events(eventRouter)  // → GET /events/stream
+    .build();
+
+// Custom path and options
+.events(eventRouter, {
+    path: '/sse',           // Custom endpoint path
+    pingInterval: 30000,    // Keep-alive interval (default: 30s)
+})
+```
+
+## SSE Authentication
+
+Browser `EventSource` API does not support custom headers. SPFN uses a **Token Exchange** pattern:
+
+1. Client sends `POST /events/token` with Bearer JWT
+2. Server returns a one-time token (30s TTL)
+3. Client connects to `GET /events/stream?token=...&events=...`
+
+```typescript
+// server.config.ts
+import { defineServerConfig } from '@spfn/core/server';
+import { authenticate } from '@spfn/auth/server';
+
+export default defineServerConfig()
+    .middlewares([authenticate])
+    .routes(appRouter)
+    .events(eventRouter, {
+        auth: { enabled: true },  // This is all you need
+    })
+    .build();
+// → POST /events/token (protected by authenticate middleware)
+// → GET /events/stream?token=...&events=... (token verified)
+```
+
+### Authorization Hooks
+
+#### `authorize` — Subscription Authorization (once on connect)
+
+```typescript
+.events(eventRouter, {
+    auth: {
+        enabled: true,
+        authorize: async (subject, events) =>
+        {
+            // events: ('userCreated' | 'orderPlaced')[] — type inferred
+            const user = await usersRepository.findById(subject);
+            if (user.role === 'admin') return events;
+            return events.filter(e => !e.startsWith('admin.'));
+        },
+    },
+})
 ```
 
-## Handle Events
+#### `filter` — Payload Filtering (on every event emission)
 
 ```typescript
-import { on } from '@spfn/core/event';
-import { userCreated, userDeleted } from './events';
+.events(eventRouter, {
+    auth: {
+        enabled: true,
+        filter: {
+            // payload type inferred per-event — no casting needed
+            orderPlaced: (subject, payload) => payload.userId === subject,
+            // userCreated: no filter → sent to all authenticated users
+        },
+    },
+})
+```
 
-// Register handlers
-on(userCreated, async (payload) => {
-    // Send welcome email
-    await emailService.sendWelcome(payload.email);
+## Browser Client
+
+```typescript
+import { createSSEClient } from '@spfn/core/event/sse/client';
+import type { EventRouter } from '@/server/events/router';
+
+// Create client (uses defaults: NEXT_PUBLIC_SPFN_API_URL + /events/stream)
+const client = createSSEClient<EventRouter>();
+
+// Or with custom configuration
+const client = createSSEClient<EventRouter>({
+    host: 'https://api.example.com',
+    pathname: '/sse',
+    reconnect: true,
+    reconnectDelay: 3000,
 });
 
-on(userCreated, async (payload) => {
-    // Create default settings
-    await settingsRepo.createDefaults(payload.userId);
+// Subscribe to events
+const unsubscribe = client.subscribe({
+    events: ['userCreated', 'orderPlaced'],
+    handlers: {
+        userCreated: (payload) => {
+            console.log('New user:', payload.userId);
+        },
+        orderPlaced: (payload) => {
+            console.log('New order:', payload.orderId);
+        },
+    },
+    onOpen: () => console.log('SSE connected'),
+    onError: (err) => console.error('SSE error:', err),
 });
 
-on(userDeleted, async (payload) => {
-    // Cleanup related data
-    await cleanupUserData(payload.userId);
+// Cleanup
+unsubscribe();
+```
+
+### With Authentication
+
+```typescript
+const client = createSSEClient<EventRouter>({
+    acquireToken: async () =>
+    {
+        const res = await fetch('/api/events/token', {
+            method: 'POST',
+            credentials: 'include',
+        });
+        const data = await res.json();
+        return data.token;
+    },
+});
+```
+
+`acquireToken` is called on every (re)connect — one-time tokens are handled automatically.
+
+## Simple Subscribe Helper
+
+```typescript
+import { subscribeToEvents } from '@spfn/core/event/sse/client';
+import type { EventRouter } from '@/server/events/router';
+
+// One-liner subscription
+const unsubscribe = subscribeToEvents<EventRouter>(
+    ['userCreated'],
+    {
+        userCreated: (payload) => console.log('User:', payload),
+    }
+);
+```
+
+## Job Integration
+
+```typescript
+import { defineEvent } from '@spfn/core/event';
+import { job, defineJobRouter } from '@spfn/core/job';
+
+// Define event
+export const orderPlaced = defineEvent('order.placed', Type.Object({
+    orderId: Type.String(),
+    userId: Type.String(),
+}));
+
+// Jobs subscribe to event
+export const sendOrderConfirmation = job('send-order-confirmation')
+    .on(orderPlaced)
+    .handler(async (payload) => {
+        await emailService.sendOrderConfirmation(payload.orderId);
+    });
+
+export const updateInventory = job('update-inventory')
+    .on(orderPlaced)
+    .handler(async (payload) => {
+        await inventoryService.reserve(payload.orderId);
+    });
+
+// Register jobs
+export const jobRouter = defineJobRouter({
+    sendOrderConfirmation,
+    updateInventory,
 });
+
+// Emit event - all subscribed jobs execute
+await orderPlaced.emit({ orderId: 'ord-123', userId: 'user-456' });
 ```
 
-## Handler Registration
+## Multi-Instance Support
+
+For applications running multiple instances, use cache-based pub/sub.
 
 ```typescript
-// src/server/events/handlers.ts
-import { on } from '@spfn/core/event';
-import { userCreated, userUpdated, userDeleted } from './index';
+import { defineEvent } from '@spfn/core/event';
+import { getCache } from '@spfn/core/cache';
 
-// Register all handlers
-export function registerEventHandlers()
+const userCreated = defineEvent('user.created', Type.Object({
+    userId: Type.String(),
+}));
+
+// Enable cache-based pub/sub
+const cache = getCache();
+if (cache)
 {
-    on(userCreated, handleUserCreated);
-    on(userUpdated, handleUserUpdated);
-    on(userDeleted, handleUserDeleted);
+    await userCreated.useCache({
+        publish: async (channel, message) => {
+            await cache.publish(channel, JSON.stringify(message));
+        },
+        subscribe: async (channel, handler) => {
+            const subscriber = cache.duplicate();
+            await subscriber.subscribe(channel);
+            subscriber.on('message', (ch, msg) => {
+                if (ch === channel)
+                {
+                    handler(JSON.parse(msg));
+                }
+            });
+        },
+    });
 }
 
-// Call in server startup
-import { registerEventHandlers } from './events/handlers';
-registerEventHandlers();
+// Events now broadcast to all instances
+await userCreated.emit({ userId: '123' });
 ```
 
-## Best Practices
+## API Reference
+
+### defineEvent(name)
+
+Define an event without payload.
 
 ```typescript
-// 1. Define events in a central location
-// src/server/events/index.ts
+export const serverStarted = defineEvent('server.started');
+
+serverStarted.subscribe(() => { ... });
+await serverStarted.emit();
+```
+
+### defineEvent(name, schema)
 
-// 2. Use descriptive event names
+Define an event with typed payload.
+
+```typescript
+export const userCreated = defineEvent('user.created', Type.Object({
+    userId: Type.String(),
+}));
+
+userCreated.subscribe((payload) => { ... });
+await userCreated.emit({ userId: '123' });
+```
+
+### EventDef Methods
+
+| Method | Description |
+|--------|-------------|
+| `subscribe(handler)` | Subscribe to event. Returns unsubscribe function |
+| `unsubscribeAll()` | Remove all subscribers |
+| `emit(payload?)` | Emit event to all subscribers |
+| `useCache(cache)` | Enable cache-based pub/sub for multi-instance |
+
+### SSE Client Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | string | `NEXT_PUBLIC_SPFN_API_URL` | Backend API host URL |
+| `pathname` | string | `/events/stream` | SSE endpoint pathname |
+| `reconnect` | boolean | `true` | Auto reconnect on disconnect |
+| `reconnectDelay` | number | `3000` | Reconnect delay (ms) |
+| `maxReconnectAttempts` | number | `0` | Max attempts (0 = infinite) |
+| `withCredentials` | boolean | `false` | Include cookies |
+| `acquireToken` | () => Promise\<string\> | - | Acquire one-time SSE token before connecting |
+
+### SSE Auth Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable token authentication |
+| `tokenTtl` | number | `30000` | Token TTL in milliseconds |
+| `store` | SSETokenStore | InMemory | Custom token store (e.g., Redis) |
+| `getSubject` | (c) => string \| null | `c.get('auth')?.userId` | Extract subject from context |
+| `authorize` | (subject, events) => events[] | - | Subscription authorization hook |
+| `filter` | { [event]: (subject, payload) => boolean } | - | Per-event payload filter |
+
+## Event Flow Architecture
+
+```
+                    userCreated.emit({ ... })
+                              │
+          ┌───────────────────┼───────────────────┐
+          ▼                   ▼                   ▼
+    ┌──────────┐       ┌──────────┐       ┌──────────┐
+    │ Backend  │       │   Job    │       │   SSE    │
+    │ Handler  │       │  Queue   │       │  Stream  │
+    └──────────┘       └──────────┘       └──────────┘
+    .subscribe()       .on(event)              ↓
+          │                 │           ┌──────────┐
+          ▼                 ▼           │ Browser  │
+    [Logging,         [Background       │  Client  │
+     Analytics]        Processing]      └──────────┘
+```
+
+## Best Practices
+
+```typescript
+// 1. Use descriptive event names
 defineEvent('user.created')
 defineEvent('order.completed')
 defineEvent('payment.failed')
 
-// 3. Keep payloads minimal
-defineEvent<{ userId: string }>('user.deleted')  // Just ID, not full user
+// 2. Keep payloads minimal - just IDs, not full objects
+defineEvent('user.deleted', Type.Object({
+    userId: Type.String(),
+}));
 
-// 4. Handle errors in handlers
-on(userCreated, async (payload) => {
-    try {
-        await sendEmail(payload.email);
-    } catch (error) {
-        logger.error('Failed to send email', { error });
-    }
+// 3. Handler errors are isolated - one failing handler doesn't affect others
+userCreated.subscribe(async (payload) => {
+    throw new Error('This fails');
 });
 
-// 5. Use events for side effects, not core logic
+userCreated.subscribe(async (payload) => {
+    // This still executes
+    console.log('Handler 2 runs');
+});
+
+// 4. Use events for side effects, not core logic
 // Core: await userRepo.create(data);
-// Side effect: emit(userCreated, { ... });
+// Side effect: await userCreated.emit({ ... });
+
+// 5. Await useCache() before emitting for multi-instance
+await userCreated.useCache(cache);
+await userCreated.emit({ userId: '123' });
 ```
+
+## Event vs Direct Job
+
+| Aspect | Event + Job | Direct Job |
+|--------|-------------|------------|
+| Coupling | Loose (producer doesn't know consumers) | Tight (producer calls specific job) |
+| Multiple consumers | Easy (multiple jobs subscribe) | Manual (call each job) |
+| Extensibility | Add consumers without modifying producer | Modify producer for each consumer |
+
+**Use Event when:**
+- Multiple systems need to react to the same occurrence
+- You want to decouple producers from consumers
+
+**Use Direct Job when:**
+- Single, known consumer
+- Simpler mental model preferred

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spfn/core",
-  "version": "0.2.0-beta.11",
+  "version": "0.2.0-beta.13",
   "description": "SPFN Framework Core - File-based routing, transactions, repository pattern",
   "type": "module",
   "exports": {

package/dist/types-B-e_f2dQ.d.ts

@@ -1,121 +0,0 @@
-import { E as EventRouterDef, I as InferEventNames, b as InferEventPayload } from './router-Di7ENoah.js';
-
-/**
- * SSE Types
- *
- * Type definitions for Server-Sent Events
- */
-
-/**
- * SSE message sent from server
- */
-interface SSEMessage<TEvent extends string = string, TPayload = unknown> {
-    /** Event name */
-    event: TEvent;
-    /** Event payload */
-    data: TPayload;
-    /** Optional message ID for reconnection */
-    id?: string;
-}
-/**
- * SSE Handler configuration
- */
-interface SSEHandlerConfig {
-    /**
-     * Keep-alive ping interval in milliseconds
-     * @default 30000
-     */
-    pingInterval?: number;
-    /**
-     * Custom headers for SSE response
-     */
-    headers?: Record<string, string>;
-}
-/**
- * SSE Client configuration
- */
-interface SSEClientConfig {
-    /**
-     * Backend API host URL
-     * @default NEXT_PUBLIC_SPFN_API_URL || 'http://localhost:8790'
-     * @example 'http://localhost:8790'
-     * @example 'https://api.example.com'
-     */
-    host?: string;
-    /**
-     * SSE endpoint pathname
-     * @default '/events/stream'
-     */
-    pathname?: string;
-    /**
-     * Full URL (overrides host + pathname)
-     * @deprecated Use host and pathname instead
-     * @example 'http://localhost:8790/events/stream'
-     */
-    url?: string;
-    /**
-     * Auto reconnect on disconnect
-     * @default true
-     */
-    reconnect?: boolean;
-    /**
-     * Reconnect delay in milliseconds
-     * @default 3000
-     */
-    reconnectDelay?: number;
-    /**
-     * Maximum reconnect attempts (0 = infinite)
-     * @default 0
-     */
-    maxReconnectAttempts?: number;
-    /**
-     * Include credentials (cookies) in request
-     * @default false
-     */
-    withCredentials?: boolean;
-}
-/**
- * Event handler function
- */
-type SSEEventHandler<TPayload> = (payload: TPayload) => void;
-/**
- * Event handlers map for EventRouter
- */
-type SSEEventHandlers<TRouter extends EventRouterDef<any>> = {
-    [K in InferEventNames<TRouter>]?: SSEEventHandler<InferEventPayload<TRouter, K>>;
-};
-/**
- * Subscription options
- */
-interface SSESubscribeOptions<TRouter extends EventRouterDef<any>> {
-    /**
-     * Events to subscribe
-     */
-    events: InferEventNames<TRouter>[];
-    /**
-     * Event handlers
-     */
-    handlers: SSEEventHandlers<TRouter>;
-    /**
-     * Called when connection opens
-     */
-    onOpen?: () => void;
-    /**
-     * Called on connection error
-     */
-    onError?: (error: Event) => void;
-    /**
-     * Called when reconnecting
-     */
-    onReconnect?: (attempt: number) => void;
-}
-/**
- * SSE connection state
- */
-type SSEConnectionState = 'connecting' | 'open' | 'closed' | 'error';
-/**
- * Unsubscribe function
- */
-type SSEUnsubscribe = () => void;
-
-export type { SSEHandlerConfig as S, SSEMessage as a, SSEClientConfig as b, SSEEventHandler as c, SSEEventHandlers as d, SSESubscribeOptions as e, SSEConnectionState as f, SSEUnsubscribe as g };