@warpfx/client 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,48 +1,32 @@
 /**
- * @warp/client — Typed SDK for Warp client-side module development.
+ * @warpfx/client — Client-side SDK for Warp module development.
  *
- * Provides type-safe access to the Warp client API. Under the hood,
- * all calls go through FiveM's resource exports to the 'warp' resource.
+ * Clean, minimal API for building FiveM client features with Warp.
+ * All calls delegate to the Warp core via FiveM resource exports.
  *
  * Usage:
- *   import { onReady, getEvents } from '@warp/client';
+ *   import { accounts } from './db'; // auto-generated reactive store
+ *   import { action, call } from '@warpfx/client';
  *
- *   onReady(() => {
- *     const events = getEvents();
- *     events.onServer('economy:balance', (data) => { ... });
- *     events.emitServer('economy:request-balance', {});
- *   });
+ *   accounts.watch((data) => console.log('Balance:', data[0].balance));
+ *   action('deposit', { amount: 100 });
+ *   const { balance } = await call('getBalance', { targetId: 'xyz' });
  */
 /** Typed event bus for client-side and network communication. */
 interface ClientEventBus<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 the server. */
     emitServer<K extends string & keyof TMap>(event: K, data: TMap[K]): void;
-    /** Listen for events from the server. Returns an unsubscribe function. */
     onServer<K extends string & keyof TMap>(event: K, handler: (data: TMap[K]) => void): () => void;
-    /** Unsubscribe from a server event. */
     offServer<K extends string & keyof TMap>(event: K, handler: (data: TMap[K]) => void): void;
 }
-/**
- * Register a callback to run when Warp client is ready.
- * If already ready, the callback fires immediately.
- */
-declare function onReady(cb: () => void): void;
-/** Check if Warp client has finished initializing. */
-declare function isReady(): boolean;
-/** Get the shared client event bus instance. */
-declare function getEvents<TMap extends Record<string, any> = Record<string, any>>(): ClientEventBus<TMap>;
-/** Reactive handle to synced state. */
-interface SyncHandle<T = any> {
+/** Reactive handle to synced state from the server. */
+interface SyncRef<T = any> {
     /** Current value of the synced state. */
     readonly value: T;
-    /** Register a callback for when state changes. Returns unsubscribe function. */
-    onChange(handler: (newState: T, oldState: T) => void): () => void;
+    /** React to state changes. Returns an unsubscribe function. */
+    watch(handler: (newState: T, oldState: T) => void): () => void;
 }
 /** Action error received from the server. */
 interface ActionError {
@@ -50,52 +34,90 @@ interface ActionError {
     code: string;
     message: string;
 }
+/** Key binding configuration. */
+interface KeybindOptions {
+    description: string;
+    key: string;
+    device?: "keyboard" | "mouse_button" | "pad_analogbutton";
+    onPress: () => void;
+    onRelease?: () => void;
+}
+/** Options for showNUI(). */
+interface ShowNUIOptions {
+    cursor?: boolean;
+}
 /**
- * Subscribe to synced state from the server.
+ * Dispatch an action to the server. Fire-and-forget — state syncs back
+ * automatically via reactive stores.
  *
- * Returns a handle with a `.value` getter and `.onChange()` method.
- * State updates automatically when the server pushes changes.
+ * @example
+ * action('deposit', { amount: 100 });
+ * action('transfer', { targetId: 'xyz', amount: 50 });
+ */
+declare function action(name: string, payload?: any): void;
+/**
+ * Call a server function and await the result.
  *
  * @example
- * const inventory = useSync<InventoryItem[]>('inventory', []);
- * console.log(inventory.value); // current items
- * inventory.onChange((items) => console.log('Updated:', items.length));
+ * const { balance } = await call<{ balance: number }>('getBalance');
+ * const price = await call('getPrice', { itemId: 'bread' });
  */
-declare function useSync<T = any>(key: string, defaultValue?: T): SyncHandle<T>;
+declare function call<T = any>(name: string, payload?: any, timeout?: number): Promise<T>;
 /**
- * Create an action dispatcher to call server-side action handlers.
+ * Create a reactive sync reference for a state key.
  *
- * Returns a function that sends the action to the server.
- * State updates flow back automatically via the sync engine.
+ * The returned ref updates automatically when the server pushes changes.
+ * Use this in auto-generated `db.ts` files or for manual state subscriptions.
  *
  * @example
- * const moveItem = useAction<{ itemId: string; toSlot: number }>('inventory:moveItem');
- * moveItem({ itemId: 'abc', toSlot: 5 });
+ * const accounts = sync<Account[]>('accounts', []);
+ * accounts.watch((data) => console.log('Updated:', data));
+ * console.log(accounts.value);
  */
-declare function useAction<P = any>(name: string, opts?: {
-    onError?: (error: ActionError) => void;
-}): (payload: P) => void;
+declare function sync<T = any>(key: string, defaultValue?: T): SyncRef<T>;
 /**
  * Register a global error handler for all action errors.
  * Returns an unsubscribe function.
  *
  * @example
- * useErrorHandler((error) => {
- *   console.log(`Action ${error.action} failed: ${error.message}`);
- * });
+ * onError((err) => console.log(`${err.action} failed: ${err.message}`));
  */
-declare function useErrorHandler(handler: (error: ActionError) => void): () => void;
+declare function onError(handler: (error: ActionError) => void): () => void;
 /**
- * Get the current synced state for a key.
- * Unlike useSync(), this is a one-shot read with no change tracking.
+ * Register a callback to run when Warp client is ready.
+ * If already ready, the callback fires immediately.
  */
-declare function getSyncState<T = any>(key: string): T | undefined;
+declare function onReady(cb: () => void): void;
+/** Check if Warp client has finished initializing. */
+declare function isReady(): boolean;
+/** Get the shared client event bus instance. */
+declare function getEvents<TMap extends Record<string, any> = Record<string, any>>(): ClientEventBus<TMap>;
 /**
- * Show the NUI overlay with mouse/keyboard focus.
- * Optionally specify a panel name to show a specific module UI.
+ * Show the NUI overlay with focus.
+ *
+ * @example
+ * showNUI('inventory');
+ * showNUI('chat', { cursor: false });
  */
-declare function showNUI(panel?: string): void;
-/** Hide the NUI overlay and release mouse/keyboard focus. */
+declare function showNUI(panel?: string, opts?: ShowNUIOptions): void;
+/** Hide the NUI overlay and release all focus. */
 declare function hideNUI(): void;
+/** Set NUI focus directly without visibility events. */
+declare function setNUIFocus(hasFocus: boolean, hasCursor?: boolean): void;
+/** Send a message to the NUI (browser) layer. */
+declare function sendNUI(type: string, payload?: Record<string, any>): void;
+/** Register a handler for NUI callbacks (browser → client). */
+declare function onNUI<T = any>(name: string, handler: (data: T) => any): void;
+/**
+ * Register a key binding with FiveM's key mapping system.
+ *
+ * @example
+ * registerKeybind('open_inventory', {
+ *   description: 'Open Inventory',
+ *   key: 'I',
+ *   onPress: () => showNUI('inventory'),
+ * });
+ */
+declare function registerKeybind(name: string, options: KeybindOptions): void;
 
-export { type ActionError, type ClientEventBus, type SyncHandle, getEvents, getSyncState, hideNUI, isReady, onReady, showNUI, useAction, useErrorHandler, useSync };
+export { type ActionError, type ClientEventBus, type KeybindOptions, type ShowNUIOptions, type SyncRef, action, call, getEvents, hideNUI, isReady, onError, onNUI, onReady, registerKeybind, sendNUI, setNUIFocus, showNUI, sync };

package/dist/index.js

@@ -20,20 +20,36 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  action: () => action,
+  call: () => call,
   getEvents: () => getEvents,
-  getSyncState: () => getSyncState,
   hideNUI: () => hideNUI,
   isReady: () => isReady,
+  onError: () => onError,
+  onNUI: () => onNUI,
   onReady: () => onReady,
+  registerKeybind: () => registerKeybind,
+  sendNUI: () => sendNUI,
+  setNUIFocus: () => setNUIFocus,
   showNUI: () => showNUI,
-  useAction: () => useAction,
-  useErrorHandler: () => useErrorHandler,
-  useSync: () => useSync
+  sync: () => sync
 });
 module.exports = __toCommonJS(index_exports);
 function warp() {
   return globalThis.exports["warp"];
 }
