@fivem-nui/core 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+# @fivem-nui/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Strongly typed TypeScript bridge between FiveM NUI panel and C#/.NET client script.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/rian-be/FiveM.Nui/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.12.0-brightgreen.svg)](#requirements)
+[![TypeScript](https://img.shields.io/badge/TypeScript-7.x-blue.svg)](#requirements)
+[![Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](#requirements)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
+
+`@fivem-nui/core` is the TypeScript half of [FiveM.Nui](../../../README.md): typed request/response, C#-callable callbacks, events, and window notifications, with no framework and no runtime dependencies. Use it with Svelte, React, Vue, or plain TypeScript.
+
+## Highlights
+
+- **Typed request/response**: correlation IDs, deadlines, and cancellation.
+- **Callbacks**: handlers C# can invoke, with clean unregistration.
+- **Events**: one-way C# → UI subscriptions, isolated per handler.
+- **Window notifications**: `open` / `close` / `focus` / `unfocus`.
+- **Error codes, not text**: branch on `NuiRequestError.code`.
+- **Diagnostics**: message counters for a dev panel.
+- **Zero runtime dependencies**, no framework lock-in.
+
+## Requirements
+
+- Node.js `>= 22.12.0`
+- TypeScript `7.x` (the package ships ESM output and `.d.ts` declarations)
+
+## Installation
+
+```bash
+npm install @fivem-nui/core
+```
+
+Or add it to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@fivem-nui/core": "^1.0.0"
+  }
+}
+```
+
+## Entry points
+
+One package, three import paths:
+
+| Import path                   | Use for                          |
+|-------------------------------|----------------------------------|
+| `@fivem-nui/core`             | Production UI                    |
+| `@fivem-nui/core/testing`     | Tests, no FiveM needed           |
+| `@fivem-nui/core/diagnostics` | Dev panels, counters             |
+
+```ts
+import { makeClient } from '@fivem-nui/core/testing';
+import type { NuiDiagnostics } from '@fivem-nui/core/diagnostics';
+```
+
+See [Package Entry Points](../../../docs/api/typescript.md#11-package-entry-points) for the full map, and
+[Testing Guide](../../../docs/developers/testing.md) for testing recipes.
+
+## Quick start
+
+```ts
+import { nui } from '@fivem-nui/core';
+
+// Once, on page start. Idempotent.
+nui.listen();
+
+// C# -> UI: handle a request and answer it.
+nui.callback<void, GetPlayerDataResponse>('player:get', async () => ({
+  success: true,
+  value: { name: 'NuiPlayer', health: 100 },
+}));
+
+// C# -> UI: react to an event. Keep the unsubscribe for teardown.
+const unsubscribe = nui.on<InventoryUpdated>('inventory:update', render);
+
+// UI -> C#: fire and forget.
+nui.notify('demo:action', { action: 'send' });
+
+// UI -> C#: call a callback registered in C# and await the response.
+const result = await nui.request<UseItemRequest, UseItemResponse>('inventory:use', { itemId });
+```
+
+`GetPlayerDataResponse`, `InventoryUpdated`, `UseItemRequest`, and `UseItemResponse` are application defined types. The C# side must expose the matching callbacks and handlers.
+
+## Generated contracts (optional)
+
+The event name strings above are unchecked: a typo compiles and fails at runtime. To make every call statically checked against the C# contract, generate a TypeScript map with the [`FiveM.Nui.Contracts`](../../../tools/FiveM.Nui.Contracts) tool from C# types annotated with `[NuiContract]` and `[NuiEvent]`:
+
+```bash
+fivem-nui-contracts -a path/to/MyProject.dll -o src/contracts.ts
+```
+
+The generated file ends with a module augmentation:
+
+```ts
+declare module '@fivem-nui/core' {
+  interface NuiEventMap {
+    'inventory:use': { request: UseItemRequest; response: UseItemResponse };
+    'player:healthChanged': { payload: HealthChanged };
+  }
+}
+```
+
+Import it once for its side effect so the map is part of the program:
+
+```ts
+import './contracts';
+import { nui } from '@fivem-nui/core';
+
+// request/response are inferred from the contract.
+const response = await nui.request('inventory:use', { itemId });
+response.ok; // typed as boolean
+
+// A name that is not in the map is a compile error.
+await nui.request('inventory:usee', { itemId }); // Error: not assignable to 'never'
+```
+
+While no map is generated `NuiEventMap` stays empty and the client keeps its permissive, string-based signatures, so this is opt-in. When the map is augmented, `request`, `send`, `sendAndWait`, `callback`, `on`, and `once` check the name, the request payload, and the response type; explicit type arguments remain available as an escape hatch. Use `--core-module <module>` if the package is imported under a different specifier.
+
+## API
+
+| Method                                           | Direction | Purpose                                                                                                               |
+|--------------------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------|
+| `listen(target?)`                                | -         | Start receiving messages from C#. Idempotent; returns a function that stops listening.                                |
+| `on<T>(event, handler)`                          | C# → UI   | Subscribe to an event. Returns `unsubscribe`.                                                                         |
+| `once<T>(event, handler)`                        | C# → UI   | Subscribe to the next matching event only. Returns `unsubscribe`.                                                     |
+| `off(event, handler?)`                           | C# → UI   | Remove one handler, or all handlers for the event.                                                                    |
+| `callback<TReq, TRes>(event, handler)`           | C# → UI   | Handle C# request the handler returns a `NuiResult`. A thrown handler is answered with `CALLBACK_ERROR`.              |
+| `unregisterCallback(event)`                      | C# → UI   | Remove handler, so C# gets `UNKNOWN_CALLBACK` again. Returns `boolean`.                                               |
+| `request<TReq, TRes>(event, payload?, timeout?, signal?)` | UI → C#   | Send request and await the response; rejects with `TIMEOUT` after `timeout` (default `30000` ms), or `ABORTED` when `signal` aborts. |
+| `send(event, payload?)`                          | UI → C#   | Fire and forget the HTTP reply is not read.                                                                           |
+| `sendAndWait(event, payload?)`                   | UI → C#   | Resolve once the POST lands, reject on `POST_TIMEOUT`/`TRANSPORT`. Delivery confirmation only not C# acknowledgement. |
+| `notify(callback, payload?)`                     | UI → C#   | POST to a named resource callback; fire and forget.                                                                   |
+| `notifyAndWait(callback, payload?)`              | UI → C#   | Same, but resolve once the resource answers.                                                                          |
+| `onWindow(handler)`                              | C# → UI   | Receive `(action, window)` for `open` / `close` / `focus` / `unfocus`.                                                |
+| `getDiagnostics()`                               | -         | Counter snapshot (`sent`, `received`, `pending`, `listeners`, …).                                                     |
+| `dispose()`                                      | -         | Drop listeners, callbacks and pending requests; reject the latter with `DISPOSED`.                                    |
+
+## Errors
+
+Failed operations reject with a `NuiRequestError`. Read `error.code`; `error.message` is for logs and may change. `isNuiRequestError(error)` narrows it inside `catch`.
+
+| Code               | Meaning                                                                           |
+|--------------------|-----------------------------------------------------------------------------------|
+| `UNKNOWN_CALLBACK` | No handler is registered for the event on the side that had to answer.            |
+| `CALLBACK_ERROR`   | A callback handler threw.                                                         |
+| `TIMEOUT`          | `request()` exceeded its deadline.                                                |
+| `ABORTED`          | The caller aborted the request through its `AbortSignal`.                          |
+| `POST_TIMEOUT`     | A single POST was aborted after `postTimeoutMs`.                                  |
+| `TRANSPORT`        | The POST failed for another reason (for example, the resource stopped answering). |
+| `DISPOSED`         | `dispose()` was called while the operation was attempted or pending.              |
+| `UNKNOWN_ERROR`    | A failure was reported without a code.                                            |
+
+```ts
+import { nui, NuiErrorCodes, isNuiRequestError } from '@fivem-nui/core';
+
+try {
+  await nui.request('inventory:use', { itemId });
+} catch (error) {
+  if (!isNuiRequestError(error)) throw error;
+
+  if (error.code === NuiErrorCodes.Timeout) {
+    showToast('The server did not respond');
+  } else {
+    showToast('The request could not be completed');
+  }
+}
+```
+
+A `TIMEOUT` rejects the promise but does **not** cancel or roll back the operation: the POST may already have reached C#, and late response is dropped. If the operation has side effects, handle retries and duplicates in your application.
+
+Pass an `AbortSignal` as the fourth argument to `request()` to stop waiting for one request without disposing the client. It rejects with `ABORTED`, and a response that arrives later is dropped.
+
+## Configuration
+
+```ts
+new NuiClient({
+  resource: 'panel_orders',   // default: GetParentResourceName(), else 'unknown_resource'
+  callback: 'nui',            // resource callback endpoint (default: 'nui')
+  window: 'panel_orders',     // filter for onWindow (default: every window)
+  postTimeoutMs: 10_000,      // per POST abort deadline (default: 10000)
+  requestTimeoutMs: 30_000,   // default request() deadline (default: 30000)
+  logger: nullNuiLogger,      // consoleNuiLogger (default) or your own NuiLogger
+  fetch: myFetch,             // injection seam; default: globalThis.fetch
+});
+```
+
+The default export `nui` is bound to the ambient resource. Create an instance when you need different options or your own lifecycle.
+
+## Design notes
+
+- **`notify` never awaits its reply.** The browser reads nothing from the HTTP response, so awaiting would only stall the page for the whole POST timeout. Use `notifyAndWait` when delivery matters.
+- **`notifyAndWait` exists for the `ready` handshake.** A silent failure there leaves the panel dead for the rest of the session.
+- **`request` is for C# callbacks.** If the UI owns the handler for an event, ask C# with `request`, not `notify`: `notify` discards the reply.
+- **Dispose on teardown.** Call `dispose()` when the page unmounts (remount, HMR) so a stale client cannot keep answering C# on behalf of dead page. After `dispose()` the client is inert; create a new instance to continue.
+- **Handlers are isolated.** A throwing event handler is logged and skipped; its siblings still receive the event. A throwing `callback` handler is answered with `CALLBACK_ERROR` rather than leaving C# waiting.
+
+## Architecture
+
+`NuiClient` is a thin facade over four collaborators, mirroring the C# side of the bridge:
+
+| File                    | Class                                    | Responsibility                                                               |
+|-------------------------|------------------------------------------|------------------------------------------------------------------------------|
+| `MessageTransport.ts`   | `MessageTransport`                       | POSTs to `https://<resource>/<callback>` with an `AbortController` deadline. |
+| `RequestCoordinator.ts` | `RequestCoordinator`                     | In flight requests, correlation IDs, deadlines, settlement.                  |
+| `CallbackRegistry.ts`   | `CallbackRegistry`                       | C# request handler lookup.                                                   |
+| `EventBus.ts`           | `EventBus`                               | C# → UI subscription and dispatch, with error isolation.                     |
+| `NuiClientOptions.ts`   | `NuiClientOptions`, `readResourceName()` | Configuration and resource-name detection.                                   |
+| `NuiClient.ts`          | `NuiClient`                              | Orchestration: message dispatch, counters, lifecycle.                        |
+
+## Development
+
+```bash
+npm install
+npm run build      # tsc -> dist/
+npm run check      # tsc --noEmit, plus the type-level contract tests
+npm test           # vitest run
+npm run coverage   # vitest run --coverage
+npm run watch      # rebuild on change
+```
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/rian-be/FiveM.Nui](https://github.com/rian-be/FiveM.Nui). Keep changes focused, add or update tests for new behavior, and update the docs when a public API or its behavior changes.
+
+## License
+
+[MIT](../../../LICENSE) © 2026 Rian.be

package/dist/CallbackRegistry.d.ts

@@ -0,0 +1,30 @@
+import type { NuiMessage } from './types';
+/** Internal storage shape for a registered callback handler. */
+export type CallbackHandler = (request: unknown) => Promise<NuiMessage>;
+/**
+ * Registry for C# request handlers.
+ *
+ * Stores handlers keyed by event name, providing typ safe registration
+ * and O(1) lookup by name. A handler that throws is caught by the caller
+ * (via {@link NuiClient.handleRequest}) and reported back to C# as
+ * `CALLBACK_ERROR` instead of being left unanswered.
+ *
+ * Mirrors C# `NuiCallbackRegistry`.
+ */
+export declare class CallbackRegistry {
+    private callbacks;
+    /** Registers (or replaces) a handler for `eventName`. */
+    register(eventName: string, handler: CallbackHandler): void;
+    /**
+     * Removes the handler for `eventName`.
+     * @returns `true` if a handler was removed.
+     */
+    unregister(eventName: string): boolean;
+    /** Retrieves the handler for `eventName`, or `undefined` if none. */
+    get(eventName: string): CallbackHandler | undefined;
+    /** Number of registered callbacks. */
+    get count(): number;
+    /** Removes every registered callback. Called during `dispose()`. */
+    clear(): void;
+}
+//# sourceMappingURL=CallbackRegistry.d.ts.map

package/dist/CallbackRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CallbackRegistry.d.ts","sourceRoot":"","sources":["../src/CallbackRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAsC;IAEvD,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAE1D;IAED;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAErC;IAED,qEAAqE;IACrE,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAElD;IAED,sCAAsC;IACtC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,oEAAoE;IACpE,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/CallbackRegistry.js

@@ -0,0 +1,37 @@
+/**
+ * Registry for C# request handlers.
+ *
+ * Stores handlers keyed by event name, providing typ safe registration
+ * and O(1) lookup by name. A handler that throws is caught by the caller
+ * (via {@link NuiClient.handleRequest}) and reported back to C# as
+ * `CALLBACK_ERROR` instead of being left unanswered.
+ *
+ * Mirrors C# `NuiCallbackRegistry`.
+ */
+export class CallbackRegistry {
+    callbacks = new Map();
+    /** Registers (or replaces) a handler for `eventName`. */
+    register(eventName, handler) {
+        this.callbacks.set(eventName, handler);
+    }
+    /**
+     * Removes the handler for `eventName`.
+     * @returns `true` if a handler was removed.
+     */
+    unregister(eventName) {
+        return this.callbacks.delete(eventName);
+    }
+    /** Retrieves the handler for `eventName`, or `undefined` if none. */
+    get(eventName) {
+        return this.callbacks.get(eventName);
+    }
+    /** Number of registered callbacks. */
+    get count() {
+        return this.callbacks.size;
+    }
+    /** Removes every registered callback. Called during `dispose()`. */
+    clear() {
+        this.callbacks.clear();
+    }
+}
+//# sourceMappingURL=CallbackRegistry.js.map

package/dist/CallbackRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CallbackRegistry.js","sourceRoot":"","sources":["../src/CallbackRegistry.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,MAAM,OAAO,gBAAgB;IACnB,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;IAEvD,yDAAyD;IACzD,QAAQ,CAAC,SAAiB,EAAE,OAAwB;QAClD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,qEAAqE;IACrE,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAED,sCAAsC;IACtC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED,oEAAoE;IACpE,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/EventBus.d.ts

@@ -0,0 +1,44 @@
+import type { NuiLogger } from './logger';
+/** Internal listener type: accepts any payload, callers cast as needed. */
+export type EventHandler = (data: unknown) => void;
+/**
+ * Type safe event subscription and dispatch.
+ *
+ * Maintains multiple listeners per event name, supports one-shot
+ * subscriptions (`once`), and isolates handler errors so a throwing
+ * listener cannot prevent its siblings from receiving the payload.
+ *
+ * Mirrors C# `EventManager`.
+ */
+export declare class EventBus {
+    private readonly listeners;
+    private readonly logger;
+    constructor(logger: NuiLogger);
+    /**
+     * Subscribes to `eventName`.
+     * @returns an unsubscribe function.
+     */
+    on<T>(eventName: string, handler: (data: T) => void): () => void;
+    /**
+     * Subscribes to the next occurrence of `eventName` only.
+     * @returns an unsubscribe function (also valid after the handler fired).
+     */
+    once<T>(eventName: string, handler: (data: T) => void): () => void;
+    /**
+     * Unsubscribes from `eventName`.
+     * If `handler` is omitted, removes every listener for that event.
+     */
+    off(eventName: string, handler?: EventHandler): void;
+    /**
+     * Dispatches `payload` to every listener of `eventName`.
+     *
+     * Copies the listener set first so a handler that unsubscribes itself
+     * (or removes a sibling) cannot skip the next listener.
+     */
+    emit(eventName: string, payload: unknown): void;
+    /** Total listeners across all events. */
+    get listenerCount(): number;
+    /** Removes every listener. Called during `dispose()`. */
+    clear(): void;
+}
+//# sourceMappingURL=EventBus.d.ts.map

package/dist/EventBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.d.ts","sourceRoot":"","sources":["../src/EventBus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;AAEnD;;;;;;;;GAQG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IAEnC,YAAY,MAAM,EAAE,SAAS,EAE5B;IAED;;;OAGG;IACH,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAkB/D;IAED;;;OAGG;IACH,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAOjE;IAED;;;OAGG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAgBnD;IAED;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAc9C;IAED,yCAAyC;IACzC,IAAI,aAAa,IAAI,MAAM,CAQ1B;IAED,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/EventBus.js

@@ -0,0 +1,98 @@
+/**
+ * Type safe event subscription and dispatch.
+ *
+ * Maintains multiple listeners per event name, supports one-shot
+ * subscriptions (`once`), and isolates handler errors so a throwing
+ * listener cannot prevent its siblings from receiving the payload.
+ *
+ * Mirrors C# `EventManager`.
+ */
+export class EventBus {
+    listeners = new Map();
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Subscribes to `eventName`.
+     * @returns an unsubscribe function.
+     */
+    on(eventName, handler) {
+        let set = this.listeners.get(eventName);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(eventName, set);
+        }
+        const listener = handler;
+        set.add(listener);
+        return () => {
+            set.delete(listener);
+            if (set.size === 0) {
+                this.listeners.delete(eventName);
+            }
+        };
+    }
+    /**
+     * Subscribes to the next occurrence of `eventName` only.
+     * @returns an unsubscribe function (also valid after the handler fired).
+     */
+    once(eventName, handler) {
+        const unsubscribe = this.on(eventName, data => {
+            unsubscribe();
+            handler(data);
+        });
+        return unsubscribe;
+    }
+    /**
+     * Unsubscribes from `eventName`.
+     * If `handler` is omitted, removes every listener for that event.
+     */
+    off(eventName, handler) {
+        const set = this.listeners.get(eventName);
+        if (!set) {
+            return;
+        }
+        if (handler) {
+            set.delete(handler);
+            if (set.size === 0) {
+                this.listeners.delete(eventName);
+            }
+        }
+        else {
+            this.listeners.delete(eventName);
+        }
+    }
+    /**
+     * Dispatches `payload` to every listener of `eventName`.
+     *
+     * Copies the listener set first so a handler that unsubscribes itself
+     * (or removes a sibling) cannot skip the next listener.
+     */
+    emit(eventName, payload) {
+        const set = this.listeners.get(eventName);
+        if (!set) {
+            return;
+        }
+        for (const listener of [...set]) {
+            try {
+                listener(payload);
+            }
+            catch (error) {
+                this.logger.error(`Error in event handler for: ${eventName}`, error);
+            }
+        }
+    }
+    /** Total listeners across all events. */
+    get listenerCount() {
+        let total = 0;
+        for (const set of this.listeners.values()) {
+            total += set.size;
+        }
+        return total;
+    }
+    /** Removes every listener. Called during `dispose()`. */
+    clear() {
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=EventBus.js.map

package/dist/EventBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.js","sourceRoot":"","sources":["../src/EventBus.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,MAAM,OAAO,QAAQ;IACF,SAAS,GAAG,IAAI,GAAG,EAA6B,CAAC;IACjD,MAAM,CAAY;IAEnC,YAAY,MAAiB;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,EAAE,CAAI,SAAiB,EAAE,OAA0B;QACjD,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAExC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACrC,CAAC;QAED,MAAM,QAAQ,GAAG,OAAuB,CAAC;QACzC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAElB,OAAO,GAAG,EAAE;YACV,GAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAEtB,IAAI,GAAI,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACpB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACnC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,IAAI,CAAI,SAAiB,EAAE,OAA0B;QACnD,MAAM,WAAW,GAAG,IAAI,CAAC,EAAE,CAAI,SAAS,EAAE,IAAI,CAAC,EAAE;YAC/C,WAAW,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;QAEH,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,SAAiB,EAAE,OAAsB;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAE1C,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QAED,IAAI,OAAO,EAAE,CAAC;YACZ,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAEpB,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACnB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,SAAiB,EAAE,OAAgB;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAE1C,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QAED,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;YAChC,IAAI,CAAC;gBACH,QAAQ,CAAC,OAAO,CAAC,CAAC;YACpB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,SAAS,EAAE,EAAE,KAAK,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;IACH,CAAC;IAED,yCAAyC;IACzC,IAAI,aAAa;QACf,IAAI,KAAK,GAAG,CAAC,CAAC;QAEd,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1C,KAAK,IAAI,GAAG,CAAC,IAAI,CAAC;QACpB,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yDAAyD;IACzD,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/MessageTransport.d.ts

@@ -0,0 +1,32 @@
+import type { NuiLogger } from './logger';
+export type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * HTTP transport for FiveM NUI.
+ *
+ * Posts envelopes to `https://<resource>/<callback>` using `fetch`.
+ * Each POST is bounded by an `AbortController` deadline so a resource
+ * that stops answering (restart, shutdown) does not hang the page forever.
+ *
+ * Mirrors C# `FiveMNuiTransport`.
+ */
+export declare class MessageTransport {
+    private readonly resource;
+    private readonly callbackName;
+    private readonly postTimeoutMs;
+    private readonly logger;
+    private readonly fetchImpl;
+    constructor(resource: string, callbackName: string, postTimeoutMs: number, logger: NuiLogger, fetchImpl: FetchImpl);
+    /** URL of the main resource callback. */
+    get mainCallbackUrl(): string;
+    /** Builds the URL for an arbitrary callback on the same resource. */
+    callbackUrl(callbackName: string): string;
+    /**
+     * Raw POST to `url` with the configured timeout deadline.
+     *
+     * @throws {NuiRequestError} with code `POST_TIMEOUT` when the resource
+     *   stops answering within `postTimeoutMs`.
+     * @throws {NuiRequestError} with code `TRANSPORT` for any other failure.
+     */
+    post(url: string, body: unknown): Promise<void>;
+}
+//# sourceMappingURL=MessageTransport.d.ts.map

package/dist/MessageTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageTransport.d.ts","sourceRoot":"","sources":["../src/MessageTransport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE5F;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC,YACE,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,SAAS,EAOrB;IAED,yCAAyC;IACzC,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,qEAAqE;IACrE,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAExC;IAED;;;;;;OAMG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCpD;CACF"}

package/dist/MessageTransport.js

@@ -0,0 +1,70 @@
+import { NuiErrorCodes, NuiRequestError } from './errors';
+/**
+ * HTTP transport for FiveM NUI.
+ *
+ * Posts envelopes to `https://<resource>/<callback>` using `fetch`.
+ * Each POST is bounded by an `AbortController` deadline so a resource
+ * that stops answering (restart, shutdown) does not hang the page forever.
+ *
+ * Mirrors C# `FiveMNuiTransport`.
+ */
+export class MessageTransport {
+    resource;
+    callbackName;
+    postTimeoutMs;
+    logger;
+    fetchImpl;
+    constructor(resource, callbackName, postTimeoutMs, logger, fetchImpl) {
+        this.resource = resource;
+        this.callbackName = callbackName;
+        this.postTimeoutMs = postTimeoutMs;
+        this.logger = logger;
+        this.fetchImpl = fetchImpl;
+    }
+    /** URL of the main resource callback. */
+    get mainCallbackUrl() {
+        return `https://${this.resource}/${encodeURIComponent(this.callbackName)}`;
+    }
+    /** Builds the URL for an arbitrary callback on the same resource. */
+    callbackUrl(callbackName) {
+        return `https://${this.resource}/${encodeURIComponent(callbackName)}`;
+    }
+    /**
+     * Raw POST to `url` with the configured timeout deadline.
+     *
+     * @throws {NuiRequestError} with code `POST_TIMEOUT` when the resource
+     *   stops answering within `postTimeoutMs`.
+     * @throws {NuiRequestError} with code `TRANSPORT` for any other failure.
+     */
+    async post(url, body) {
+        // Without an abort, a resource that stops answering leaves this promise
+        // pending forever and the caller's await never returns.
+        const controller = new AbortController();
+        const deadline = setTimeout(() => controller.abort(), this.postTimeoutMs);
+        try {
+            await this.fetchImpl(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json; charset=UTF-8' },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            // A timeout abort surfaces as an error whose `name` is 'AbortError'.
+            // In browsers that is a DOMException, but some fetch polyfills throw a
+            // plain Error, so match on the name instead of the constructor. Checking
+            // only `controller.signal.aborted` is unsafe: a race between the deadline
+            // firing and an unrelated network error would misclassify the network
+            // error as POST_TIMEOUT.
+            const isAbortError = error?.name === 'AbortError';
+            if (isAbortError) {
+                throw new NuiRequestError(NuiErrorCodes.PostTimeout, `POST ${url} timed out after ${this.postTimeoutMs}ms`);
+            }
+            throw new NuiRequestError(NuiErrorCodes.Transport, String(error));
+        }
+        finally {
+            clearTimeout(deadline);
+        }
+    }
+}
+//# sourceMappingURL=MessageTransport.js.map

package/dist/MessageTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageTransport.js","sourceRoot":"","sources":["../src/MessageTransport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAM1D;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IACV,QAAQ,CAAS;IACjB,YAAY,CAAS;IACrB,aAAa,CAAS;IACtB,MAAM,CAAY;IAClB,SAAS,CAAY;IAEtC,YACE,QAAgB,EAChB,YAAoB,EACpB,aAAqB,EACrB,MAAiB,EACjB,SAAoB;QAEpB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,yCAAyC;IACzC,IAAI,eAAe;QACjB,OAAO,WAAW,IAAI,CAAC,QAAQ,IAAI,kBAAkB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;IAC7E,CAAC;IAED,qEAAqE;IACrE,WAAW,CAAC,YAAoB;QAC9B,OAAO,WAAW,IAAI,CAAC,QAAQ,IAAI,kBAAkB,CAAC,YAAY,CAAC,EAAE,CAAC;IACxE,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,IAAa;QACnC,wEAAwE;QACxE,wDAAwD;QACxD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAE1E,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;gBACxB,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,iCAAiC,EAAE;gBAC9D,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qEAAqE;YACrE,uEAAuE;YACvE,yEAAyE;YACzE,0EAA0E;YAC1E,sEAAsE;YACtE,yBAAyB;YACzB,MAAM,YAAY,GAAI,KAAkC,EAAE,IAAI,KAAK,YAAY,CAAC;YAEhF,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,IAAI,eAAe,CACvB,aAAa,CAAC,WAAW,EACzB,QAAQ,GAAG,oBAAoB,IAAI,CAAC,aAAa,IAAI,CACtD,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,eAAe,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACpE,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;CACF"}