@fitzzero/quickdraw-core 3.6.0 → 3.8.0

package/README.md

@@ -21,31 +21,36 @@ pnpm add @fitzzero/quickdraw-core
 ### Server Setup
 
 ```typescript
-import { createQuickdrawServer, BaseService } from '@fitzzero/quickdraw-core/server';
-import { PrismaClient } from '@prisma/client';
+import { createQuickdrawServer, BaseService } from "@fitzzero/quickdraw-core/server";
+import { PrismaClient } from "@prisma/client";
 
 const prisma = new PrismaClient();
 
 // Define your service
-class ChatService extends BaseService<Chat, Prisma.ChatCreateInput, Prisma.ChatUpdateInput, ChatServiceMethods> {
+class ChatService extends BaseService<
+  Chat,
+  Prisma.ChatCreateInput,
+  Prisma.ChatUpdateInput,
+  ChatServiceMethods
+> {
   constructor() {
-    super({ serviceName: 'chatService', hasEntryACL: true });
+    super({ serviceName: "chatService", hasEntryACL: true });
     this.setDelegate(prisma.chat);
-    
+
     // Define public methods
-    this.createChat = this.defineMethod('createChat', 'Read', async (payload, ctx) => {
+    this.createChat = this.defineMethod("createChat", "Read", async (payload, ctx) => {
       const chat = await this.create({ title: payload.title, ownerId: ctx.userId });
       return { id: chat.id };
     });
   }
-  
-  createChat: ReturnType<typeof this.defineMethod<'createChat'>>;
+
+  createChat: ReturnType<typeof this.defineMethod<"createChat">>;
 }
 
 // Start server
 const { io, httpServer } = createQuickdrawServer({
   port: 4000,
-  cors: { origin: 'http://localhost:3000' },
+  cors: { origin: "http://localhost:3000" },
   services: {
     chatService: new ChatService(),
   },
@@ -62,45 +67,42 @@ const { io, httpServer } = createQuickdrawServer({
 
 ```tsx
 // app/layout.tsx
-import { QuickdrawProvider } from '@fitzzero/quickdraw-core/client';
+import { QuickdrawProvider } from "@fitzzero/quickdraw-core/client";
 
 export default function RootLayout({ children }) {
   return (
-    <QuickdrawProvider
-      serverUrl="http://localhost:4000"
-      authToken={getAuthToken()}
-    >
+    <QuickdrawProvider serverUrl="http://localhost:4000" authToken={getAuthToken()}>
       {children}
     </QuickdrawProvider>
   );
 }
 
 // app/chat/page.tsx
