added EntityRecord

Author: kfirstri

src/index.ts

@@ -36,6 +36,7 @@ export * from "./types.js";
 export type {
   EntitiesModule,
   EntityHandler,
+  EntityRecord,
   EntityTypeRegistry,
   RealtimeEventType,
   RealtimeEvent,

src/modules/entities.types.ts

@@ -80,12 +80,37 @@ export type SortField<T> =
   | `+${keyof T & string}`
   | `-${keyof T & string}`;
 
+/**
+ * Fields added by the server to every entity record (id, dates, created_by, etc.).
+ */
+interface ServerEntityFields {
+  /** Unique identifier of the record */
+  id: string;
+  /** ISO 8601 timestamp when the record was created */
+  created_date: string;
+  /** ISO 8601 timestamp when the record was last updated */
+  updated_date: string;
+  /** Email of the user who created the record (may be hidden in some responses) */
+  created_by?: string | null;
+  /** ID of the user who created the record */
+  created_by_id?: string | null;
+  /** Whether the record is sample/seed data */
+  is_sample?: boolean;
+}
+
 /**
  * Registry mapping entity names to their TypeScript types.
- * Augment this interface to enable type-safe entity access.
+ * Augment this interface with your entity schema (user-defined fields only).
  */
 export interface EntityTypeRegistry {}
 
+/**
+ * Full record type for each entity: schema fields + server-injected fields (id, created_date, etc.).
+ */
+export type EntityRecord = {
+  [K in keyof EntityTypeRegistry]: EntityTypeRegistry[K] & ServerEntityFields;
+};
+
 /**
  * Entity handler providing CRUD operations for a specific entity type.
  *
@@ -389,10 +414,10 @@ export interface EntityHandler<T = any> {
 }
 
 /**
- * Typed entities module - maps registry keys to typed handlers.
+ * Typed entities module - maps registry keys to typed handlers (full record type).
  */
 type TypedEntitiesModule = {
-  [K in keyof EntityTypeRegistry]: EntityHandler<EntityTypeRegistry[K]>;
+  [K in keyof EntityTypeRegistry]: EntityHandler<EntityRecord[K]>;
 };
 
 /**