@warpfx/client 0.1.3 → 0.2.1

package/dist/index.d.ts

@@ -5,12 +5,17 @@
  * all calls go through FiveM's resource exports to the 'warp' resource.
  *
  * Usage:
- *   import { onReady, getEvents } from '@warp/client';
+ *   import { onReady, getEvents, registerKeybind, sendNUI } from '@warp/client';
  *
  *   onReady(() => {
  *     const events = getEvents();
  *     events.onServer('economy:balance', (data) => { ... });
- *     events.emitServer('economy:request-balance', {});
+ *
+ *     registerKeybind('open_shop', {
+ *       description: 'Open Shop',
+ *       key: 'E',
+ *       onPress: () => showNUI('shop'),
+ *     });
  *   });
  */
 /** Typed event bus for client-side and network communication. */
@@ -28,6 +33,24 @@ interface ClientEventBus<TMap extends Record<string, any> = Record<string, any>>
     /** Unsubscribe from a server event. */
     offServer<K extends string & keyof TMap>(event: K, handler: (data: TMap[K]) => void): void;
 }
+/** Key binding configuration. */
+interface KeybindOptions {
+    /** Description shown in FiveM key mapping settings. */
+    description: string;
+    /** Default key (e.g. 'T', 'E', 'F5'). */
+    key: string;
+    /** Input device (defaults to 'keyboard'). */
+    device?: "keyboard" | "mouse_button" | "pad_analogbutton";
+    /** Callback when the key is pressed. */
+    onPress: () => void;
+    /** Callback when the key is released (optional). */
+    onRelease?: () => void;
+}
+/** Options for showNUI(). */
+interface ShowNUIOptions {
+    /** Whether to show the mouse cursor. Defaults to true. */
+    cursor?: boolean;
+}
 /**
  * Register a callback to run when Warp client is ready.
  * If already ready, the callback fires immediately.
@@ -91,11 +114,83 @@ declare function useErrorHandler(handler: (error: ActionError) => void): () => v
  */
 declare function getSyncState<T = any>(key: string): T | undefined;
 /**
- * Show the NUI overlay with mouse/keyboard focus.
- * Optionally specify a panel name to show a specific module UI.
+ * Call a server function and await the result.
+ *
+ * Unlike actions (fire-and-forget), this returns a Promise that resolves
+ * with the server's return value. Use for request/response patterns.
+ *
+ * @param name     The registered function name.
+ * @param payload  Optional data to send to the server.
+ * @param timeout  Timeout in ms (default: 10000).
+ *
+ * @example
+ * const { balance } = await callServer<{ balance: number }>('economy:getBalance');
+ * const result = await callServer('shop:getPrice', { itemId: 'bread' });
  */
-declare function showNUI(panel?: string): void;
-/** Hide the NUI overlay and release mouse/keyboard focus. */
+declare function callServer<T = any>(name: string, payload?: any, timeout?: number): Promise<T>;
+/**
+ * Show the NUI overlay with focus.
+ * Optionally specify a panel name and cursor control.
+ *
+ * @example
+ * showNUI('inventory');                     // panel + keyboard + cursor
+ * showNUI('chat', { cursor: false });       // panel + keyboard only
+ */
+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 sending visibility events.
+ * Use this for custom focus control (e.g. keyboard-only overlays).
+ *
+ * @param hasFocus  Whether NUI should capture keyboard input.
+ * @param hasCursor Whether to show the mouse cursor. Defaults to match hasFocus.
+ *
+ * @example
+ * setNUIFocus(true, false);  // keyboard only, no cursor
+ * setNUIFocus(false);         // release all focus
+ */
+declare function setNUIFocus(hasFocus: boolean, hasCursor?: boolean): void;
+/**
+ * Send a message to the NUI (browser) layer.
+ * The payload fields are spread into the message alongside the type.
+ *
+ * @example
+ * sendNUI('inventory:open', { tab: 'weapons' });
+ * // NUI receives: { type: 'inventory:open', tab: 'weapons' }
+ */
+declare function sendNUI(type: string, payload?: Record<string, any>): void;
+/**
+ * Register a handler for NUI callbacks (browser → client).
+ *
+ * When the NUI calls `fetch('https://warp/{name}', ...)`, this handler
+ * fires. Return a value to send it back to the NUI, or return nothing
+ * for the default `{ ok: true }` response.
+ *
+ * @example
+ * onNUI('inventoryDrop', (data) => {
+ *   console.log('Dropped item:', data.itemId);
+ * });
+ */
+declare function onNUI<T = any>(name: string, handler: (data: T) => any): void;
+/**
+ * Register a key binding with FiveM's key mapping system.
+ * Players can rebind the key in their FiveM settings.
+ *
+ * @example
+ * registerKeybind('open_inventory', {
+ *   description: 'Open Inventory',
+ *   key: 'I',
+ *   onPress: () => showNUI('inventory'),
+ * });
+ *
+ * registerKeybind('sprint_boost', {
+ *   description: 'Sprint Boost',
+ *   key: 'LSHIFT',
+ *   onPress: () => startBoost(),
+ *   onRelease: () => stopBoost(),
+ * });
+ */
+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 SyncHandle, callServer, getEvents, getSyncState, hideNUI, isReady, onNUI, onReady, registerKeybind, sendNUI, setNUIFocus, showNUI, useAction, useErrorHandler, useSync };

package/dist/index.js

@@ -20,11 +20,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  callServer: () => callServer,
   getEvents: () => getEvents,
   getSyncState: () => getSyncState,
   hideNUI: () => hideNUI,
   isReady: () => isReady,
+  onNUI: () => onNUI,
   onReady: () => onReady,
+  registerKeybind: () => registerKeybind,
+  sendNUI: () => sendNUI,
+  setNUIFocus: () => setNUIFocus,
   showNUI: () => showNUI,
   useAction: () => useAction,
   useErrorHandler: () => useErrorHandler,
@@ -55,19 +60,39 @@ function useErrorHandler(handler) {
 function getSyncState(key) {
   return warp().getSyncState(key);
 }
-function showNUI(panel) {
-  warp().showNUI(panel);
+function callServer(name, payload, timeout) {
+  return warp().callServer(name, payload, timeout);
+}
+function showNUI(panel, opts) {
+  warp().showNUI(panel, opts);
 }
 function hideNUI() {
   warp().hideNUI();
 }
+function setNUIFocus(hasFocus, hasCursor) {
+  warp().setNUIFocus(hasFocus, hasCursor);
+}
+function sendNUI(type, payload) {
+  warp().sendNUI(type, payload);
+}
+function onNUI(name, handler) {
+  warp().onNUI(name, handler);
+}
+function registerKeybind(name, options) {
+  warp().registerKeybind(name, options);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  callServer,
   getEvents,
   getSyncState,
   hideNUI,
   isReady,
+  onNUI,
   onReady,
+  registerKeybind,
+  sendNUI,
+  setNUIFocus,
   showNUI,
   useAction,
   useErrorHandler,

package/package.json

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