-import { useService, useSubscription, useRoomEvents } from '@fitzzero/quickdraw-core/client';
+import { useService, useSubscription, useRoomEvents } from "@fitzzero/quickdraw-core/client";
 
 function ChatPage({ chatId }: { chatId: string }) {
   // Subscribe to real-time entity updates
-  const { data: chat, isLoading } = useSubscription('chatService', chatId);
-  
+  const { data: chat, isLoading } = useSubscription("chatService", chatId);
+
   // Mutation hook
-  const updateTitle = useService('chatService', 'updateTitle', {
-    onSuccess: () => console.log('Title updated!'),
+  const updateTitle = useService("chatService", "updateTitle", {
+    onSuccess: () => console.log("Title updated!"),
   });
-  
+
   // Listen for custom events broadcast to the chat room
   const [typing, setTyping] = useState(false);
   useRoomEvents({
-    'chat:message': (msg) => appendMessage(msg),
-    'agent_typing_start': () => setTyping(true),
-    'agent_typing_stop': () => setTyping(false),
+    "chat:message": (msg) => appendMessage(msg),
+    agent_typing_start: () => setTyping(true),
+    agent_typing_stop: () => setTyping(false),
   });
-  
+
   if (isLoading) return <div>Loading...</div>;
-  
+
   return (
     <div>
       <h1>{chat?.title}</h1>
-      <button onClick={() => updateTitle.mutate({ id: chatId, title: 'New Title' })}>
+      <button onClick={() => updateTitle.mutate({ id: chatId, title: "New Title" })}>
         Update Title
       </button>
     </div>
@@ -111,7 +113,7 @@ function ChatPage({ chatId }: { chatId: string }) {
 ### Socket Inputs
 
 ```tsx
-import { SocketTextField } from '@fitzzero/quickdraw-core/client';
+import { SocketTextField } from "@fitzzero/quickdraw-core/client";
 
 function ChatTitleEditor({ chat, updateChat }) {
   return (
@@ -132,16 +134,16 @@ function ChatTitleEditor({ chat, updateChat }) {
 When your server broadcasts custom events to subscription rooms via `emitToRoom`, use `useRoomEvents` on the client to listen with proper lifecycle management:
 
 ```tsx
-import { useSubscription, useRoomEvents } from '@fitzzero/quickdraw-core/client';
+import { useSubscription, useRoomEvents } from "@fitzzero/quickdraw-core/client";
 
 function ProjectBoard({ projectId }: { projectId: string }) {
-  const { data: project } = useSubscription('projectService', projectId);
+  const { data: project } = useSubscription("projectService", projectId);
   const [tasks, setTasks] = useState<Task[]>([]);
 
   // Lifecycle-managed event listeners — cleanup handled automatically
   useRoomEvents({
-    'task:created': (task: Task) => setTasks(prev => [...prev, task]),
-    'task:deleted': ({ id }: { id: string }) => setTasks(prev => prev.filter(t => t.id !== id)),
+    "task:created": (task: Task) => setTasks((prev) => [...prev, task]),
+    "task:deleted": ({ id }: { id: string }) => setTasks((prev) => prev.filter((t) => t.id !== id)),
   });
 
   return <Board tasks={tasks} />;
@@ -153,39 +155,183 @@ function ProjectBoard({ projectId }: { projectId: string }) {
 For list queries that should refresh when related events fire, use `invalidateOn`:
 
 ```tsx
-import { useServiceQuery } from '@fitzzero/quickdraw-core/client';
+import { useServiceQuery } from "@fitzzero/quickdraw-core/client";
 
 function TaskList({ projectId }: { projectId: string }) {
   // Auto-refetches when tasks are created, deleted, or change status
-  const { data: tasks } = useServiceQuery('taskService', 'listTasks', { projectId }, {
-    invalidateOn: ['task:created', 'task:deleted', 'task:statusUpdate'],
-  });
+  const { data: tasks } = useServiceQuery(
+    "taskService",
+    "listTasks",
+    { projectId },
+    {
+      invalidateOn: ["task:created", "task:deleted", "task:statusUpdate"],
+    },
+  );
 
-  return <ul>{tasks?.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
+  return (
+    <ul>
+      {tasks?.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  );
 }
 ```
 
 Rapid-fire events within 100ms are debounced into a single refetch.
 
+### Channels (High-Frequency Traffic)
+
+Methods are request/response: ack'd, ACL-checked against the database, and
+counted by the global rate limiter. **Channels** are their fire-and-forget
+counterpart for traffic where per-message overhead matters and losing a
+message is fine — game input, cursor positions, typing indicators, telemetry.
+
+Channel messages have no ack and no response. Each message is validated
+(zod schema required), access-checked entirely in memory (zero DB reads on
+the hot path), and governed by a per-socket, per-channel token bucket instead
+of the global limiter. Excess messages are silently dropped; sustained extreme
+flooding disconnects the socket.
+
+**Server** — define channels next to methods; broadcast tick data back with
+`emitToRoomVolatile` (backpressured clients drop frames instead of queueing):
+
+```typescript
+type GameServiceChannels = ServiceChannelMap<{
+  input: { seq: number; dx: number; dy: number; boost: boolean };
+}>;
+
+class GameService extends BaseService<
+  GameWorld,
+  Prisma.GameWorldCreateInput,
+  Prisma.GameWorldUpdateInput,
+  GameServiceMethods,
+  GameServiceChannels // 5th type param
+> {
+  constructor(prisma: PrismaClient) {
+    super({ serviceName: "gameService" });
+    this.setDelegate(prisma.gameWorld);
+
+    this.defineChannel(
+      "input",
+      "Read",
+      (payload, ctx) => this.sim.applyInput(ctx.userId, payload),
+      {
+        schema: gameInputSchema,
+        ratePerSecond: 30, // default 30
+        burst: 60, // default 2x rate
+        requireRoom: () => this.getRoomName(WORLD_ID), // entry-level gate
+      },
+    );
+  }
+
+  // In a 20Hz tick loop:
+  broadcastSnapshot(snapshot: WorldSnapshot): void {
+    this.emitToRoomVolatile(this.getRoomName(WORLD_ID), "game:snapshot", snapshot);
+  }
+}
+```
+
+Exempt channel traffic from the global rate limiter (channels self-limit):
+
+```typescript
+import { CHANNEL_EVENT_PREFIX } from "@fitzzero/quickdraw-core";
+
+const rateLimiter = createRateLimiter({
+  maxRequests: 100,
+  excludePrefixes: [CHANNEL_EVENT_PREFIX],
+});
+```
+
+**Client** — send with `useChannelSend`; receive broadcasts with the existing
+`useRoomEvents` (volatile room emits arrive as ordinary events):
+
+```tsx
+import { useSubscription, useRoomEvents, useChannelSend } from "@fitzzero/quickdraw-core/client";
+
+function GameView({ worldId }: { worldId: string }) {
+  useSubscription("gameService", worldId); // room membership gates the channel
+  const { send, isReady } = useChannelSend<GameInput>("gameService", "input");
+
+  useRoomEvents({
+    "game:snapshot": (snap: WorldSnapshot) => applySnapshot(snap),
+  });
+
+  // e.g. called from a fixed-timestep loop
+  const onTick = (input: GameInput) => send(input);
+}
+```
+
+**Access model** (all synchronous, in-memory):
+
+| Check                    | Behavior                                                                                                                                                       |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Authentication           | Always required — anonymous messages dropped, even at `"Public"` access                                                                                        |
+| `"Public"` / `"Read"`    | Any authenticated user passes the service gate                                                                                                                 |
+| `"Moderate"` / `"Admin"` | Requires that level in the socket's `serviceAccess`                                                                                                            |
+| `requireRoom`            | Socket must already be in the resolved room — membership was ACL-checked at subscribe time, so this inherits entry ACL semantics without a DB read per message |
+
+Channels route as the Socket.io event `channel:<serviceName>:<channelName>`
+(helper: `channelEventName(serviceName, channelName)`), which also makes them
+easy to speak from non-JS clients (game engines, native apps).
+
+When to use which:
+
+|                | Method                    | Channel                  |
+| -------------- | ------------------------- | ------------------------ |
+| Response       | ack with data/error       | none (fire-and-forget)   |
+| Frequency      | occasional (user actions) | tick rate (10-60Hz)      |
+| Loss tolerance | must not lose             | next message supersedes  |
+| ACL            | full async check incl. DB | in-memory only           |
+| Rate limit     | global limiter            | per-channel token bucket |
+
 ## Package Exports
 
 ```typescript
 // Shared types (both server and client)
-import { ServiceResponse, AccessLevel, ServiceMethodMap } from '@fitzzero/quickdraw-core';
+import { ServiceResponse, AccessLevel, ServiceMethodMap } from "@fitzzero/quickdraw-core";
 
 // Server
-import { 
-  BaseService, 
-  ServiceRegistry, 
+import {
+  BaseService,
+  ServiceRegistry,
   createQuickdrawServer,
   createJWT,
   verifyJWT,
   discordProvider,
   googleProvider,
-} from '@fitzzero/quickdraw-core/server';
+  // Auth & security (3.7+)
+  createMockOAuthProvider,
+  registerMockOAuthProvider,
+  isMockOAuthEnabled,
+  validateRedirectOrigin,
+  setSessionCookie,
+  clearSessionCookie,
+  createRequireAuth,
+  encrypt,
+  decrypt,
+} from "@fitzzero/quickdraw-core/server";
+
+// Express rate-limit presets (3.7+, requires the optional express-rate-limit peer)
+import {
+  createAuthLimiter,
+  createWebhookLimiter,
+  createPublicApiLimiter,
+} from "@fitzzero/quickdraw-core/server/express";
 
 // Server testing
-import { createTestServer, connectAsUser, emitWithAck } from '@fitzzero/quickdraw-core/server/testing';
+import {
+  createTestServer,
+  connectAsUser,
+  emitWithAck,
+} from "@fitzzero/quickdraw-core/server/testing";
+
+// Dual-mode Prisma test databases (3.7+, optional peers: @electric-sql/pglite, pg)
+import {
+  createPrismaTestGlobalSetup,
+  resetDatabase,
+  workerDatabaseUrl,
+} from "@fitzzero/quickdraw-core/server/testing/prisma";
 
 // Client
 import {
@@ -200,10 +346,10 @@ import {
   SocketSelect,
   SocketSlider,
   SocketSwitch,
-} from '@fitzzero/quickdraw-core/client';
+} from "@fitzzero/quickdraw-core/client";
 
 // Client testing
-import { createMockSocket, createTestWrapper } from '@fitzzero/quickdraw-core/client/testing';
+import { createMockSocket, createTestWrapper } from "@fitzzero/quickdraw-core/client/testing";
 ```
 
 ## Local Development
@@ -226,7 +372,7 @@ Define your service methods in a shared types file:
 
 ```typescript
 // shared/types.ts
-import type { ServiceMethodMap } from '@fitzzero/quickdraw-core';
+import type { ServiceMethodMap } from "@fitzzero/quickdraw-core";
 
 export type ChatServiceMethods = ServiceMethodMap<{
   createChat: {
@@ -238,7 +384,7 @@ export type ChatServiceMethods = ServiceMethodMap<{
     response: { id: string; title: string };
   };
   inviteUser: {
-    payload: { id: string; userId: string; level: 'Read' | 'Moderate' | 'Admin' };
+    payload: { id: string; userId: string; level: "Read" | "Moderate" | "Admin" };
     response: { id: string };
   };
 }>;
@@ -309,6 +455,7 @@ Per-entity permissions. Quickdraw supports two patterns:
 #### Pattern 1: JSON ACL (Simple)
 
 Store ACL directly on the entity. Best for:
+
 - Simple ownership models (owner + collaborators)
 - When you don't need to query "all entities user X can access" efficiently
 - Minimal schema complexity
@@ -338,6 +485,7 @@ class DocumentService extends BaseService<Document, ...> {
 #### Pattern 2: Membership Table (Complex)
 
 Separate table for memberships. Best for:
+
 - Querying "all entities user X can access" efficiently
 - Complex role hierarchies
 - Additional membership metadata (join date, invited by, etc.)
@@ -353,7 +501,7 @@ model ChatMember {
   chatId String
   userId String
   level  String  // "Read" | "Moderate" | "Admin"
-  
+
   @@unique([chatId, userId])
 }
 
@@ -384,35 +532,41 @@ When a method is called, `ensureAccessForMethod` checks in this order:
 
 ### Access Levels
 
-| Level | Value | Typical Use |
-|-------|-------|-------------|
-| Public | 0 | No authentication required |
-| Read | 1 | View data, subscribe to updates |
-| Moderate | 2 | Edit content, manage members |
-| Admin | 3 | Delete, manage ACL, full control |
+| Level    | Value | Typical Use                      |
+| -------- | ----- | -------------------------------- |
+| Public   | 0     | No authentication required       |
+| Read     | 1     | View data, subscribe to updates  |
+| Moderate | 2     | Edit content, manage members     |
+| Admin    | 3     | Delete, manage ACL, full control |
 
 ## Testing
 
 ### Server Integration Tests
 
 ```typescript
-import { createTestServer, connectAsUser, emitWithAck } from '@fitzzero/quickdraw-core/server/testing';
+import {
+  createTestServer,
+  connectAsUser,
+  emitWithAck,
+} from "@fitzzero/quickdraw-core/server/testing";
 
-describe('ChatService', () => {
+describe("ChatService", () => {
   let server;
-  
+
   beforeAll(async () => {
     server = await createTestServer({
       services: { chatService: new ChatService() },
-      seedDb: async () => { /* seed test data */ },
+      seedDb: async () => {
+        /* seed test data */
+      },
     });
   });
-  
+
   afterAll(() => server.stop());
-  
-  it('creates chat', async () => {
-    const client = await server.connectAs('user-id');
-    const chat = await client.emit('chatService:createChat', { title: 'Test' });
+
+  it("creates chat", async () => {
+    const client = await server.connectAs("user-id");
+    const chat = await client.emit("chatService:createChat", { title: "Test" });
     expect(chat.id).toBeDefined();
     client.close();
   });
@@ -427,10 +581,10 @@ import { createTestWrapper, createMockSocket, mockSuccessEmit } from '@fitzzero/
 test('renders chat', () => {
   const mockSocket = createMockSocket();
   mockSocket.emit.mockImplementation(mockSuccessEmit({ title: 'Test Chat' }));
-  
+
   const wrapper = createTestWrapper({ socketContext: { socket: mockSocket } });
   render(<ChatView chatId="123" />, { wrapper });
-  
+
   expect(screen.getByText('Test Chat')).toBeInTheDocument();
 });
 ```

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { a as QuickdrawProviderProps, Q as QuickdrawSocketContextValue, U as UseServiceOptions, b as UseServiceResult, c as UseServiceQueryOptions, d as UseServiceQueryResult, e as UseSubscriptionOptions, f as UseSubscriptionResult, g as UseRoomEventsOptions } from '../types-B1z5aXdR.js';
-export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-B1z5aXdR.js';
+import { a as QuickdrawProviderProps, Q as QuickdrawSocketContextValue, U as UseServiceOptions, b as UseServiceResult, c as UseServiceQueryOptions, d as UseServiceQueryResult, e as UseSubscriptionOptions, f as UseSubscriptionResult, g as UseRoomEventsOptions, h as UseChannelSendResult } from '../types-DUHPIy_5.js';
+export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-DUHPIy_5.js';
 import 'socket.io-client';
 import '@tanstack/react-query';
 import '../shared/index.js';
@@ -28,7 +28,7 @@ declare function useQuickdrawSocket(): QuickdrawSocketContextValue;
  * }
  * ```
  */
-declare function QuickdrawProvider({ children, serverUrl, queryClient, authToken, autoConnect, withCredentials, }: QuickdrawProviderProps): React.ReactElement;
+declare function QuickdrawProvider({ children, serverUrl, queryClient, authToken, autoConnect, withCredentials, socketPath, }: QuickdrawProviderProps): React.ReactElement;
 
 /**
  * Hook for invoking service methods via Socket.io with TanStack Query integration.
@@ -207,6 +207,36 @@ declare function useSubscription<TData extends {
  */
 declare function useRoomEvents(handlers: Record<string, (data: never) => void>, options?: UseRoomEventsOptions): void;
 
+/**
+ * Hook for sending fire-and-forget channel messages (the high-frequency
+ * counterpart to useService).
+ *
+ * Channel messages are emitted volatile: if the connection is backpressured,
+ * the message is dropped instead of queued — the right behavior for input
+ * streams where the next message supersedes the last. There is no ack and no
+ * response; the server validates, rate-limits (per-channel token bucket), and
+ * access-checks each message, silently dropping any that fail.
+ *
+ * Receiving server broadcasts needs nothing new: volatile room emits arrive
+ * as ordinary events, so pair this with `useRoomEvents` (and `useSubscription`
+ * for room membership).
+ *
+ * @typeParam TPayload - The channel payload type (from the service's channel map)
+ *
+ * @example
+ * ```tsx
+ * function GameInput({ worldId }: { worldId: string }) {
+ *   // Room membership (ACL-checked server-side) gates the channel
+ *   useSubscription("gameService", worldId);
+ *   const { send, isReady } = useChannelSend<GameInput>("gameService", "input");
+ *
+ *   // e.g. called from a 20Hz game loop
+ *   const onTick = (input: GameInput) => send(input);
+ * }
+ * ```
+ */
+declare function useChannelSend<TPayload = unknown>(serviceName: string, channelName: string): UseChannelSendResult<TPayload>;
+
 type CommitMode = "change" | "blur" | "debounce";
 interface UseSocketInputOptions<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> {
     /**
@@ -517,4 +547,4 @@ declare function buildBreadcrumbs(pathname: string, navigation: NavItem[]): Brea
  */
 declare function routeRequiresAuth(pathname: string, navigation: NavItem[], userMenuItems?: NavItem[]): boolean;
 
-export { type BreadcrumbItem, type CommitMode, type JWTPayload, type NavItem, QuickdrawProvider, QuickdrawProviderProps, QuickdrawSocketContextValue, SocketCheckbox, type SocketCheckboxProps, SocketSelect, type SocketSelectProps, SocketSlider, type SocketSliderProps, SocketSwitch, type SocketSwitchProps, SocketTextField, type SocketTextFieldProps, UseRoomEventsOptions, UseServiceOptions, UseServiceQueryOptions, UseServiceQueryResult, UseServiceResult, type UseSocketInputOptions, type UseSocketInputResult, UseSubscriptionOptions, UseSubscriptionResult, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
+export { type BreadcrumbItem, type CommitMode, type JWTPayload, type NavItem, QuickdrawProvider, QuickdrawProviderProps, QuickdrawSocketContextValue, SocketCheckbox, type SocketCheckboxProps, SocketSelect, type SocketSelectProps, SocketSlider, type SocketSliderProps, SocketSwitch, type SocketSwitchProps, SocketTextField, type SocketTextFieldProps, UseChannelSendResult, UseRoomEventsOptions, UseServiceOptions, UseServiceQueryOptions, UseServiceQueryResult, UseServiceResult, type UseSocketInputOptions, type UseSocketInputResult, UseSubscriptionOptions, UseSubscriptionResult, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useChannelSend, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };