@warpfx/server 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -66,10 +66,20 @@ interface ColumnDef {
     /** Default value for this column when inserting a row without it. */
     default?: unknown;
 }
+/** Table access mode for client sync. */
+type AccessMode = "private" | "public";
 /** Table definition in a warp.schema.json. */
 interface TableDef {
     /** Column definitions keyed by column name. */
     columns: Record<string, ColumnDef>;
+    /**
+     * Client access mode — controls automatic sync to players.
+     *
+     * - `"private"` — Only the owning player receives their rows (scope = primary key).
+     * - `"public"` — All connected players receive all rows.
+     * - Omitted — Server-only, not synced to clients.
+     */
+    access?: AccessMode;
 }
 /** The full warp.schema.json format. */
 interface WarpSchema {
@@ -84,22 +94,22 @@ interface WarpSchema {
 }
 
 /**
- * @warp/server — Typed SDK for Warp server-side module development.
+ * @warpfx/server — Server-side SDK for Warp module development.
  *
- * Provides type-safe access to the Warp core API. Under the hood,
- * all calls go through FiveM's resource exports to the 'warp' resource.
+ * Clean, minimal API for building FiveM server features with Warp.
+ * All calls delegate to the Warp core via FiveM resource exports.
  *
  * Usage:
- *   import { onReady, provide, use, getEvents } from '@warp/server';
+ *   import { action, fn, command, error, table } from '@warpfx/server';
+ *   import { accounts } from './db'; // auto-generated from schema
  *
- *   onReady(() => {
- *     const events = getEvents();
- *     events.on('player:spawned', (data) => { ... });
- *     provide('economy', new EconomyService());
+ *   action('deposit', async (player, { amount }) => {
+ *     const account = accounts.find(player.citizenId);
+ *     accounts.update(player.citizenId, { balance: account.balance + amount });
  *   });
  */
-/** Player lifecycle event data. */
-interface PlayerEventContext {
+/** Player context passed to action/function handlers. */
+interface Player {
     /** FiveM server-side player ID. */
     source: number;
     /** Citizen ID (license identifier). */
@@ -124,63 +134,131 @@ interface PlayerRow {
 type PlayerState = "connecting" | "connected" | "spawned";
 /** Player entity with ECS component access. */
 interface PlayerEntity {
-    /** FiveM server-side player ID. */
     readonly source: number;
-    /** Citizen ID (license identifier). */
     readonly citizenId: string;
-    /** Display name. */
     readonly name: string;
-    /** Discord identifier (e.g. "discord:123456789"), if linked. */
     readonly discordId: string | undefined;
-    /** Steam identifier (e.g. "steam:110000..."), if linked. */
     readonly steamId: string | undefined;
-    /** Current lifecycle state. */
     readonly state: PlayerState;
-    /** Get a component attached to this player. */
     getComponent<T>(component: string): T | undefined;
-    /** Attach or replace a component on this player. */
     setComponent<T>(component: string, data: T): void;
-    /** Check if this player has a specific component. */
     hasComponent(component: string): boolean;
-    /** Remove a component from this player. */
     removeComponent(component: string): boolean;
 }
 /** Typed event bus for server-side and network communication. */
 interface ServerEventBus<TMap extends Record<string, any> = Record<string, any>> {
-    /** Subscribe to a local event. Returns an unsubscribe function. */
     on<K extends string & keyof TMap>(event: K, handler: (data: TMap[K]) => void): () => void;
-    /** Unsubscribe from a local event. */
     off<K extends string & keyof TMap>(event: K, handler: (data: TMap[K]) => void): void;
-    /** Emit a local event to all subscribers. */
     emit<K extends string & keyof TMap>(event: K, data: TMap[K]): void;
-    /** Send an event to a specific client. */
     emitClient<K extends string & keyof TMap>(event: K, target: number, data: TMap[K]): void;
-    /** Broadcast an event to all connected clients. */
     emitAllClients<K extends string & keyof TMap>(event: K, data: TMap[K]): void;
-    /** Listen for events from clients. Returns an unsubscribe function. */
     onClient<K extends string & keyof TMap>(event: K, handler: (source: number, data: TMap[K]) => void): () => void;
-    /** Unsubscribe from a client event. */
     offClient<K extends string & keyof TMap>(event: K, handler: (source: number, data: TMap[K]) => void): void;
 }
 /** ECS-inspired entity component store. */
 interface EntityStore {
-    /** Attach a component to an entity. */
     attach<T>(entityId: string, component: string, data: T): void;
-    /** Get a component from an entity. Returns undefined if not found. */
     get<T>(entityId: string, component: string): T | undefined;
-    /** Remove a component from an entity. */
     detach(entityId: string, component: string): boolean;
-    /** Remove all components for an entity. */
     removeEntity(entityId: string): void;
-    /** Check if an entity has a specific component. */
     has(entityId: string, component: string): boolean;
-    /** Iterate all entities that have a specific component. */
     query<T>(component: string): IterableIterator<[string, T]>;
 }
+/** Table handle for typed database operations. */
+interface Table<T = any> {
+    /** Find a row by primary key. */
+    find(primaryKey: any): T | null;
+    /** Get all rows in the table. */
+    all(): T[];
+    /** Insert a new row. */
+    insert(data: T): Promise<void>;
+    /** Update an existing row by primary key (partial update). */
+    update(primaryKey: any, data: Partial<T>): Promise<void>;
+    /** Delete a row by primary key. */
+    delete(primaryKey: any): Promise<void>;
+}
+/** Parameter hint shown in command autocomplete. */
+interface CommandParam {
+    name: string;
+    help?: string;
+}
+/** Options for command(). */
+interface CommandOptions {
+    description?: string;
+    ace?: string;
+    canUse?: (source: number) => boolean;
+    params?: CommandParam[];
+}
+/** Action error received from the server. */
+interface ActionError {
+    action: string;
+    code: string;
+    message: string;
+}
+/**
+ * Register an action handler that clients can invoke.
+ *
+ * Actions are fire-and-forget mutations — the client sends data,
+ * the server validates and mutates, state syncs back automatically.
+ *
+ * @example
+ * action('deposit', async (player, { amount }) => {
+ *   const account = accounts.find(player.citizenId);
+ *   accounts.update(player.citizenId, { balance: account.balance + amount });
+ * });
+ */
+declare function action(name: string, handler: (player: Player, payload: any) => Promise<void> | void): void;
+/**
+ * Register a server function that clients can call and await a result.
+ *
+ * Unlike actions (fire-and-forget), functions return a value to the caller.
+ * Use for request/response patterns like data fetches or validations.
+ *
+ * @example
+ * fn('getBalance', async (player, { targetId }) => {
+ *   const account = accounts.find(targetId);
+ *   return { balance: account?.balance ?? 0 };
+ * });
+ */
+declare function fn<T = any>(name: string, handler: (player: Player, payload: any) => Promise<T> | T): void;
+/**
+ * Register a chat command with optional autocomplete.
+ *
+ * @example
+ * command('balance', (player) => {
+ *   const account = accounts.find(player.citizenId);
+ *   player.notify(`Balance: $${account.balance}`);
+ * });
+ *
+ * command('give', {
+ *   description: 'Give money to a player',
+ *   params: [{ name: 'id' }, { name: 'amount' }],
+ * }, (player, args) => { ... });
+ */
+declare function command(name: string, handlerOrOptions: CommandOptions | ((player: Player, args: string[], raw: string) => void), handler?: (player: Player, args: string[], raw: string) => void): void;
+/**
+ * Create an error to throw from action/function handlers.
+ * The error is sent back to the client with a structured code and message.
+ *
+ * @example
+ * throw error('NO_ACCOUNT', 'No account found');
+ */
+declare function error(code: string, message?: string): Error;
+/**
+ * Get a table handle for database operations.
+ *
+ * The table name must be the full prefixed name (e.g. 'economy_accounts').
+ * For auto-generated handles with types, use the generated `db.ts` instead.
+ *
+ * @example
+ * const accounts = table<Account>('economy_accounts');
+ * const account = accounts.find(citizenId);
+ * await accounts.update(citizenId, { balance: 500 });
+ */
+declare function table<T = any>(name: string): Table<T>;
 /**
  * Register a callback to run when Warp is fully booted.
  * If Warp is already ready, the callback fires immediately.
- * All other SDK functions should be called inside this callback.
  */
 declare function onReady(cb: () => void): void;
 /** Check if Warp has finished booting. */
@@ -197,91 +275,19 @@ declare function getEntities(): EntityStore;
 declare function getPlayer(citizenId: string): PlayerRow | null;
 /** Get all cached players. */
 declare function getPlayers(): PlayerRow[];
-/**
- * Get the player entity for a citizenId.
- * Returns the entity with lifecycle state and component access.
- */
+/** Get the player entity for a citizenId. */
 declare function getEntity(citizenId: string): PlayerEntity | null;
-/**
- * Transition a player to the "spawned" state.
- * Call after character selection (e.g. from a multichar module).
- * Fires all onPlayerSpawned hooks.
- */
+/** Transition a player to the "spawned" state. */
 declare function spawnPlayer(citizenId: string): void;
-/** Register a callback for when a player connects (database confirmed). */
-declare function onPlayerConnect(cb: (player: PlayerEventContext) => void): void;
-/** Register a callback for when a player spawns (character selected). */
-declare function onPlayerSpawned(cb: (player: PlayerEventContext) => void): void;
+/** Register a callback for when a player connects. */
+declare function onPlayerConnect(cb: (player: Player) => void): void;
+/** Register a callback for when a player spawns. */
+declare function onPlayerSpawned(cb: (player: Player) => void): void;
 /** Register a callback for when a player disconnects. */
-declare function onPlayerDisconnect(cb: (player: PlayerEventContext) => void): void;
-/**
- * Get the database bridge for direct table and reducer access.
- * Advanced — most modules should use the event bus and DI instead.
- */
+declare function onPlayerDisconnect(cb: (player: Player) => void): void;
+/** Get the database bridge for direct table and reducer access. */
 declare function getBridge(): any;
-/** Subscribe to database tables. Call inside onReady(). */
+/** Subscribe to database tables. */
 declare function subscribe(queries: string[]): Promise<void>;
-/** Sync configuration for a table. */
-interface SyncConfig {
-    /** Who receives updates for this table. */
-    to: "owner" | "all";
-    /** Column name for owner filtering (required when to: 'owner'). */
-    scope?: string;
-    /** Primary key column for row identity (defaults to 'id'). */
-    key?: string;
-}
-/** Context passed to action handlers. */
-interface ActionContext {
-    /** FiveM server-side player ID. */
-    source: number;
-    /** Player's citizen ID (license identifier). */
-    citizenId: string;
-    /** Player's display name. */
-    name: string;
-    /** Discord identifier (e.g. "discord:123456789"), if linked. */
-    discordId?: string;
-    /** Steam identifier (e.g. "steam:110000..."), if linked. */
-    steamId?: string;
-    /** Database table accessors (read-only). */
-    db: any;
-    /** Database reducer proxy (for mutations). */
-    reducers: any;
-}
-/** Action handler function. */
-type ActionHandler = (ctx: ActionContext, payload: any) => Promise<void> | void;
-/**
- * Register a table for automatic sync to clients.
- *
- * The sync engine subscribes to SpacetimeDB table changes and routes
- * updates to the correct players based on the config. Call inside onReady().
- *
- * @example
- * registerSync('inventory', { to: 'owner', scope: 'ownerId', key: 'id' });
- * registerSync('itemDefinitions', { to: 'all', key: 'name' });
- */
-declare function registerSync(table: string, config: SyncConfig): void;
-/**
- * Register an action handler that clients can invoke via useAction().
- *
- * Actions are the only entry point for client-initiated mutations.
- * The sync engine handles security, error routing, and state updates.
- *
- * @example
- * registerAction('inventory:moveItem', async (ctx, { itemId, toSlot }) => {
- *   await ctx.reducers.moveItem(ctx.citizenId, itemId, toSlot);
- * });
- */
-declare function registerAction(name: string, handler: ActionHandler): void;
-/**
- * Typed error for action handlers. Thrown errors with a `code` property
- * are sent to the client as structured error messages.
- *
- * @example
- * throw new WarpError('ITEM_NOT_FOUND', 'That item no longer exists');
- */
-declare class WarpError extends Error {
-    code: string;
-    constructor(code: string, message?: string);
-}
 
-export { type ActionContext, type ActionHandler, type ColumnDef, type ColumnType, type EntityStore, type PlayerEntity, type PlayerEventContext, type PlayerRow, type PlayerState, type ServerEventBus, type SyncConfig, type TableDef, WarpError, type WarpSchema, getBridge, getEntities, getEntity, getEvents, getPlayer, getPlayers, isReady, onPlayerConnect, onPlayerDisconnect, onPlayerSpawned, onReady, provide, registerAction, registerSync, spawnPlayer, subscribe, use };
+export { type AccessMode, type ActionError, type ColumnDef, type ColumnType, type CommandOptions, type CommandParam, type EntityStore, type Player, type PlayerEntity, type PlayerRow, type PlayerState, type ServerEventBus, type Table, type TableDef, type WarpSchema, action, command, error, fn, getBridge, getEntities, getEntity, getEvents, getPlayer, getPlayers, isReady, onPlayerConnect, onPlayerDisconnect, onPlayerSpawned, onReady, provide, spawnPlayer, subscribe, table, use };

package/dist/index.js

@@ -20,7 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  WarpError: () => WarpError,
+  action: () => action,
+  command: () => command,
+  error: () => error,
+  fn: () => fn,
   getBridge: () => getBridge,
   getEntities: () => getEntities,
   getEntity: () => getEntity,
@@ -33,16 +36,34 @@ __export(index_exports, {
   onPlayerSpawned: () => onPlayerSpawned,
   onReady: () => onReady,
   provide: () => provide,
-  registerAction: () => registerAction,
-  registerSync: () => registerSync,
   spawnPlayer: () => spawnPlayer,
   subscribe: () => subscribe,
+  table: () => table,
   use: () => use
 });
 module.exports = __toCommonJS(index_exports);
 function warp() {
   return globalThis.exports["warp"];
 }
+function action(name, handler) {
+  warp().action(name, handler);
+}
+function fn(name, handler) {
+  warp().fn(name, handler);
+}
+function command(name, handlerOrOptions, handler) {
+  if (typeof handlerOrOptions === "function") {
+    warp().command(name, {}, handlerOrOptions);
+  } else {
+    warp().command(name, handlerOrOptions, handler);
+  }
+}
+function error(code, message) {
+  return warp().error(code, message);
+}
+function table(name) {
+  return warp().table(name);
+}
 function onReady(cb) {
   warp().onReady(cb);
 }
@@ -88,22 +109,12 @@ function getBridge() {
 function subscribe(queries) {
   return warp().subscribe(queries);
 }
-function registerSync(table, config) {
-  warp().registerSync(table, config);
-}
-function registerAction(name, handler) {
-  warp().registerAction(name, handler);
-}
-var WarpError = class extends Error {
-  constructor(code, message) {
-    super(message ?? code);
-    this.code = code;
-    this.name = "WarpError";
-  }
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  WarpError,
+  action,
+  command,
+  error,
+  fn,
   getBridge,
   getEntities,
   getEntity,
@@ -116,9 +127,8 @@ var WarpError = class extends Error {
   onPlayerSpawned,
   onReady,
   provide,
-  registerAction,
-  registerSync,
   spawnPlayer,
   subscribe,
+  table,
   use
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpfx/server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Warp Framework SDK for server-side FiveM module development",
   "keywords": [
     "fivem",