@fitzzero/quickdraw-core 3.9.0 → 4.0.0

package/dist/shared/index.d.ts

@@ -196,68 +196,61 @@ declare const CHANNEL_EVENT_PREFIX = "channel:";
 type AdminListPayload = {
     page?: number;
     pageSize?: number;
-    sort?: {
-        field?: string;
-        direction?: "asc" | "desc";
-    };
-    filter?: {
-        id?: string;
-        ids?: string[];
-        createdAfter?: string;
-        createdBefore?: string;
-        updatedAfter?: string;
-        updatedBefore?: string;
-    } & Record<string, unknown>;
+    where?: Record<string, unknown>;
+    orderBy?: Record<string, "asc" | "desc">;
 };
 type AdminListResponse<T> = {
-    rows: T[];
+    items: T[];
+    total: number;
     page: number;
     pageSize: number;
-    total: number;
+    totalPages: number;
 };
 type AdminGetPayload = {
     id: string;
 };
-type AdminCreatePayload<TInsert> = {
-    data: Partial<TInsert>;
+type AdminCreatePayload<TCreate> = {
+    data: TCreate;
 };
-type AdminUpdatePayload<TInsert> = {
+type AdminUpdatePayload<TUpdate> = {
     id: string;
-    data: Partial<TInsert>;
+    data: TUpdate;
 };
 type AdminDeletePayload = {
     id: string;
 };
 type AdminDeleteResponse = {
+    success: boolean;
     id: string;
-    deleted: true;
 };
-type AdminSetEntryACLPayload = {
-    id: string;
+type AdminSetACLPayload = {
+    entryId: string;
     acl: ACL;
 };
 type AdminGetSubscribersPayload = {
-    id: string;
+    entryId: string;
 };
-type AdminGetSubscribersResponse = {
-    id: string;
+type AdminSubscribersResponse = {
+    entryId: string;
     subscribers: Array<{
         socketId: string;
-        userId?: string;
+        userId: string | null;
     }>;
+    count: number;
 };
 type AdminReemitPayload = {
-    id: string;
+    entryId: string;
 };
 type AdminReemitResponse = {
-    emitted: boolean;
+    success: boolean;
+    subscriberCount: number;
 };
 type AdminUnsubscribeAllPayload = {
-    id: string;
+    entryId: string;
 };
 type AdminUnsubscribeAllResponse = {
-    id: string;
-    unsubscribed: number;
+    success: boolean;
+    unsubscribedCount: number;
 };
 /**
  * Supported field types for admin UI generation.
@@ -314,6 +307,136 @@ type SubscribePayload = {
 type UnsubscribePayload = {
     entryId: string;
 };
+/**
+ * The Socket.io room for an entity subscription: `{serviceName}:{entryId}`.
+ *
+ * Static counterpart to `BaseService.getRoomName` — usable from shared
+ * modules and when emitting into *another* service's room without holding
+ * its instance.
+ */
+declare function serviceRoom(serviceName: string, entryId: string): string;
+/**
+ * The room subscribers of an elevated (unfiltered) entity tier join in
+ * addition to {@link serviceRoom}. Emission targets it via
+ * `io.to(fullRoom)` + `io.to(room).except(fullRoom)`.
+ */
+declare function serviceFullRoom(serviceName: string, entryId: string): string;
+/**
+ * The room for a collection scope:
+ * `{serviceName}:collection:{collection}:{scopeId}`.
+ * Entity ids are cuids, so this never collides with {@link serviceRoom}.
+ */
+declare function collectionRoom(serviceName: string, collection: string, scopeId: string): string;
+/**
+ * The event name collection deltas are emitted as. Identical to the room
+ * name by design — one event per scope room, no id parsing client-side.
+ */
+declare function collectionEventName(serviceName: string, collection: string, scopeId: string): string;
+/**
+ * The per-user room every authenticated socket joins on connection:
+ * `user:{userId}`. Used for targeted notifications and adapter-safe
+ * revocation (`kickFromCollection`).
+ */
+declare function userRoom(userId: string): string;
+/**
+ * Augmentable map of custom room event names to their payload types.
+ * Empty by default — `emitToRoom` and `useRoomEvents` degrade gracefully to
+ * `string` names and `unknown` payloads until an app augments it:
+ *
+ * @example
+ * ```typescript
+ * // In your app's shared types
+ * declare module "@fitzzero/quickdraw-core" {
+ *   interface QuickdrawEventMap {
+ *     "chat:memberUpdate": { chatId: string; userId: string };
+ *     "presence:changed": { userId: string; online: boolean };
+ *   }
+ * }
+ * ```
+ *
+ * Collection deltas and `{service}:update:{id}` events need no entries here —
+ * they are framework-generated and typed end-to-end by the service generics.
+ */
+interface QuickdrawEventMap {
+}
+/**
+ * Event names accepted by `emitToRoom`/`useRoomEvents`: keys of the
+ * augmented {@link QuickdrawEventMap} (with autocomplete) plus any string.
+ */
+type QuickdrawEventName = (keyof QuickdrawEventMap & string) | (string & Record<never, never>);
+/**
+ * Payload type for a room event: the mapped type when the name is in
+ * {@link QuickdrawEventMap}, `unknown` otherwise.
+ */
+type QuickdrawEventData<E extends string> = E extends keyof QuickdrawEventMap ? QuickdrawEventMap[E] : unknown;
+/**
+ * One page of a collection snapshot, returned by a collection's `snapshot`
+ * query and by the `{service}:collection:subscribe` ack.
+ */
+interface CollectionSnapshotPage<TItem> {
+    items: TItem[];
+    nextCursor: string | null;
+    totalCount: number;
+    /**
+     * Full membership id list for the scope (ids only, cheap select).
+     * Returned on cursor-less (first-page / re-snapshot) requests so clients
+     * can prune rows deleted while disconnected. Omit for unbounded scopes
+     * (e.g. long chat histories) — the client then merges without pruning.
+     */
+    ids?: string[];
+    /**
+     * Set by the server when the scope's id list exceeded the cap (5,000) and
+     * `ids` was dropped — the client degrades to no-prune merges.
+     */
+    idsTruncated?: boolean;
+}
+/** Snapshot page plus the revision captured before the query ran. */
+type CollectionSnapshotResponse<TItem> = CollectionSnapshotPage<TItem> & {
+    rev: number;
+};
+/**
+ * Payload for `{service}:collection:subscribe`. Cursor-less calls join the
+ * scope room and may include `ids`; cursor-bearing calls are pure paging —
+ * no room join, no `ids`.
+ */
+type CollectionSubscribePayload = {
+    collection: string;
+    scopeId: string;
+    cursor?: string | null;
+    limit?: number;
+};
+/** Payload for `{service}:collection:unsubscribe`. */
+type CollectionUnsubscribePayload = {
+    collection: string;
+    scopeId: string;
+};
+/**
+ * A collection change, emitted to the scope room under the event name
+ * {@link collectionEventName}.
+ *
+ * `rev` is per-item last-writer-wins: clients ignore an `added`/`updated`
+ * older than what they hold for that id, and snapshot items only overwrite
+ * cached items whose rev predates the snapshot rev. Revisions are epoch
+ * milliseconds (`Date.now()` at emit, or the collection's `revOf`).
+ */
+type CollectionDelta<TItem extends {
+    id: string;
+}> = {
+    type: "added";
+    item: TItem;
+    rev: number;
+} | {
+    type: "updated";
+    item: TItem;
+    rev: number;
+} | {
+    type: "removed";
+    id: string;
+    rev: number;
+} | {
+    type: "reset";
+    rev: number;
+};
 /**
  * Extracts payload type from a service method definition
  */
@@ -341,4 +464,4 @@ interface Logger {
  */
 declare const consoleLogger: Logger;
 
-export { type ACE, type ACL, type ACLEntity, type AccessLevel, type AdminCreatePayload, type AdminDeletePayload, type AdminDeleteResponse, type AdminFieldConfig, type AdminFieldType, type AdminGetPayload, type AdminGetSubscribersPayload, type AdminGetSubscribersResponse, type AdminListPayload, type AdminListResponse, type AdminMetaPayload, type AdminMetaResponse, type AdminReemitPayload, type AdminReemitResponse, type AdminServiceMeta, type AdminSetEntryACLPayload, type AdminUnsubscribeAllPayload, type AdminUnsubscribeAllResponse, type AdminUpdatePayload, CHANNEL_EVENT_PREFIX, type ExtractPayload, type ExtractResponse, type Logger, type QuickdrawUser, type ServiceChannelContext, type ServiceChannelDefinition, type ServiceChannelMap, type ServiceMethodContext, type ServiceMethodDefinition, type ServiceMethodMap, type ServiceResponse, type SubscribePayload, type UnsubscribePayload, channelEventName, consoleLogger };
+export { type ACE, type ACL, type ACLEntity, type AccessLevel, type AdminCreatePayload, type AdminDeletePayload, type AdminDeleteResponse, type AdminFieldConfig, type AdminFieldType, type AdminGetPayload, type AdminGetSubscribersPayload, type AdminListPayload, type AdminListResponse, type AdminMetaPayload, type AdminMetaResponse, type AdminReemitPayload, type AdminReemitResponse, type AdminServiceMeta, type AdminSetACLPayload, type AdminSubscribersResponse, type AdminUnsubscribeAllPayload, type AdminUnsubscribeAllResponse, type AdminUpdatePayload, CHANNEL_EVENT_PREFIX, type CollectionDelta, type CollectionSnapshotPage, type CollectionSnapshotResponse, type CollectionSubscribePayload, type CollectionUnsubscribePayload, type ExtractPayload, type ExtractResponse, type Logger, type QuickdrawEventData, type QuickdrawEventMap, type QuickdrawEventName, type QuickdrawUser, type ServiceChannelContext, type ServiceChannelDefinition, type ServiceChannelMap, type ServiceMethodContext, type ServiceMethodDefinition, type ServiceMethodMap, type ServiceResponse, type SubscribePayload, type UnsubscribePayload, channelEventName, collectionEventName, collectionRoom, consoleLogger, serviceFullRoom, serviceRoom, userRoom };

package/dist/shared/index.js

@@ -3,6 +3,21 @@ function channelEventName(serviceName, channelName) {
   return `channel:${serviceName}:${channelName}`;
 }
 var CHANNEL_EVENT_PREFIX = "channel:";
+function serviceRoom(serviceName, entryId) {
+  return `${serviceName}:${entryId}`;
+}
+function serviceFullRoom(serviceName, entryId) {
+  return `${serviceRoom(serviceName, entryId)}:full`;
+}
+function collectionRoom(serviceName, collection, scopeId) {
+  return `${serviceName}:collection:${collection}:${scopeId}`;
+}
+function collectionEventName(serviceName, collection, scopeId) {
+  return collectionRoom(serviceName, collection, scopeId);
+}
+function userRoom(userId) {
+  return `user:${userId}`;
+}
 var consoleLogger = {
   info: (message, meta) => console.log(`[INFO] ${message}`, meta ?? ""),
   warn: (message, meta) => console.warn(`[WARN] ${message}`, meta ?? ""),
@@ -11,6 +26,6 @@ var consoleLogger = {
   child: () => consoleLogger
 };
 
-export { CHANNEL_EVENT_PREFIX, channelEventName, consoleLogger };
+export { CHANNEL_EVENT_PREFIX, channelEventName, collectionEventName, collectionRoom, consoleLogger, serviceFullRoom, serviceRoom, userRoom };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/shared/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/shared/types.ts"],"names":[],"mappings":";AAoNO,SAAS,gBAAA,CAAiB,aAAqB,WAAA,EAA6B;AACjF,EAAA,OAAO,CAAA,QAAA,EAAW,WAAW,CAAA,CAAA,EAAI,WAAW,CAAA,CAAA;AAC9C;AAOO,IAAM,oBAAA,GAAuB;AAoK7B,IAAM,aAAA,GAAwB;AAAA,EACnC,IAAA,EAAM,CAAC,OAAA,EAAS,IAAA,KAAS,OAAA,CAAQ,IAAI,CAAA,OAAA,EAAU,OAAO,CAAA,CAAA,EAAI,IAAA,IAAQ,EAAE,CAAA;AAAA,EACpE,IAAA,EAAM,CAAC,OAAA,EAAS,IAAA,KAAS,OAAA,CAAQ,KAAK,CAAA,OAAA,EAAU,OAAO,CAAA,CAAA,EAAI,IAAA,IAAQ,EAAE,CAAA;AAAA,EACrE,KAAA,EAAO,CAAC,OAAA,EAAS,IAAA,KAAS,OAAA,CAAQ,MAAM,CAAA,QAAA,EAAW,OAAO,CAAA,CAAA,EAAI,IAAA,IAAQ,EAAE,CAAA;AAAA,EACxE,KAAA,EAAO,CAAC,OAAA,EAAS,IAAA,KAAS,OAAA,CAAQ,MAAM,CAAA,QAAA,EAAW,OAAO,CAAA,CAAA,EAAI,IAAA,IAAQ,EAAE,CAAA;AAAA,EACxE,OAAO,MAAM;AACf","file":"index.js","sourcesContent":["import type { z } from \"zod\";\n\n// ============================================================================\n// Access Control Types\n// ============================================================================\n\nexport type AccessLevel = \"Public\" | \"Read\" | \"Moderate\" | \"Admin\";\n\nexport type ACE = {\n  userId: string;\n  level: AccessLevel;\n};\n\nexport type ACL = ACE[];\n\n// ============================================================================\n// Entity and User Interfaces for ACL\n// ============================================================================\n\n/**\n * Interface for entities that support entry-level ACL stored as JSON.\n *\n * Use this pattern when:\n * - You want simple ACL without a separate membership table\n * - Access patterns are straightforward (read/write permissions)\n * - You don't need to query \"all entities user X can access\" efficiently\n *\n * The default `checkEntryACL` in BaseService expects entities to have this shape.\n *\n * @example\n * ```prisma\n * model Document {\n *   id    String @id @default(cuid())\n *   title String\n *   acl   Json?  // Stores ACL array\n * }\n * ```\n *\n * @example\n * ```typescript\n * class DocumentService extends BaseService<Document & ACLEntity, ...> {\n *   constructor(prisma: PrismaClient) {\n *     super({ serviceName: 'documentService', hasEntryACL: true });\n *     this.setDelegate(prisma.document);\n *     // Default checkEntryACL will work automatically\n *   }\n * }\n * ```\n */\nexport interface ACLEntity {\n  id: string;\n  acl?: ACL | null;\n}\n\n/**\n * Interface for users with service-level access control.\n *\n * The `serviceAccess` field maps service names to access levels, granting\n * blanket permissions across all entries in that service.\n *\n * @example\n * ```prisma\n * model User {\n *   id            String @id @default(cuid())\n *   serviceAccess Json?  // { \"chatService\": \"Admin\", \"documentService\": \"Read\" }\n * }\n * ```\n *\n * @example\n * ```typescript\n * // User with Admin access to chatService can perform any operation\n * // on any chat, regardless of entry-level ACL\n * const user: QuickdrawUser = {\n *   id: \"user-123\",\n *   serviceAccess: { chatService: \"Admin\" }\n * };\n * ```\n */\nexport interface QuickdrawUser {\n  id: string;\n  serviceAccess?: Record<string, AccessLevel> | null;\n}\n\n// ============================================================================\n// Service Response Types\n// ============================================================================\n\nexport type ServiceResponse<T = unknown> =\n  | { success: true; data: T }\n  | { success: false; error: string; code?: number };\n\n// ============================================================================\n// Service Method Definition Types\n// ============================================================================\n\n/**\n * Defines the shape of a service method including its payload and response types.\n * Used to create a type-safe contract between server and client.\n */\nexport interface ServiceMethodDefinition<TPayload = unknown, TResponse = unknown> {\n  name: string;\n  access: AccessLevel;\n  handler: (payload: TPayload, context: ServiceMethodContext) => Promise<TResponse>;\n  schema?: z.ZodType<TPayload>;\n  resolveEntryId?: (payload: TPayload) => string | null;\n}\n\n/**\n * Context provided to service method handlers\n */\nexport interface ServiceMethodContext {\n  userId: string | undefined;\n  socketId: string;\n  serviceAccess: Record<string, AccessLevel>;\n}\n\n/**\n * Type helper for defining service method maps.\n * Each service should define its methods using this structure.\n *\n * @example\n * ```typescript\n * type ChatServiceMethods = ServiceMethodMap<{\n *   createChat: {\n *     payload: { title: string };\n *     response: { id: string };\n *   };\n *   updateTitle: {\n *     payload: { id: string; title: string };\n *     response: { id: string; title: string };\n *   };\n * }>;\n * ```\n */\nexport type ServiceMethodMap<T extends Record<string, { payload: unknown; response: unknown }>> = T;\n\n// ============================================================================\n// Service Channel Types (high-frequency, fire-and-forget events)\n// ============================================================================\n\n/**\n * Channels are the high-frequency counterpart to service methods.\n *\n * Where methods are request/response (ack'd, ACL-checked against the database,\n * counted by the global rate limiter), channels are fire-and-forget: no ack,\n * no response, validated and access-checked entirely in memory, and governed\n * by a per-channel token bucket instead of the global limiter. Use them for\n * traffic where per-message overhead matters and losing a message is fine —\n * game input, cursor positions, typing indicators, telemetry.\n *\n * Wire format: channels route as the Socket.io event\n * `channel:<serviceName>:<channelName>` (see {@link channelEventName}).\n * Clients should emit them volatile; servers broadcast tick data back with\n * `emitToRoomVolatile` so backpressured clients drop frames instead of\n * queueing them.\n *\n * Access model (all checks synchronous, zero DB reads):\n * - Authentication is always required — anonymous sockets are dropped silently.\n * - `\"Public\"` / `\"Read\"` access: any authenticated user passes the service gate.\n * - `\"Moderate\"` / `\"Admin\"`: requires that level in the socket's in-memory\n *   `serviceAccess`.\n * - Entry-level access is expressed via `requireRoom`: the payload resolves to\n *   a room name and the socket must already be in that room. Room membership\n *   was ACL-checked at subscribe time, so this inherits full entry ACL\n *   semantics without touching the database on the hot path.\n */\nexport interface ServiceChannelDefinition<TPayload = unknown> {\n  name: string;\n  access: AccessLevel;\n  handler: (payload: TPayload, context: ServiceChannelContext) => void;\n  /** Required — channel payloads are untrusted high-frequency input. */\n  schema: z.ZodType<TPayload>;\n  /** Sustained messages per second allowed per socket. */\n  ratePerSecond: number;\n  /** Bucket capacity — short bursts above ratePerSecond up to this size. */\n  burst: number;\n  /**\n   * Resolve a room the socket must already be a member of (typically the\n   * service room joined via subscribe). Return null to skip the check.\n   */\n  requireRoom?: (payload: TPayload) => string | null;\n}\n\n/**\n * Context provided to channel handlers. Unlike ServiceMethodContext,\n * userId is always present — unauthenticated channel messages are dropped\n * before the handler runs.\n */\nexport interface ServiceChannelContext {\n  userId: string;\n  socketId: string;\n  serviceAccess: Record<string, AccessLevel>;\n}\n\n/**\n * Type helper for defining service channel maps (payload-only — channels\n * have no response).\n *\n * @example\n * ```typescript\n * type GameServiceChannels = ServiceChannelMap<{\n *   input: { seq: number; dx: number; dy: number; boost: boolean };\n * }>;\n * ```\n */\nexport type ServiceChannelMap<T extends Record<string, unknown>> = T;\n\n/**\n * The Socket.io event name a channel routes as.\n * Shared by the server registry, the React client, and non-JS clients\n * (e.g. the Godot addon) so the wire contract lives in one place.\n */\nexport function channelEventName(serviceName: string, channelName: string): string {\n  return `channel:${serviceName}:${channelName}`;\n}\n\n/**\n * Prefix for all channel events — pass to the rate limiter's\n * `excludePrefixes` so channel traffic bypasses the global request limiter\n * (channels enforce their own per-socket token buckets).\n */\nexport const CHANNEL_EVENT_PREFIX = \"channel:\";\n\n// ============================================================================\n// Admin Method Types (Generic shapes for all services)\n// ============================================================================\n\nexport type AdminListPayload = {\n  page?: number;\n  pageSize?: number;\n  sort?: {\n    field?: string;\n    direction?: \"asc\" | \"desc\";\n  };\n  filter?: {\n    id?: string;\n    ids?: string[];\n    createdAfter?: string;\n    createdBefore?: string;\n    updatedAfter?: string;\n    updatedBefore?: string;\n  } & Record<string, unknown>;\n};\n\nexport type AdminListResponse<T> = {\n  rows: T[];\n  page: number;\n  pageSize: number;\n  total: number;\n};\n\nexport type AdminGetPayload = { id: string };\n\nexport type AdminCreatePayload<TInsert> = { data: Partial<TInsert> };\n\nexport type AdminUpdatePayload<TInsert> = {\n  id: string;\n  data: Partial<TInsert>;\n};\n\nexport type AdminDeletePayload = { id: string };\nexport type AdminDeleteResponse = { id: string; deleted: true };\n\nexport type AdminSetEntryACLPayload = {\n  id: string;\n  acl: ACL;\n};\n\nexport type AdminGetSubscribersPayload = { id: string };\nexport type AdminGetSubscribersResponse = {\n  id: string;\n  subscribers: Array<{ socketId: string; userId?: string }>;\n};\n\nexport type AdminReemitPayload = { id: string };\nexport type AdminReemitResponse = { emitted: boolean };\n\nexport type AdminUnsubscribeAllPayload = { id: string };\nexport type AdminUnsubscribeAllResponse = { id: string; unsubscribed: number };\n\n// ============================================================================\n// Admin Field Configuration Types\n// ============================================================================\n\n/**\n * Supported field types for admin UI generation.\n */\nexport type AdminFieldType =\n  | \"string\"\n  | \"number\"\n  | \"boolean\"\n  | \"date\"\n  | \"enum\"\n  | \"json\"\n  | \"relation\";\n\n/**\n * Configuration for a single field in the admin UI.\n * Derived from Zod schemas with optional overrides.\n */\nexport interface AdminFieldConfig {\n  /** Field name (property key on the entity) */\n  name: string;\n  /** Field type for rendering appropriate input */\n  type: AdminFieldType;\n  /** Human-readable label */\n  label: string;\n  /** Whether the field is required for creation */\n  required: boolean;\n  /** Whether the field can be edited (false for id, createdAt, etc.) */\n  editable: boolean;\n  /** Whether to show this field as a table column */\n  showInTable: boolean;\n  /** Whether the table can be sorted by this field */\n  sortable: boolean;\n  /** For enum fields, the allowed values */\n  enumValues?: string[];\n  /** For relation fields, the related service name */\n  relationService?: string;\n}\n\n/**\n * Service metadata for admin UI generation.\n * Returned by the adminMeta method.\n */\nexport interface AdminServiceMeta {\n  /** Internal service name (e.g., \"chatService\") */\n  serviceName: string;\n  /** Human-readable display name (e.g., \"Chats\") */\n  displayName: string;\n  /** Field configurations derived from schema */\n  fields: AdminFieldConfig[];\n}\n\n/**\n * Payload for adminMeta method (no parameters needed)\n */\nexport type AdminMetaPayload = Record<string, never>;\n\n/**\n * Response type for adminMeta method\n */\nexport type AdminMetaResponse = AdminServiceMeta;\n\n// ============================================================================\n// Subscription Types\n// ============================================================================\n\nexport type SubscribePayload = {\n  entryId: string;\n  requiredLevel?: AccessLevel;\n};\n\nexport type UnsubscribePayload = {\n  entryId: string;\n};\n\n// ============================================================================\n// Utility Types\n// ============================================================================\n\n/**\n * Extracts payload type from a service method definition\n */\nexport type ExtractPayload<T> = T extends { payload: infer P } ? P : never;\n\n/**\n * Extracts response type from a service method definition\n */\nexport type ExtractResponse<T> = T extends { response: infer R } ? R : never;\n\n/**\n * Logger interface compatible with Winston and other loggers\n */\nexport interface Logger {\n  info(message: string, meta?: Record<string, unknown>): void;\n  warn(message: string, meta?: Record<string, unknown>): void;\n  error(message: string, meta?: Record<string, unknown>): void;\n  debug(message: string, meta?: Record<string, unknown>): void;\n  child(options: Record<string, unknown>): Logger;\n}\n\n/**\n * Default console logger implementation\n */\nexport const consoleLogger: Logger = {\n  info: (message, meta) => console.log(`[INFO] ${message}`, meta ?? \"\"),\n  warn: (message, meta) => console.warn(`[WARN] ${message}`, meta ?? \"\"),\n  error: (message, meta) => console.error(`[ERROR] ${message}`, meta ?? \"\"),\n  debug: (message, meta) => console.debug(`[DEBUG] ${message}`, meta ?? \"\"),\n  child: () => consoleLogger,\n};\n"]}
+{"version":3,"sources":["../../src/shared/types.ts"],"names":[],"mappings":";AAoNO,SAAS,gBAAA,CAAiB,aAAqB,WAAA,EAA6B;AACjF,EAAA,OAAO,CAAA,QAAA,EAAW,WAAW,CAAA,CAAA,EAAI,WAAW,CAAA,CAAA;AAC9C;AAOO,IAAM,oBAAA,GAAuB;AA8I7B,SAAS,WAAA,CAAY,aAAqB,OAAA,EAAyB;AACxE,EAAA,OAAO,CAAA,EAAG,WAAW,CAAA,CAAA,EAAI,OAAO,CAAA,CAAA;AAClC;AAOO,SAAS,eAAA,CAAgB,aAAqB,OAAA,EAAyB;AAC5E,EAAA,OAAO,CAAA,EAAG,WAAA,CAAY,WAAA,EAAa,OAAO,CAAC,CAAA,KAAA,CAAA;AAC7C;AAOO,SAAS,cAAA,CAAe,WAAA,EAAqB,UAAA,EAAoB,OAAA,EAAyB;AAC/F,EAAA,OAAO,CAAA,EAAG,WAAW,CAAA,YAAA,EAAe,UAAU,IAAI,OAAO,CAAA,CAAA;AAC3D;AAMO,SAAS,mBAAA,CACd,WAAA,EACA,UAAA,EACA,OAAA,EACQ;AACR,EAAA,OAAO,cAAA,CAAe,WAAA,EAAa,UAAA,EAAY,OAAO,CAAA;AACxD;AAOO,SAAS,SAAS,MAAA,EAAwB;AAC/C,EAAA,OAAO,QAAQ,MAAM,CAAA,CAAA;AACvB;AAsIO,IAAM,aAAA,GAAwB;AAAA,EACnC,IAAA,EAAM,CAAC,OAAA,EAAS,IAAA,KAAS,OAAA,CAAQ,IAAI,CAAA,OAAA,EAAU,OAAO,CAAA,CAAA,EAAI,IAAA,IAAQ,EAAE,CAAA;AAAA,EACpE,IAAA,EAAM,CAAC,OAAA,EAAS,IAAA,KAAS,OAAA,CAAQ,KAAK,CAAA,OAAA,EAAU,OAAO,CAAA,CAAA,EAAI,IAAA,IAAQ,EAAE,CAAA;AAAA,EACrE,KAAA,EAAO,CAAC,OAAA,EAAS,IAAA,KAAS,OAAA,CAAQ,MAAM,CAAA,QAAA,EAAW,OAAO,CAAA,CAAA,EAAI,IAAA,IAAQ,EAAE,CAAA;AAAA,EACxE,KAAA,EAAO,CAAC,OAAA,EAAS,IAAA,KAAS,OAAA,CAAQ,MAAM,CAAA,QAAA,EAAW,OAAO,CAAA,CAAA,EAAI,IAAA,IAAQ,EAAE,CAAA;AAAA,EACxE,OAAO,MAAM;AACf","file":"index.js","sourcesContent":["import type { z } from \"zod\";\n\n// ============================================================================\n// Access Control Types\n// ============================================================================\n\nexport type AccessLevel = \"Public\" | \"Read\" | \"Moderate\" | \"Admin\";\n\nexport type ACE = {\n  userId: string;\n  level: AccessLevel;\n};\n\nexport type ACL = ACE[];\n\n// ============================================================================\n// Entity and User Interfaces for ACL\n// ============================================================================\n\n/**\n * Interface for entities that support entry-level ACL stored as JSON.\n *\n * Use this pattern when:\n * - You want simple ACL without a separate membership table\n * - Access patterns are straightforward (read/write permissions)\n * - You don't need to query \"all entities user X can access\" efficiently\n *\n * The default `checkEntryACL` in BaseService expects entities to have this shape.\n *\n * @example\n * ```prisma\n * model Document {\n *   id    String @id @default(cuid())\n *   title String\n *   acl   Json?  // Stores ACL array\n * }\n * ```\n *\n * @example\n * ```typescript\n * class DocumentService extends BaseService<Document & ACLEntity, ...> {\n *   constructor(prisma: PrismaClient) {\n *     super({ serviceName: 'documentService', hasEntryACL: true });\n *     this.setDelegate(prisma.document);\n *     // Default checkEntryACL will work automatically\n *   }\n * }\n * ```\n */\nexport interface ACLEntity {\n  id: string;\n  acl?: ACL | null;\n}\n\n/**\n * Interface for users with service-level access control.\n *\n * The `serviceAccess` field maps service names to access levels, granting\n * blanket permissions across all entries in that service.\n *\n * @example\n * ```prisma\n * model User {\n *   id            String @id @default(cuid())\n *   serviceAccess Json?  // { \"chatService\": \"Admin\", \"documentService\": \"Read\" }\n * }\n * ```\n *\n * @example\n * ```typescript\n * // User with Admin access to chatService can perform any operation\n * // on any chat, regardless of entry-level ACL\n * const user: QuickdrawUser = {\n *   id: \"user-123\",\n *   serviceAccess: { chatService: \"Admin\" }\n * };\n * ```\n */\nexport interface QuickdrawUser {\n  id: string;\n  serviceAccess?: Record<string, AccessLevel> | null;\n}\n\n// ============================================================================\n// Service Response Types\n// ============================================================================\n\nexport type ServiceResponse<T = unknown> =\n  | { success: true; data: T }\n  | { success: false; error: string; code?: number };\n\n// ============================================================================\n// Service Method Definition Types\n// ============================================================================\n\n/**\n * Defines the shape of a service method including its payload and response types.\n * Used to create a type-safe contract between server and client.\n */\nexport interface ServiceMethodDefinition<TPayload = unknown, TResponse = unknown> {\n  name: string;\n  access: AccessLevel;\n  handler: (payload: TPayload, context: ServiceMethodContext) => Promise<TResponse>;\n  schema?: z.ZodType<TPayload>;\n  resolveEntryId?: (payload: TPayload) => string | null;\n}\n\n/**\n * Context provided to service method handlers\n */\nexport interface ServiceMethodContext {\n  userId: string | undefined;\n  socketId: string;\n  serviceAccess: Record<string, AccessLevel>;\n}\n\n/**\n * Type helper for defining service method maps.\n * Each service should define its methods using this structure.\n *\n * @example\n * ```typescript\n * type ChatServiceMethods = ServiceMethodMap<{\n *   createChat: {\n *     payload: { title: string };\n *     response: { id: string };\n *   };\n *   updateTitle: {\n *     payload: { id: string; title: string };\n *     response: { id: string; title: string };\n *   };\n * }>;\n * ```\n */\nexport type ServiceMethodMap<T extends Record<string, { payload: unknown; response: unknown }>> = T;\n\n// ============================================================================\n// Service Channel Types (high-frequency, fire-and-forget events)\n// ============================================================================\n\n/**\n * Channels are the high-frequency counterpart to service methods.\n *\n * Where methods are request/response (ack'd, ACL-checked against the database,\n * counted by the global rate limiter), channels are fire-and-forget: no ack,\n * no response, validated and access-checked entirely in memory, and governed\n * by a per-channel token bucket instead of the global limiter. Use them for\n * traffic where per-message overhead matters and losing a message is fine —\n * game input, cursor positions, typing indicators, telemetry.\n *\n * Wire format: channels route as the Socket.io event\n * `channel:<serviceName>:<channelName>` (see {@link channelEventName}).\n * Clients should emit them volatile; servers broadcast tick data back with\n * `emitToRoomVolatile` so backpressured clients drop frames instead of\n * queueing them.\n *\n * Access model (all checks synchronous, zero DB reads):\n * - Authentication is always required — anonymous sockets are dropped silently.\n * - `\"Public\"` / `\"Read\"` access: any authenticated user passes the service gate.\n * - `\"Moderate\"` / `\"Admin\"`: requires that level in the socket's in-memory\n *   `serviceAccess`.\n * - Entry-level access is expressed via `requireRoom`: the payload resolves to\n *   a room name and the socket must already be in that room. Room membership\n *   was ACL-checked at subscribe time, so this inherits full entry ACL\n *   semantics without touching the database on the hot path.\n */\nexport interface ServiceChannelDefinition<TPayload = unknown> {\n  name: string;\n  access: AccessLevel;\n  handler: (payload: TPayload, context: ServiceChannelContext) => void;\n  /** Required — channel payloads are untrusted high-frequency input. */\n  schema: z.ZodType<TPayload>;\n  /** Sustained messages per second allowed per socket. */\n  ratePerSecond: number;\n  /** Bucket capacity — short bursts above ratePerSecond up to this size. */\n  burst: number;\n  /**\n   * Resolve a room the socket must already be a member of (typically the\n   * service room joined via subscribe). Return null to skip the check.\n   */\n  requireRoom?: (payload: TPayload) => string | null;\n}\n\n/**\n * Context provided to channel handlers. Unlike ServiceMethodContext,\n * userId is always present — unauthenticated channel messages are dropped\n * before the handler runs.\n */\nexport interface ServiceChannelContext {\n  userId: string;\n  socketId: string;\n  serviceAccess: Record<string, AccessLevel>;\n}\n\n/**\n * Type helper for defining service channel maps (payload-only — channels\n * have no response).\n *\n * @example\n * ```typescript\n * type GameServiceChannels = ServiceChannelMap<{\n *   input: { seq: number; dx: number; dy: number; boost: boolean };\n * }>;\n * ```\n */\nexport type ServiceChannelMap<T extends Record<string, unknown>> = T;\n\n/**\n * The Socket.io event name a channel routes as.\n * Shared by the server registry, the React client, and non-JS clients\n * (e.g. the Godot addon) so the wire contract lives in one place.\n */\nexport function channelEventName(serviceName: string, channelName: string): string {\n  return `channel:${serviceName}:${channelName}`;\n}\n\n/**\n * Prefix for all channel events — pass to the rate limiter's\n * `excludePrefixes` so channel traffic bypasses the global request limiter\n * (channels enforce their own per-socket token buckets).\n */\nexport const CHANNEL_EVENT_PREFIX = \"channel:\";\n\n// ============================================================================\n// Admin Method Types (Generic shapes for all services)\n// ============================================================================\n// One canonical shape per admin method, matching what BaseService actually\n// sends and receives on the wire. (Before 4.0 these were declared twice —\n// here and in server/types.ts — with different shapes; the server shapes won.)\n\nexport type AdminListPayload = {\n  page?: number;\n  pageSize?: number;\n  where?: Record<string, unknown>;\n  orderBy?: Record<string, \"asc\" | \"desc\">;\n};\n\nexport type AdminListResponse<T> = {\n  items: T[];\n  total: number;\n  page: number;\n  pageSize: number;\n  totalPages: number;\n};\n\nexport type AdminGetPayload = { id: string };\n\nexport type AdminCreatePayload<TCreate> = { data: TCreate };\n\nexport type AdminUpdatePayload<TUpdate> = {\n  id: string;\n  data: TUpdate;\n};\n\nexport type AdminDeletePayload = { id: string };\nexport type AdminDeleteResponse = { success: boolean; id: string };\n\nexport type AdminSetACLPayload = {\n  entryId: string;\n  acl: ACL;\n};\n\nexport type AdminGetSubscribersPayload = { entryId: string };\nexport type AdminSubscribersResponse = {\n  entryId: string;\n  subscribers: Array<{ socketId: string; userId: string | null }>;\n  count: number;\n};\n\nexport type AdminReemitPayload = { entryId: string };\nexport type AdminReemitResponse = { success: boolean; subscriberCount: number };\n\nexport type AdminUnsubscribeAllPayload = { entryId: string };\nexport type AdminUnsubscribeAllResponse = { success: boolean; unsubscribedCount: number };\n\n// ============================================================================\n// Admin Field Configuration Types\n// ============================================================================\n\n/**\n * Supported field types for admin UI generation.\n */\nexport type AdminFieldType =\n  | \"string\"\n  | \"number\"\n  | \"boolean\"\n  | \"date\"\n  | \"enum\"\n  | \"json\"\n  | \"relation\";\n\n/**\n * Configuration for a single field in the admin UI.\n * Derived from Zod schemas with optional overrides.\n */\nexport interface AdminFieldConfig {\n  /** Field name (property key on the entity) */\n  name: string;\n  /** Field type for rendering appropriate input */\n  type: AdminFieldType;\n  /** Human-readable label */\n  label: string;\n  /** Whether the field is required for creation */\n  required: boolean;\n  /** Whether the field can be edited (false for id, createdAt, etc.) */\n  editable: boolean;\n  /** Whether to show this field as a table column */\n  showInTable: boolean;\n  /** Whether the table can be sorted by this field */\n  sortable: boolean;\n  /** For enum fields, the allowed values */\n  enumValues?: string[];\n  /** For relation fields, the related service name */\n  relationService?: string;\n}\n\n/**\n * Service metadata for admin UI generation.\n * Returned by the adminMeta method.\n */\nexport interface AdminServiceMeta {\n  /** Internal service name (e.g., \"chatService\") */\n  serviceName: string;\n  /** Human-readable display name (e.g., \"Chats\") */\n  displayName: string;\n  /** Field configurations derived from schema */\n  fields: AdminFieldConfig[];\n}\n\n/**\n * Payload for adminMeta method (no parameters needed)\n */\nexport type AdminMetaPayload = Record<string, never>;\n\n/**\n * Response type for adminMeta method\n */\nexport type AdminMetaResponse = AdminServiceMeta;\n\n// ============================================================================\n// Subscription Types\n// ============================================================================\n\nexport type SubscribePayload = {\n  entryId: string;\n  requiredLevel?: AccessLevel;\n};\n\nexport type UnsubscribePayload = {\n  entryId: string;\n};\n\n// ============================================================================\n// Room Naming (shared between server emitters and client listeners)\n// ============================================================================\n\n/**\n * The Socket.io room for an entity subscription: `{serviceName}:{entryId}`.\n *\n * Static counterpart to `BaseService.getRoomName` — usable from shared\n * modules and when emitting into *another* service's room without holding\n * its instance.\n */\nexport function serviceRoom(serviceName: string, entryId: string): string {\n  return `${serviceName}:${entryId}`;\n}\n\n/**\n * The room subscribers of an elevated (unfiltered) entity tier join in\n * addition to {@link serviceRoom}. Emission targets it via\n * `io.to(fullRoom)` + `io.to(room).except(fullRoom)`.\n */\nexport function serviceFullRoom(serviceName: string, entryId: string): string {\n  return `${serviceRoom(serviceName, entryId)}:full`;\n}\n\n/**\n * The room for a collection scope:\n * `{serviceName}:collection:{collection}:{scopeId}`.\n * Entity ids are cuids, so this never collides with {@link serviceRoom}.\n */\nexport function collectionRoom(serviceName: string, collection: string, scopeId: string): string {\n  return `${serviceName}:collection:${collection}:${scopeId}`;\n}\n\n/**\n * The event name collection deltas are emitted as. Identical to the room\n * name by design — one event per scope room, no id parsing client-side.\n */\nexport function collectionEventName(\n  serviceName: string,\n  collection: string,\n  scopeId: string,\n): string {\n  return collectionRoom(serviceName, collection, scopeId);\n}\n\n/**\n * The per-user room every authenticated socket joins on connection:\n * `user:{userId}`. Used for targeted notifications and adapter-safe\n * revocation (`kickFromCollection`).\n */\nexport function userRoom(userId: string): string {\n  return `user:${userId}`;\n}\n\n// ============================================================================\n// Typed Room Events\n// ============================================================================\n\n/**\n * Augmentable map of custom room event names to their payload types.\n * Empty by default — `emitToRoom` and `useRoomEvents` degrade gracefully to\n * `string` names and `unknown` payloads until an app augments it:\n *\n * @example\n * ```typescript\n * // In your app's shared types\n * declare module \"@fitzzero/quickdraw-core\" {\n *   interface QuickdrawEventMap {\n *     \"chat:memberUpdate\": { chatId: string; userId: string };\n *     \"presence:changed\": { userId: string; online: boolean };\n *   }\n * }\n * ```\n *\n * Collection deltas and `{service}:update:{id}` events need no entries here —\n * they are framework-generated and typed end-to-end by the service generics.\n */\n// oxlint-disable-next-line typescript/no-empty-interface, typescript/no-empty-object-type\nexport interface QuickdrawEventMap {}\n\n/**\n * Event names accepted by `emitToRoom`/`useRoomEvents`: keys of the\n * augmented {@link QuickdrawEventMap} (with autocomplete) plus any string.\n */\nexport type QuickdrawEventName =\n  | (keyof QuickdrawEventMap & string)\n  | (string & Record<never, never>);\n\n/**\n * Payload type for a room event: the mapped type when the name is in\n * {@link QuickdrawEventMap}, `unknown` otherwise.\n */\nexport type QuickdrawEventData<E extends string> = E extends keyof QuickdrawEventMap\n  ? QuickdrawEventMap[E]\n  : unknown;\n\n// ============================================================================\n// Collection Subscription Types (wire protocol)\n// ============================================================================\n\n/**\n * One page of a collection snapshot, returned by a collection's `snapshot`\n * query and by the `{service}:collection:subscribe` ack.\n */\nexport interface CollectionSnapshotPage<TItem> {\n  items: TItem[];\n  nextCursor: string | null;\n  totalCount: number;\n  /**\n   * Full membership id list for the scope (ids only, cheap select).\n   * Returned on cursor-less (first-page / re-snapshot) requests so clients\n   * can prune rows deleted while disconnected. Omit for unbounded scopes\n   * (e.g. long chat histories) — the client then merges without pruning.\n   */\n  ids?: string[];\n  /**\n   * Set by the server when the scope's id list exceeded the cap (5,000) and\n   * `ids` was dropped — the client degrades to no-prune merges.\n   */\n  idsTruncated?: boolean;\n}\n\n/** Snapshot page plus the revision captured before the query ran. */\nexport type CollectionSnapshotResponse<TItem> = CollectionSnapshotPage<TItem> & { rev: number };\n\n/**\n * Payload for `{service}:collection:subscribe`. Cursor-less calls join the\n * scope room and may include `ids`; cursor-bearing calls are pure paging —\n * no room join, no `ids`.\n */\nexport type CollectionSubscribePayload = {\n  collection: string;\n  scopeId: string;\n  cursor?: string | null;\n  limit?: number;\n};\n\n/** Payload for `{service}:collection:unsubscribe`. */\nexport type CollectionUnsubscribePayload = {\n  collection: string;\n  scopeId: string;\n};\n\n/**\n * A collection change, emitted to the scope room under the event name\n * {@link collectionEventName}.\n *\n * `rev` is per-item last-writer-wins: clients ignore an `added`/`updated`\n * older than what they hold for that id, and snapshot items only overwrite\n * cached items whose rev predates the snapshot rev. Revisions are epoch\n * milliseconds (`Date.now()` at emit, or the collection's `revOf`).\n */\nexport type CollectionDelta<TItem extends { id: string }> =\n  | { type: \"added\"; item: TItem; rev: number }\n  | { type: \"updated\"; item: TItem; rev: number }\n  | { type: \"removed\"; id: string; rev: number }\n  | { type: \"reset\"; rev: number };\n\n// ============================================================================\n// Utility Types\n// ============================================================================\n\n/**\n * Extracts payload type from a service method definition\n */\nexport type ExtractPayload<T> = T extends { payload: infer P } ? P : never;\n\n/**\n * Extracts response type from a service method definition\n */\nexport type ExtractResponse<T> = T extends { response: infer R } ? R : never;\n\n/**\n * Logger interface compatible with Winston and other loggers\n */\nexport interface Logger {\n  info(message: string, meta?: Record<string, unknown>): void;\n  warn(message: string, meta?: Record<string, unknown>): void;\n  error(message: string, meta?: Record<string, unknown>): void;\n  debug(message: string, meta?: Record<string, unknown>): void;\n  child(options: Record<string, unknown>): Logger;\n}\n\n/**\n * Default console logger implementation\n */\nexport const consoleLogger: Logger = {\n  info: (message, meta) => console.log(`[INFO] ${message}`, meta ?? \"\"),\n  warn: (message, meta) => console.warn(`[WARN] ${message}`, meta ?? \"\"),\n  error: (message, meta) => console.error(`[ERROR] ${message}`, meta ?? \"\"),\n  debug: (message, meta) => console.debug(`[DEBUG] ${message}`, meta ?? \"\"),\n  child: () => consoleLogger,\n};\n"]}

package/dist/{types-ClgSr90l.d.ts → types-87lWXyNP.d.ts}

@@ -1,7 +1,7 @@
 import { Socket, Server } from 'socket.io';
 import { Server as Server$1 } from 'http';
 import { z } from 'zod';
-import { AccessLevel, ServiceMethodDefinition, ServiceChannelDefinition, Logger, AdminFieldConfig } from './shared/index.js';
+import { AccessLevel, ServiceMethodDefinition, ServiceChannelDefinition, CollectionSubscribePayload, CollectionSnapshotResponse, CollectionUnsubscribePayload, Logger, AdminFieldConfig } from './shared/index.js';
 
 /**
  * Extended Socket type with authentication properties
@@ -9,6 +9,24 @@ import { AccessLevel, ServiceMethodDefinition, ServiceChannelDefinition, Logger,
 interface QuickdrawSocket extends Socket {
     userId?: string;
     serviceAccess?: Record<string, AccessLevel>;
+    /** Principal type from the structured identity (e.g. "user", "taskToken"). */
+    principalType?: string;
+    /** Arbitrary verified claims stamped by `authenticate`. */
+    claims?: Record<string, unknown>;
+}
+/**
+ * Structured result of socket authentication. Lets `authenticate` express
+ * multiple principal types (user JWT, task token, deployment-runner token…)
+ * instead of only a userId.
+ *
+ * Everything is stamped onto the socket: `userId`, `principalType`, `claims`,
+ * and `serviceAccess` (when omitted, `loadServiceAccess(userId)` is consulted).
+ */
+interface QuickdrawIdentity {
+    userId?: string;
+    principalType?: string;
+    claims?: Record<string, unknown>;
+    serviceAccess?: Record<string, AccessLevel>;
 }
 interface QuickdrawServerOptions {
     port: number;
@@ -21,9 +39,16 @@ interface QuickdrawServerOptions {
     auth?: {
         /**
          * Custom authentication function.
-         * Return the userId if authenticated, or throw/return undefined to reject.
+         * Return a userId string or a structured {@link QuickdrawIdentity} if
+         * authenticated; throw or return undefined to reject.
+         */
+        authenticate?: (socket: QuickdrawSocket, auth: Record<string, unknown>) => Promise<string | QuickdrawIdentity | undefined>;
+        /**
+         * Load service-level access for an authenticated user (e.g. from the
+         * user record). Used when the identity result does not carry
+         * `serviceAccess` itself. Defaults to empty access.
          */
-        authenticate?: (socket: QuickdrawSocket, auth: Record<string, unknown>) => Promise<string | undefined>;
+        loadServiceAccess?: (userId: string) => Promise<Record<string, AccessLevel> | null | undefined>;
     };
     logger?: Logger;
     /**
@@ -60,6 +85,12 @@ interface BaseServiceInstance {
     getPublicChannels?: () => ServiceChannelDefinition<unknown>[];
     /** Synchronous in-memory access check for channel messages */
     checkChannelAccess?: (channel: ServiceChannelDefinition<unknown>, socket: QuickdrawSocket, payload: unknown) => boolean;
+    /** Handle a collection subscribe (services without collections may omit) */
+    subscribeCollection?: (payload: CollectionSubscribePayload, socket: QuickdrawSocket) => Promise<CollectionSnapshotResponse<{
+        id: string;
+    }> | null>;
+    /** Handle a collection unsubscribe (services without collections may omit) */
+    unsubscribeCollection?: (payload: CollectionUnsubscribePayload, socket: QuickdrawSocket) => void;
     /** Set Socket.io server instance for room-based broadcasts */
     setIo?: (io: Server) => void;
 }
@@ -118,34 +149,7 @@ interface InstallAdminMethodsOptions {
     /** Override specific field configurations */
     fieldOverrides?: Partial<Record<string, Partial<AdminFieldConfig>>>;
 }
-interface AdminListPayload {
-    page?: number;
-    pageSize?: number;
-    where?: Record<string, unknown>;
-    orderBy?: Record<string, "asc" | "desc">;
-}
-interface AdminListResponse<TEntity> {
-    items: TEntity[];
-    total: number;
-    page: number;
-    pageSize: number;
-    totalPages: number;
-}
-interface AdminSetACLPayload {
-    entryId: string;
-    acl: Array<{
-        userId: string;
-        level: AccessLevel;
-    }>;
-}
-interface AdminSubscribersResponse {
-    entryId: string;
-    subscribers: Array<{
-        socketId: string;
-        userId: string | null;
-    }>;
-    count: number;
-}
+
 /**
  * Generic Prisma delegate type for CRUD operations.
  * This allows BaseService to work with any Prisma model without tight coupling.
@@ -178,4 +182,4 @@ interface PrismaDelegate<TEntity, TCreateInput, TUpdateInput, TWhereUniqueInput
     }) => Promise<number>;
 }
 
-export type { AdminListPayload as A, BaseServiceInstance as B, InstallAdminMethodsOptions as I, PrismaDelegate as P, QuickdrawServerResult as Q, ServiceRegistryInstance as S, QuickdrawSocket as a, BaseServiceOptions as b, AdminListResponse as c, AdminSetACLPayload as d, AdminSubscribersResponse as e, QuickdrawServerOptions as f };
+export type { BaseServiceInstance as B, InstallAdminMethodsOptions as I, PrismaDelegate as P, QuickdrawServerResult as Q, ServiceRegistryInstance as S, QuickdrawSocket as a, BaseServiceOptions as b, QuickdrawServerOptions as c, QuickdrawIdentity as d };

package/dist/{types-DUHPIy_5.d.ts → types-CX5LuC_8.d.ts}

@@ -1,6 +1,6 @@
 import { Socket } from 'socket.io-client';
 import { QueryClient } from '@tanstack/react-query';
-import { AccessLevel, ServiceResponse } from './shared/index.js';
+import { AccessLevel, ServiceResponse, CollectionDelta, QuickdrawEventMap } from './shared/index.js';
 
 interface QuickdrawProviderProps {
     children: React.ReactNode;
@@ -34,6 +34,18 @@ interface QuickdrawProviderProps {
      * must connect with path "/.proxy/api/socket.io".
      */
     socketPath?: string;
+    /**
+     * What to do with TanStack Query caches when the socket reconnects.
+     *
+     * Subscriptions and collections heal themselves on reconnect
+     * (re-subscribe / re-snapshot), but plain `useServiceQuery` reads keep
+     * stale data — room events emitted during the outage are gone for good.
+     * `"invalidate-queries"` (the default) invalidates all queries on
+     * reconnect so active reads refetch. Set `"none"` to opt out.
+     *
+     * @default "invalidate-queries"
+     */
+    reconnectBehavior?: "invalidate-queries" | "none";
 }
 /**
  * Return type for the useChannelSend hook.
@@ -133,6 +145,57 @@ interface UseRoomEventsOptions {
      */
     enabled?: boolean;
 }
+/**
+ * Handler map for useRoomEvents, typed via the augmentable
+ * `QuickdrawEventMap`: known event names get their mapped payload type
+ * (with autocomplete), unknown names degrade to the untyped handler shape.
+ */
+type QuickdrawRoomEventHandlers = {
+    [E in keyof QuickdrawEventMap]?: (data: QuickdrawEventMap[E]) => void;
+} & {
+    [event: string]: ((data: never) => void) | undefined;
+};
+/**
+ * Options for the useCollection hook.
+ */
+interface UseCollectionOptions<TItem extends {
+    id: string;
+}> {
+    /** Whether to subscribe (default: true). */
+    enabled?: boolean;
+    /** Snapshot page size. Default comes from the server definition. */
+    limit?: number;
+    /**
+     * Client-side ordering. Omit to keep server snapshot order (new `added`
+     * items land per `insertPosition`). Should be referentially stable.
+     */
+    compare?: (a: TItem, b: TItem) => number;
+    /** Where `added` items land when no `compare` is set. Default "end". */
+    insertPosition?: "start" | "end";
+    /** Called for every delta received (informational; cache updates are automatic). */
+    onDelta?: (delta: CollectionDelta<TItem>) => void;
+    /** Called when a snapshot or page request fails. */
+    onError?: (error: string) => void;
+}
+/**
+ * Return type for the useCollection hook.
+ */
+interface UseCollectionResult<TItem> {
+    /** Ordered, deduped items of the scope. */
+    items: TItem[];
+    byId: ReadonlyMap<string, TItem>;
+    /** Server-reported scope size (null before the first snapshot). */
+    totalCount: number | null;
+    isLoading: boolean;
+    isError: boolean;
+    error: string | null;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+    /** Fetch the next page (cursor reuse of the subscribe event). */
+    loadMore: () => Promise<void>;
+    /** Manual re-snapshot (also what `reset` deltas trigger, debounced 100ms). */
+    refresh: () => Promise<void>;
+}
 /**
  * Options for the useServiceQuery hook.
  */
@@ -201,6 +264,16 @@ interface UseServiceQueryOptions<TResponse> {
      * ```
      */
     invalidateOn?: string[];
+    /**
+     * Refetch on a fixed interval (milliseconds), passed through to TanStack
+     * Query. `false`/undefined disables interval refetching.
+     */
+    refetchInterval?: number | false;
+    /**
+     * Continue interval refetching while the tab is in the background.
+     * Only meaningful with `refetchInterval`.
+     */
+    refetchIntervalInBackground?: boolean;
 }
 /**
  * Return type for the useServiceQuery hook.
@@ -258,6 +331,13 @@ type SubscriptionDataMap<T extends Record<string, unknown>> = T;
 interface SubscriptionEntry {
     refCount: number;
     cleanup?: () => void;
+    /**
+     * Shared per-subscription state slot. The first acquirer (the owner) may
+     * stash a controller object here so later acquirers of the same key can
+     * drive the shared pipeline (used by useCollection for snapshot/loadMore
+     * dedup across components).
+     */
+    controller?: unknown;
 }
 /**
  * Registry for tracking active subscriptions per socket instance.
@@ -313,6 +393,18 @@ interface QuickdrawSocketContextValue {
     disconnect: () => void;
     subscriptionRegistry: SubscriptionRegistry;
     subscriptionBatcher: SubscriptionBatcher;
+    /**
+     * True while the server has reported this client rate-limited.
+     * `useServiceQuery` pauses reads while set — rejected events still count
+     * against the budget and would re-trip the limiter indefinitely.
+     */
+    isRateLimited: boolean;
+    /**
+     * Report a rate-limit rejection (used internally by hooks; callable by
+     * app code that talks to the socket directly). Pauses reads for
+     * `retryAfterMs` (or a 5s default when the server didn't say).
+     */
+    reportRateLimited: (retryAfterMs?: number) => void;
 }
 
-export type { ClientServiceMethodMap as C, QuickdrawSocketContextValue as Q, SubscriptionDataMap as S, UseServiceOptions as U, QuickdrawProviderProps as a, UseServiceResult as b, UseServiceQueryOptions as c, UseServiceQueryResult as d, UseSubscriptionOptions as e, UseSubscriptionResult as f, UseRoomEventsOptions as g, UseChannelSendResult as h };
+export type { ClientServiceMethodMap as C, QuickdrawSocketContextValue as Q, SubscriptionDataMap as S, UseServiceOptions as U, QuickdrawProviderProps as a, UseServiceResult as b, UseServiceQueryOptions as c, UseServiceQueryResult as d, UseSubscriptionOptions as e, UseSubscriptionResult as f, UseCollectionOptions as g, UseCollectionResult as h, QuickdrawRoomEventHandlers as i, UseRoomEventsOptions as j, UseChannelSendResult as k };

package/eslint-plugin-quickdraw/index.mjs

@@ -1,7 +1,9 @@
 import noCrossServiceMutations from "./rules/no-cross-service-mutations.mjs";
+import noDirectPrismaMutations from "./rules/no-direct-prisma-mutations.mjs";
 import requireZodSchema from "./rules/require-zod-schema.mjs";
 import noServiceMethodRecord from "./rules/no-service-method-record.mjs";
 import noUnsafePayloadCast from "./rules/no-unsafe-payload-cast.mjs";
+import noManualCollectionEvents from "./rules/no-manual-collection-events.mjs";
 import noRawSocketOn from "./rules/no-raw-socket-on.mjs";
 import noRawSocketEmit from "./rules/no-raw-socket-emit.mjs";
 import noRawServiceRoomString from "./rules/no-raw-service-room-string.mjs";
@@ -13,9 +15,11 @@ import noRawTypographyStrings from "./rules/no-raw-typography-strings.mjs";
 export default {
   rules: {
     "no-cross-service-mutations": noCrossServiceMutations,
+    "no-direct-prisma-mutations": noDirectPrismaMutations,
     "require-zod-schema": requireZodSchema,
     "no-service-method-record": noServiceMethodRecord,
     "no-unsafe-payload-cast": noUnsafePayloadCast,
+    "no-manual-collection-events": noManualCollectionEvents,
     "no-raw-socket-on": noRawSocketOn,
     "no-raw-socket-emit": noRawSocketEmit,
     "no-raw-service-room-string": noRawServiceRoomString,