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

# Client exports

> Reference for FA Shop Robbery client exports and clerk lifecycle events.

FA Shop Robbery exposes a client-side API for shop and target integrations. These exports describe the local clerk entity and its current presentation state.

<Warning>
  Every export on this page is **client-side only**. Do not use it for purchases, prices, rewards, or other authoritative gameplay decisions. Validate those actions in the owning resource's server code.
</Warning>

## Resource name

Examples use the default resource name:

```lua theme={null}
exports['fa_shoprobbery']:GetClerkEntity('ltd_grove')
```

If your server uses a different resource folder name, replace `fa_shoprobbery` with the running resource name in every export call.

## `GetClerkEntity`

Returns the local ped entity for a configured store.

```lua theme={null}
local entity = exports['fa_shoprobbery']:GetClerkEntity('ltd_grove')
if entity then
    -- Add or refresh your client-side target on this ped.
end
```

| Parameter | Type     | Description                         |
| --------- | -------- | ----------------------------------- |
| `storeId` | `string` | The store `id` from `Config.Stores` |

Returns the entity handle (`number`) or `nil` when the store is unknown, the clerk is disabled, or the local entity does not exist.

## `GetClerkState`

Returns the last published clerk state for a configured store.

```lua theme={null}
local state = exports['fa_shoprobbery']:GetClerkState('ltd_grove')
```

| Parameter | Type     | Description                         |
| --------- | -------- | ----------------------------------- |
| `storeId` | `string` | The store `id` from `Config.Stores` |

Returns one of `idle`, `surrendering`, `intimidated`, `hostile`, `dead`, or `disabled`, or `nil` when the store ID is unknown or the state has not been published yet.

## `CanUseClerkShop`

Returns whether the clerk is present, alive, and currently idle.

```lua theme={null}
canInteract = function()
    return exports['fa_shoprobbery']:CanUseClerkShop('ltd_grove')
end
```

| Parameter | Type     | Description                         |
| --------- | -------- | ----------------------------------- |
| `storeId` | `string` | The store `id` from `Config.Stores` |

Returns `true` only while the local clerk entity exists, is alive, and has the `idle` state. Use this as a client-side visibility guard for a shop target.

## `GetClerkData`

Returns the current clerk snapshot in one table.

```lua theme={null}
local clerk = exports['fa_shoprobbery']:GetClerkData('ltd_grove')
if clerk and clerk.available then
    print(clerk.storeId, clerk.entity, clerk.state)
end
```

| Field       | Type            | Description                                           |
| ----------- | --------------- | ----------------------------------------------------- |
| `storeId`   | `string`        | Configured store ID                                   |
| `entity`    | `number \| nil` | Current local clerk entity                            |
| `state`     | `string \| nil` | Last published clerk state                            |
| `available` | `boolean`       | `true` only when the clerk exists, is alive, and idle |
| `coords`    | `table \| nil`  | Clerk coordinates with `x`, `y`, and `z`              |

Returns `nil` when the store ID is unknown.

## `FindClerkStore`

Finds the closest enabled clerk store within a radius. This is useful when another resource starts from its own shop location instead of FA Shop Robbery's store ID.

```lua theme={null}
local storeId = exports['fa_shoprobbery']:FindClerkStore(vector3(-47.0, -1758.2, 29.4), 2.0)
if storeId then
    print(('Matched FA Shop Robbery store: %s'):format(storeId))
end
```

| Parameter     | Type                           | Description                                                  |
| ------------- | ------------------------------ | ------------------------------------------------------------ |
| `coords`      | `vector3`, `vector4`, or table | Coordinates with `x`, `y`, and `z`                           |
| `maxDistance` | `number` (optional)            | Search radius in metres. Defaults to `2.0`; minimum is `0.1` |

Returns the closest enabled store ID or `nil` when no clerk is within the radius.

## Lifecycle events

Subscribe to events and refresh your target instead of caching a ped indefinitely. A killed or reset clerk can be recreated with a new entity handle.

```lua theme={null}
AddEventHandler('fa_shoprobbery:client:clerkCreated', function(data)
    -- data.storeId, data.entity, data.state, data.previousState, data.coords
end)

AddEventHandler('fa_shoprobbery:client:clerkStateChanged', function(data)
    -- data.storeId, data.entity, data.state, data.previousState, data.coords
end)

AddEventHandler('fa_shoprobbery:client:clerkRemoved', function(data)
    -- data.storeId, data.entity, data.state, data.reason, data.coords
end)
```

Each event passes a table containing `storeId`, `entity`, `state`, and `coords`. `clerkStateChanged` also includes `previousState`. `clerkRemoved` includes `reason`.

<Tip>
  When your resource starts after FA Shop Robbery, call `GetClerkData` once during startup and then subscribe to the lifecycle events for subsequent changes.
</Tip>