@warpfx/client 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,181 +1,115 @@
 /**
- * @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, registerKeybind, sendNUI } 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) => { ... });
- *
- *     registerKeybind('open_shop', {
- *       description: 'Open Shop',
- *       key: 'E',
- *       onPress: () => showNUI('shop'),
- *     });
- *   });
+ *   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;
 }
+/** Reactive handle to synced state from the server. */
+interface SyncRef<T = any> {
+    /** Current value of the synced state. */
+    readonly value: T;
+    /** React to state changes. Returns an unsubscribe function. */
+    watch(handler: (newState: T, oldState: T) => void): () => void;
+}
+/** Action error received from the server. */
+interface ActionError {
+    action: string;
+    code: string;
+    message: string;
+}
 /** 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.
+ * Dispatch an action to the server. Fire-and-forget — state syncs back
+ * automatically via reactive stores.
+ *
+ * @example
+ * action('deposit', { amount: 100 });
+ * action('transfer', { targetId: 'xyz', amount: 50 });
  */
-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> {
-    /** 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;
-}
-/** Action error received from the server. */
-interface ActionError {
-    action: string;
-    code: string;
-    message: string;
-}
+declare function action(name: string, payload?: any): void;
 /**
- * Subscribe to synced state from the server.
- *
- * Returns a handle with a `.value` getter and `.onChange()` method.
- * State updates automatically when the server pushes changes.
+ * 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.
- */
-declare function getSyncState<T = any>(key: string): T | undefined;
-/**
- * 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' });
+ * Register a callback to run when Warp client is ready.
+ * If already ready, the callback fires immediately.
  */
-declare function callServer<T = any>(name: string, payload?: any, timeout?: number): Promise<T>;
+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 focus.
- * Optionally specify a panel name and cursor control.
  *
  * @example
- * showNUI('inventory');                     // panel + keyboard + cursor
- * showNUI('chat', { cursor: false });       // panel + keyboard only
+ * showNUI('inventory');
+ * showNUI('chat', { cursor: false });
  */
 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
- */
+/** Set NUI focus directly without visibility events. */
 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' }
- */
+/** 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).
- *
- * 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);
- * });
- */
+/** 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.
- * Players can rebind the key in their FiveM settings.
  *
  * @example
  * registerKeybind('open_inventory', {
@@ -183,14 +117,7 @@ declare function onNUI<T = any>(name: string, handler: (data: T) => any): void;
  *   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 KeybindOptions, type ShowNUIOptions, type SyncHandle, callServer, getEvents, getSyncState, hideNUI, isReady, onNUI, onReady, registerKeybind, sendNUI, setNUIFocus, 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,25 +20,36 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  callServer: () => callServer,
+  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);
 }
@@ -48,21 +59,6 @@ function isReady() {
 function getEvents() {
   return warp().getEvents();
 }
-function useSync(key, defaultValue) {
-  return warp().useSync(key, defaultValue);
-}
-function useAction(name, opts) {
-  return warp().useAction(name, opts);
-}
-function useErrorHandler(handler) {
-  return warp().useErrorHandler(handler);
-}
-function getSyncState(key) {
-  return warp().getSyncState(key);
-}
-function callServer(name, payload, timeout) {
-  return warp().callServer(name, payload, timeout);
-}
 function showNUI(panel, opts) {
   warp().showNUI(panel, opts);
 }
@@ -83,18 +79,17 @@ function registerKeybind(name, options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  callServer,
+  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.1",
+  "version": "0.3.0",
   "description": "Warp Framework SDK for client-side FiveM module development",
   "keywords": [
     "client",