# Client Store Usage Guide

The client store addon provides the storefront browser UI for catalog browsing,
category hydration, payment source display, cart handling, and checkout
requests.

## Open Store UI

```sqf
call forge_client_store_fnc_openUI;
```

The UI opens `RscStore`, loads `ui/_site/index.html`, and routes browser alerts
through `forge_client_store_fnc_handleUIEvents`.

## Bridge

`forge_client_store_fnc_initUIBridge` owns:

- browser control lookup
- store hydrate requests
- category requests
- checkout requests
- category hydrate/failure responses
- checkout success/failure responses
- store config refresh after successful checkout

Store currently uses its own `StoreUIBridge.receive(...)` browser bridge rather
than the shared `ForgeBridge.receive(...)` delivery used by newer bridges.

## Browser Events

| Event | Client behavior |
| --- | --- |
| `store::ready` | Request store hydrate from the server. |
| `store::category::request` | Request catalog items for a category. |
| `store::checkout::request` | Forward checkout JSON to the server. |
| `store::close` | Close the display. |

## Browser Response Events

| Event | Purpose |
| --- | --- |
| `store::hydrate` | Initial storefront/session/config payload. |
| `store::config::hydrate` | Refreshed payment/source config. |
| `store::category::hydrate` | Category catalog payload. |
| `store::category::failure` | Category request failure. |
| `store::checkout::success` | Checkout success payload. |
| `store::checkout::failure` | Checkout failure payload. |

## Category Requests

Category requests require a non-empty category value.

```json
{
  "category": "weapons"
}
```

The client lowercases the category before forwarding it to the server store
addon.

## Checkout Requests

Checkout requests send a serialized checkout payload:

```json
{
  "checkoutJson": "{\"items\":[],\"paymentSource\":\"cash\"}"
}
```

The client only forwards the checkout data. The server store addon and
extension validate prices, inventory grants, payment source authorization, and
integration with bank, organization, locker, and garage state.

After a successful checkout, the client asks the server for a fresh store config
payload so payment-source balances and permissions stay current.

## Authoritative State

Catalog data, prices, checkout validation, money movement, organization funds,
credit lines, locker grants, garage grants, and persistence are server-owned.

## Related Guides

- [Store Usage Guide](./STORE_USAGE_GUIDE.md)
- [Client Bank Usage Guide](./CLIENT_BANK_USAGE_GUIDE.md)
- [Client Organization Usage Guide](./CLIENT_ORG_USAGE_GUIDE.md)
- [Client Locker Usage Guide](./CLIENT_LOCKER_USAGE_GUIDE.md)
- [Client Garage Usage Guide](./CLIENT_GARAGE_USAGE_GUIDE.md)
