=== WE88 Portal ===
Contributors: we88portal
Tags: casino, gaming, we88, portal, integration, gutenberg
Requires at least: 6.0
Tested up to: 6.7
Stable tag: 1.0.0
Requires PHP: 8.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Frontend presentation layer and BFF proxy connecting WordPress to the We88 gaming platform via the External API.

== Description ==

WE88 Portal is a WordPress plugin that acts as the frontend presentation layer and Backend-for-Frontend (BFF) proxy between your WordPress site and the We88 gaming platform.

**Three-tier architecture:**

1. **WordPress Plugin (this plugin)** — Renders UI widgets (login, profile, games lobby, balance, reviews, popup menu) via shortcodes and Gutenberg blocks. Exposes an internal REST API at `/wp-json/we88-portal/v1/` consumed by the frontend React components. The browser never communicates with the External API directly.

2. **External API (Go service)** — A Go-based middleware service that handles authentication, session management, caching, and rate limiting before proxying requests upstream to the We88 platform. All sensitive credentials and business logic reside here, outside of WordPress.

3. **We88 Upstream** — The We88 gaming platform providing player accounts, game catalogues, wallet balances, and review data.

**Features:**

* Login / register / forgot-password widget
* Authenticated user profile display
* Games lobby with provider and category filtering, configurable grid layout
* Real-time account balance display with auto-refresh
* User reviews widget
* Floating popup navigation menu
* Six ready-to-use Gutenberg blocks (WE88 Portal block category)
* WP Admin settings page (Settings > WE88 Portal) for API configuration
* Full i18n support via the `we88-portal` text domain

== Installation ==

1. Download the plugin zip or clone the repository into `/wp-content/plugins/we88-portal/`.
2. If building from source, run the asset build steps described in the **Developer Notes** section below.
3. Activate the plugin via **Plugins > Installed Plugins** in the WordPress admin.
4. Navigate to **Settings > WE88 Portal** and enter your External API URL and API token.
5. (Optional) Adjust the cache TTL, request timeout, retry count, and environment setting to match your deployment.
6. Add shortcodes or Gutenberg blocks to any page or post where you want WE88 widgets to appear.

== Configuration ==

All settings are managed from **Settings > WE88 Portal** in the WordPress admin. The following options are available:

= API URL =
The base URL of your External API (Go service), e.g. `https://api.example.com`. This is the only service the plugin communicates with; it must be reachable from the WordPress server.

= API Token =
Bearer token used to authenticate requests from the plugin to the External API. Keep this value secret — it is stored in the WordPress options table and never exposed to the browser.

= Environment =
Set to `production` for live sites or `staging` / `development` for non-production environments. Some debug output is only enabled in non-production modes.

= Cache TTL =
Time-to-live (in seconds) for cached API responses stored as WordPress transients. Default: `300` (5 minutes). Set to `0` to disable caching.

= API Timeout =
Maximum time (in seconds) to wait for a response from the External API before aborting. Default: `10`.

= API Retries =
Number of times to retry a failed API request before returning an error. Default: `2`.

= Debug Mode =
When enabled, additional diagnostic information is logged to the PHP error log. Disable on production.

== Shortcode Reference ==

All shortcodes output server-rendered HTML. They require no JavaScript configuration — the React frontend bootstraps automatically from the rendered markup.

= [we88_login] =

Renders the login / register / forgot-password widget.

**Usage:**

    [we88_login]

No attributes. Automatically shows the appropriate form based on the user's session state.

= [we88_profile] =

Renders the authenticated user's profile information.

**Usage:**

    [we88_profile]

No attributes. Requires an active We88 session; shows a prompt to log in if no session is present.

= [we88_games] =

Renders the games lobby with optional filtering and layout control.

**Attributes:**

* `provider` (string, optional) — Filter games by provider slug, e.g. `pragmatic`, `evolution`. Defaults to all providers.
* `category` (string, optional) — Filter games by category slug, e.g. `slots`, `live-casino`. Defaults to all categories.
* `columns` (integer, default `4`) — Number of columns in the game grid.
* `per_page` (integer, default `20`) — Number of games to load per page.

**Usage:**

    [we88_games]
    [we88_games provider="pragmatic" columns="4" per_page="20"]
    [we88_games category="live-casino" columns="3" per_page="12"]

= [we88_balance] =

Renders the user's current account balance with optional wallet breakdown and auto-refresh.

**Attributes:**

