@warpfx/server 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -1,3 +1,88 @@
+/**
+ * Schema types for Warp module developers.
+ *
+ * Modules define their database tables in a `warp.schema.json` file
+ * placed at the root of their FiveM resource. These types document
+ * the expected format.
+ *
+ * @example
+ * ```json
+ * {
+ *   "module": "superrobbery",
+ *   "tables": {
+ *     "robberies": {
+ *       "columns": {
+ *         "id": { "type": "string", "primaryKey": true },
+ *         "name": { "type": "string" },
+ *         "reward": { "type": "number", "default": 0 },
+ *         "lastRobbedBy": { "type": "string", "optional": true }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Column Types
+ *
+ * | Type       | Description                  | SpacetimeDB |
+ * |------------|------------------------------|-------------|
+ * | `string`   | UTF-8 text                   | String      |
+ * | `number`   | 64-bit float (JS number)     | F64         |
+ * | `boolean`  | true/false                   | Bool        |
+ *
+ * ## Column Options
+ *
+ * | Option       | Type      | Description                              |
+ * |--------------|-----------|------------------------------------------|
+ * | `primaryKey` | boolean   | Marks this column as the table's PK      |
+ * | `optional`   | boolean   | Column can be null/undefined              |
+ * | `default`    | any       | Default value for new rows               |
+ *
+ * ## Breaking Changes
+ *
+ * When you modify a schema in a way that could lose data (remove column,
+ * change type, etc.), Warp will block startup in production mode.
+ * To acknowledge breaking changes, add an `allowBreaking` array:
+ *
+ * ```json
+ * {
+ *   "module": "superrobbery",
+ *   "tables": { ... },
+ *   "allowBreaking": ["robberies.cooldown:removed"],
+ *   "version": 2
+ * }
+ * ```
+ */
+/** Supported column types. */
+type ColumnType = "string" | "number" | "boolean";
+/** Column definition in a warp.schema.json table. */
+interface ColumnDef {
+    /** The data type of this column. */
+    type: ColumnType;
+    /** If true, this column is the table's primary key. Exactly one required per table. */
+    primaryKey?: boolean;
+    /** If true, this column can be null/undefined. Cannot be combined with primaryKey. */
+    optional?: boolean;
+    /** Default value for this column when inserting a row without it. */
+    default?: unknown;
+}
+/** Table definition in a warp.schema.json. */
+interface TableDef {
+    /** Column definitions keyed by column name. */
+    columns: Record<string, ColumnDef>;
+}
+/** The full warp.schema.json format. */
+interface WarpSchema {
+    /** Unique module name (used as table prefix in the database). */
+    module: string;
+    /** Table definitions keyed by table name. */
+    tables: Record<string, TableDef>;
+    /** Schema version number (increment when making breaking changes). */
+    version?: number;
+    /** Acknowledged breaking changes (required in production for destructive schema changes). */
+    allowBreaking?: string[];
+}
+
 /**
  * @warp/server — Typed SDK for Warp server-side module development.
  *
@@ -29,6 +114,27 @@ interface PlayerRow {
     online: boolean;
     lastSeen: bigint;
 }
+/** Player lifecycle state. */
+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;
+    /** 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. */
@@ -81,8 +187,21 @@ 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.
+ */
+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.
+ */
+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 disconnects. */
 declare function onPlayerDisconnect(cb: (player: PlayerEventContext) => void): void;
 /**
@@ -151,4 +270,4 @@ declare class WarpError extends Error {
     constructor(code: string, message?: string);
 }
 
-export { type ActionContext, type ActionHandler, type EntityStore, type PlayerEventContext, type PlayerRow, type ServerEventBus, type SyncConfig, WarpError, getBridge, getEntities, getEvents, getPlayer, getPlayers, isReady, onPlayerConnect, onPlayerDisconnect, onReady, provide, registerAction, registerSync, subscribe, use };
+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 };

package/dist/index.js

@@ -23,16 +23,19 @@ __export(index_exports, {
   WarpError: () => WarpError,
   getBridge: () => getBridge,
   getEntities: () => getEntities,
+  getEntity: () => getEntity,
   getEvents: () => getEvents,
   getPlayer: () => getPlayer,
   getPlayers: () => getPlayers,
   isReady: () => isReady,
   onPlayerConnect: () => onPlayerConnect,
   onPlayerDisconnect: () => onPlayerDisconnect,
+  onPlayerSpawned: () => onPlayerSpawned,
   onReady: () => onReady,
   provide: () => provide,
   registerAction: () => registerAction,
   registerSync: () => registerSync,
+  spawnPlayer: () => spawnPlayer,
   subscribe: () => subscribe,
   use: () => use
 });
@@ -64,9 +67,18 @@ function getPlayer(citizenId) {
 function getPlayers() {
   return warp().getPlayers();
 }
+function getEntity(citizenId) {
+  return warp().getEntity(citizenId);
+}
+function spawnPlayer(citizenId) {
+  warp().spawnPlayer(citizenId);
+}
 function onPlayerConnect(cb) {
   warp().onPlayerConnect(cb);
 }
+function onPlayerSpawned(cb) {
+  warp().onPlayerSpawned(cb);
+}
 function onPlayerDisconnect(cb) {
   warp().onPlayerDisconnect(cb);
 }
@@ -94,16 +106,19 @@ var WarpError = class extends Error {
   WarpError,
   getBridge,
   getEntities,
+  getEntity,
   getEvents,
   getPlayer,
   getPlayers,
   isReady,
   onPlayerConnect,
   onPlayerDisconnect,
+  onPlayerSpawned,
   onReady,
   provide,
   registerAction,
   registerSync,
+  spawnPlayer,
   subscribe,
   use
 });

package/package.json

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