Jacob Schmidt 89169f1e84 Update documentation and add new client usage guides

- Revised README.md for the Forge Client Example Addon to clarify its purpose as a template.
- Enhanced MODULE_REFERENCE.md to categorize guides into Server and Extension guides and Client guides.
- Created detailed usage guides for various client addons including Actor, Bank, CAD, Garage, Locker, Notifications, Organization, Phone, and Store.
- Added a Client Common Usage Guide to outline shared browser UI bridge patterns.
- Introduced a Client Main Usage Guide to define the foundational elements for client addons.
- Established authoritative state notes and usage rules across new guides to ensure clarity on server ownership and client responsibilities.

2026-04-18 13:04:01 -05:00

2.7 KiB

Raw Blame History

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

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.

{
  "category": "weapons"
}

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

Checkout Requests

Checkout requests send a serialized checkout payload:

{
  "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.

2.7 KiB Raw Blame History