* `interval` (integer, default `30`) — Auto-refresh interval in seconds. Set to `0` to disable auto-refresh.
* `show_wallets` (boolean, default `true`) — Whether to display the individual wallet breakdown alongside the total balance.

**Usage:**

    [we88_balance]
    [we88_balance interval="30" show_wallets="true"]
    [we88_balance interval="0" show_wallets="false"]

= [we88_reviews] =

Renders the user reviews widget.

**Usage:**

    [we88_reviews]

No attributes.

= [we88_popup_menu] =

Renders the floating popup navigation menu. Typically placed once in a footer or global template.

**Usage:**

    [we88_popup_menu]

No attributes.

== Gutenberg Blocks ==

All six shortcodes are also available as Gutenberg blocks under the **WE88 Portal** block category in the block editor. The blocks are server-side rendered — they call the same shortcode render logic — and support the same attributes.

Available blocks:

* **WE88 Login** (`we88/login`)
* **WE88 Profile** (`we88/profile`)
* **WE88 Games** (`we88/games`) — provider, category, columns, per_page attributes
* **WE88 Balance** (`we88/balance`) — interval, show_wallets attributes
* **WE88 Reviews** (`we88/reviews`)
* **WE88 Popup Menu** (`we88/popup-menu`)

== Developer Notes ==

= Building Frontend Assets =

The plugin ships two separate React frontends: one for the public-facing widgets and one for the admin settings page.

**Public frontend:**

    cd public
    npm install
    npm run build

Compiled output is written to `public/dist/`. The plugin reads `public/dist/manifest.json` to fingerprint asset URLs.

**Admin frontend:**

    cd admin
    npm install
    npm run build

Compiled output is written to `admin/dist/`. The plugin reads `admin/dist/manifest.json` to fingerprint asset URLs.

= Architecture =

    WordPress Plugin (PHP)
        └── /wp-json/we88-portal/v1/*  (REST API consumed by React)
            └── External API (Go service)
                └── We88 upstream platform

The plugin never calls the We88 upstream directly. All API communication is routed through the External API, which enforces authentication, caching, and rate limiting.

= Admin Settings Page =

The admin UI is a React single-page application mounted at `#we88-portal-admin-root`. It is loaded only on the **Settings > WE88 Portal** admin page (`options-general.php?page=we88-portal`).

= Plugin Constants =

Defined in `we88-portal.php`:

* `WE88_PORTAL_VERSION` — Plugin version string.
* `WE88_PORTAL_PLUGIN_FILE` — Absolute path to the main plugin file.
* `WE88_PORTAL_PLUGIN_DIR` — Absolute path to the plugin directory (trailing slash).
* `WE88_PORTAL_PLUGIN_URL` — URL to the plugin directory (trailing slash).
* `WE88_PORTAL_PLUGIN_BASENAME` — Plugin basename, e.g. `we88-portal/we88-portal.php`.

= Autoloader =

The plugin registers a custom `spl_autoload_register` callback that maps `We88Portal\ClassName` to `includes/class-classname.php` and `We88Portal\Sub\ClassName` to `includes/sub/class-classname.php`. No Composer autoload is required for plugin classes, though Composer is used for third-party dependencies.

== Frequently Asked Questions ==

= Does this plugin work without the External API? =

No. The plugin requires the External API (Go service) to be running and accessible from the WordPress server. Without it, all shortcodes and blocks will return errors or empty output. Configure the API URL and token in **Settings > WE88 Portal** before using any widgets.

= Can I use the shortcodes and Gutenberg blocks at the same time? =

Yes. Shortcodes and blocks are interchangeable — they produce identical output. Use whichever suits your page-building workflow.

= How do I change the number of columns in the games lobby? =

Use the `columns` attribute on the shortcode or set the **Columns** field in the WE88 Games block inspector panel. For example: `[we88_games columns="3"]`.

= Is the API token exposed to site visitors? =

No. The API token is stored server-side in the WordPress options table and is only used in server-to-server requests from PHP to the External API. It is never included in any HTML output or JavaScript variables sent to the browser.

== Changelog ==

= 1.0.0 =
* Initial release.
* Login, profile, games, balance, reviews, and popup-menu shortcodes.
* Six server-side-rendered Gutenberg blocks with a custom WE88 Portal block category.
* WP Admin settings page (Settings > WE88 Portal).
* Internal REST API at `/wp-json/we88-portal/v1/`.
* BFF proxy architecture: WordPress plugin communicates exclusively with the External API (Go service).
* Custom autoloader for the `We88Portal` namespace.
* Plugin activation defaults and transient-cache cleanup on deactivation.