+function action(name, payload) {
+  warp().action(name, payload);
+}
+function call(name, payload, timeout) {
+  return warp().call(name, payload, timeout);
+}
+function sync(key, defaultValue) {
+  return warp().sync(key, defaultValue);
+}
+function onError(handler) {
+  return warp().onError(handler);
+}
 function onReady(cb) {
   warp().onReady(cb);
 }
@@ -43,33 +59,37 @@ function isReady() {
 function getEvents() {
   return warp().getEvents();
 }
-function useSync(key, defaultValue) {
-  return warp().useSync(key, defaultValue);
+function showNUI(panel, opts) {
+  warp().showNUI(panel, opts);
 }
-function useAction(name, opts) {
-  return warp().useAction(name, opts);
+function hideNUI() {
+  warp().hideNUI();
 }
-function useErrorHandler(handler) {
-  return warp().useErrorHandler(handler);
+function setNUIFocus(hasFocus, hasCursor) {
+  warp().setNUIFocus(hasFocus, hasCursor);
 }
-function getSyncState(key) {
-  return warp().getSyncState(key);
+function sendNUI(type, payload) {
+  warp().sendNUI(type, payload);
 }
-function showNUI(panel) {
-  warp().showNUI(panel);
+function onNUI(name, handler) {
+  warp().onNUI(name, handler);
 }
-function hideNUI() {
-  warp().hideNUI();
+function registerKeybind(name, options) {
+  warp().registerKeybind(name, options);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  action,
+  call,
   getEvents,
-  getSyncState,
   hideNUI,
   isReady,
+  onError,
+  onNUI,
   onReady,
+  registerKeybind,
+  sendNUI,
+  setNUIFocus,
   showNUI,
-  useAction,
-  useErrorHandler,
-  useSync
+  sync
 });

package/package.json

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