> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sure-developer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> All sure_lib modules, methods, availability, and return values

# API Reference

This page is a compact reference for sure\_lib version `2.2.1`.

## Module availability

| Module      | Client | Server |
| ----------- | ------ | ------ |
| `validator` | Yes    | Yes    |
| `listener`  | Yes    | Yes    |
| `track`     | Yes    | Yes    |
| `config`    | Yes    | Yes    |
| `player`    | Yes    | No     |
| `spawn`     | Yes    | No     |
| `lui`       | Yes    | No     |
| `cooldown`  | Yes    | Yes    |
| `db`        | No     | Yes    |
| `esx`       | No     | Yes    |

## Loader

<ParamField path="sure.getModule(name)" type="function" required>
  Loads a module by name from the current runtime side.
</ParamField>

<ResponseField name="module" type="table | nil">
  Returns a module table or `nil` when unavailable.
</ResponseField>

## Validator

<AccordionGroup>
  <Accordion title="Builders" defaultOpen>
    `object(fields)`, `array(itemRule)`, `string()`, `number()`, `integer()`, `boolean()`, and `callback()` create rules.
  </Accordion>

  <Accordion title="Rule methods">
    `required(message?)`, `message(message)`, `min(value)`, `max(value)`, `between(min, max)`, `oneOf(values)`, and `parse(data)`.
  </Accordion>

  <Accordion title="Return and errors">
    `parse(data)` returns `true` when data is valid. It raises `Validation Error: ...` when data is invalid.
  </Accordion>
</AccordionGroup>

## Listener

<ParamField path="listener:on(eventName, callback)" type="function">
  Registers a local event.
</ParamField>

<ParamField path="listener:onNet(eventName, callback)" type="function">
  Registers a network event.
</ParamField>

<ParamField path="listenerMeta:expect(...validators)" type="function">
  Validates positional event parameters before the callback runs.
</ParamField>

## Track

<ParamField path="track.state(stateName, initialValue)" type="function">
  Returns a getter and setter pair. The setter accepts a value or a functional update.
</ParamField>

<ParamField path="track.effect(callback, dependencies)" type="function">
  Runs `callback` whenever one of the dependency getters changes.
</ParamField>

## Player

<Tabs>
  <Tab title="Data">
    `data`, `inventory`, `accounts`, and `loadout` read current ESX player data. Inventory and account lists support lookup by name. Loadout supports normalized weapon lookup.
  </Tab>

  <Tab title="State">
    `loaded`, `ped`, `health`, `armor`, `coords`, `vehicle`, `serverId`, and `currentVehicleProperties` expose common client state.
  </Tab>

  <Tab title="Lifecycle">
    `waitUntilLoaded()` waits until `ESX.IsPlayerLoaded()` returns true.
  </Tab>
</Tabs>

## Config

<ParamField path="config:load(filePath, schema?)" type="function">
  Loads and caches a Lua config file. When `schema` is supplied, the cached or freshly loaded value is validated before it is returned.
</ParamField>

<ParamField path="config:reload(filePath, schema?)" type="function">
  Reloads a Lua config file, replaces the cached value, and optionally validates it.
</ParamField>

## Spawn

| Method                                     | Description                                                                             |
| ------------------------------------------ | --------------------------------------------------------------------------------------- |
| `spawn:ped(model, coords, heading, opts?)` | Spawns a client ped or registers a proximity stream entry.                              |
| `spawn:object(model, coords, opts?)`       | Spawns a client object or registers a proximity stream entry.                           |
| `spawn:scope()`                            | Creates an isolated cleanup scope with scoped `ped`, `object`, and `deleteAll` methods. |
| `spawn:deleteAll()`                        | Deletes tracked spawned entities and removes stream points.                             |

## LUI

<Tabs>
  <Tab title="Page">
    `lui.page(pageId, pageBuilder, props?)`, `lui.render(pageId)`, `lui.open(pageId, focusOptions?)`, and `lui.close(pageId)` manage client NUI pages.
  </Tab>

  <Tab title="Builder nodes">
    `text`, `button`, `input`, `select`, `textarea`, `slider`, `stack`, `row`, `panel`, `alert`, `tooltip`, `badge`, `typography`, `accordion`, `tabs`, `table`, `carousel`, `presence`, `motion*`, and `foreach`.
  </Tab>

  <Tab title="Declarative nodes">
    The same node factories are available directly on `lui`, plus `lui.list(source, render, props?)`, `lui.fragment(children)`, and `lui.component(component, ...)`.
  </Tab>
</Tabs>

## Cooldown

<Tabs>
  <Tab title="Server">
    `define(key, definition)` registers a cooldown definition with `initialDurationMs`, `durationMs`, optional `pauseTimerOn`, and optional `resetAfterZeroTicks`.
  </Tab>

  <Tab title="Client">
    `getRemaining(key, position)`, `start(key, position, durationMs?)`, `ready(callback)`, and `all()` manage client cooldown reads and updates.
  </Tab>
</Tabs>

## DB

| Method                               | Description                                                                  |
| ------------------------------------ | ---------------------------------------------------------------------------- |
| `db:schema(schemaName, definition?)` | Creates a model object. `definition.tableName` overrides the SQL table name. |
| `model:findMany({ where? })`         | Runs `SELECT *` with optional equality filters.                              |
| `model:findFirst({ where? })`        | Runs `SELECT * ... LIMIT 1` and returns one row or `nil`.                    |
| `model:create({ data })`             | Inserts sorted data fields and returns the insert id from oxmysql.           |
| `model:update({ data, where })`      | Updates rows. A non-empty `where` clause is required.                        |
| `model:delete({ where })`            | Deletes rows. A non-empty `where` clause is required.                        |
| `model:raw(sql, params?)`            | Runs a raw `query_async` call.                                               |

Console command: `sure_lib:db push <schemaName>` creates a table from `db/<schemaName>.lua`; `sure_lib:db pull <targetTable>` writes a schema file from the current database table.

## ESX

| Method                                           | Description                      |
| ------------------------------------------------ | -------------------------------- |
| `giveItem(playerSource, itemName, amount)`       | Give one inventory item.         |
| `giveItems(playerSource, items)`                 | Give multiple inventory items.   |
| `removeItem(playerSource, itemName, amount)`     | Remove one inventory item.       |
| `removeItems(playerSource, items)`               | Remove multiple inventory items. |
| `addMoney(playerSource, accountName, amount)`    | Add account money.               |
| `addMoneyEntries(playerSource, accounts)`        | Add multiple account entries.    |
| `removeMoney(playerSource, accountName, amount)` | Remove account money.            |
| `removeMoneyEntries(playerSource, accounts)`     | Remove multiple account entries. |
| `transactions(playerSource, entries)`            | Apply low-level action batches.  |

<Callout icon="list-check" color="#ffffff">
  All ESX helpers return a boolean. `false` means invalid input, missing player, malformed transaction data, or an unknown transaction action.
</Callout>