=== Kitbix Commerce ===
Contributors: kitbix
Tags: ecommerce, shop, cart, checkout, products
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Kitbix Commerce by [KitBix](https://kitbix.com/) is a lightweight, WordPress-native eCommerce plugin with a React admin dashboard and a framework-free storefront. The public repository lives at https://github.com/pay2fullstack/kitbix-commerce.

== Description ==

Kitbix Commerce is designed for site owners who want a simple, fast store experience that feels like WordPress. It keeps the storefront lightweight (no frontend framework required) while providing a modern React-powered admin for day-to-day store management.

Kitbix Commerce is a good fit if you:

- Want a small eCommerce footprint for a content-focused site.
- Prefer WordPress-native patterns (shortcodes, wp-admin, REST API).
- Need a clean foundation that developers can extend.

Key highlights:

- Lightweight storefront with plain templates and JavaScript.
- React admin dashboard inside wp-admin.
- WordPress REST API endpoints with nonce and capability checks.
- Extensible architecture for customizations and payment gateways.

Features (grouped):

*Store Management*

- Product management from a React admin dashboard.
- Order management workflow inside wp-admin.
- Customer directory with search, pagination, and profile insights for every shopper captured at checkout.
- WordPress-native storage using dedicated plugin tables.

*Storefront*

- Shortcodes for products, cart, and checkout.
- Category dropdown on the product grid so shoppers can filter by parent/child categories populated from the admin tree.
- Framework-free frontend output to keep pages fast and theme-friendly.
- Storefront behavior powered by WordPress REST endpoints.

*Payments & Checkout*

- Checkout flow designed to support multiple gateway types (card, redirect, offline).
- Gateway settings can be surfaced in the admin and consumed by the storefront.
- Ships with Stripe, PayPal, and Cash on Delivery gateways out of the box.
- Includes toggleable addons for Product Q&A sections on product pages, a Live View Counter for social proof, and a Payment Trust Badge block beneath the checkout payment methods list.

*Developer Friendly*

- PSR-4 autoloaded PHP code and a modular structure.
- Extensible payment gateway interface for custom implementations.
- Clean REST design that works well with custom frontends or integrations.
- Hierarchical category model + REST endpoints for developers who want to sync catalog taxonomies from external systems.

== Installation ==

1. Upload the plugin ZIP via Plugins -> Add New -> Upload Plugin (or copy the `kitbix-commerce` folder into `wp-content/plugins/`).
2. Activate Kitbix Commerce from the Plugins screen.
3. Open Kitbix Commerce -> Dashboard in wp-admin.
4. Create products and add the shortcodes below to pages.

Recommended pages:

- Shop page: `[kitbix_commerce_products]`
- Product page: `[kitbix_commerce_product]`
- Cart page: `[kitbix_commerce_cart]`
- Checkout page: `[kitbix_commerce_checkout]`

== External services ==

This plugin connects to two external payment services to power checkout flows:

* **Stripe** — the frontend enqueue loads `https://js.stripe.com/v3/` to initialize Stripe Elements, and server-to-server requests are performed through the Stripe PHP SDK when an order is processed. Customer billing details, order totals, and metadata required to complete the payment are sent to Stripe when a charge is created. See the [Stripe Terms](https://stripe.com/legal) and [Stripe Privacy Policy](https://stripe.com/privacy).
* **PayPal** — the PayPal PHP integration sends REST requests to `https://api-m.paypal.com` for live transactions or `https://api-m.sandbox.paypal.com` when sandbox mode is enabled. Checkout amounts, currency, and basic order references are included in those requests. See the [PayPal User Agreement](https://www.paypal.com/us/legalhub/useragreement-full) and [PayPal Privacy Statement](https://www.paypal.com/us/legalhub/privacy-full).

Both integrations only run when the corresponding gateway is enabled inside **Kitbix Commerce → Settings → Payments**, and they rely on credentials provided by the store owner. No data is transmitted to these services unless a customer initiates checkout using the configured gateway.

== Frequently Asked Questions ==

= What shortcodes are available? =

- `[kitbix_commerce_products]` — Product listing/grid
- `[kitbix_commerce_product]` — Product page
- `[kitbix_commerce_cart]` — Cart page
- `[kitbix_commerce_checkout]` — Checkout page

= Where do I manage products and orders? =

In wp-admin under **Kitbix Commerce → Dashboard**.

= Does it create database tables? =

Yes. On activation it runs migrations to create the required tables (orders, order items, products).

= Does uninstall remove data? =

By default, data is preserved on uninstall to prevent accidental loss.

= Will this slow down my site? =

Kitbix Commerce is built to keep the storefront lightweight. The admin dashboard assets load in wp-admin on Kitbix Commerce pages, and the storefront uses simple templates and JavaScript rather than a frontend framework.

= Will it work with my theme? =

The storefront output is designed to be theme-friendly. It uses shortcodes and standard HTML markup. Styling depends on your theme and the plugin CSS.

= Can developers extend Kitbix Commerce? =

Yes. The plugin is structured for extensibility, including a payment gateway interface and WordPress-native integration points. Developers can add custom behavior by building on the plugin architecture and WordPress hooks.

== Developer Guide: Custom Currency & Payment Gateways ==

=== 1. Registering a Custom Currency ===

Kitbix Commerce keeps its currency list in two helper filters:

1. `kitbix_commerce_currency_symbols` — define the ISO code → symbol map.
2. `kitbix_commerce_supported_currencies` — final list exposed to the admin UI and REST API.

```php
<?php
// Somewhere in your theme's functions.php or a custom plugin.

add_filter('kitbix_commerce_currency_symbols', function ($symbols) {
    $symbols['BDT'] = '৳'; // Add a custom symbol or override existing ones.
    $symbols['MXN'] = 'MX$';
    return $symbols;
});

add_filter('kitbix_commerce_supported_currencies', function ($currencies) {
    $currencies[] = 'BDT';
    $currencies[] = 'MXN';
    return $currencies;
});
```

After these hooks run, visit **Kitbix Commerce → Settings → Store** and pick the new currency. The REST API, admin React app, and storefront helpers (`kitbix_commerce_get_currency()`, `kitbix_commerce_format_currency()`) will all use the stored currency code.

=== 2. Creating a Custom Payment Gateway ===

Gateways are PSR-4 classes extending `KitbixCommerce\Services\Payment\BaseGateway` (or implementing `PaymentGatewayInterface`). Register them through the `kitbix_commerce_payment_gateways` filter:

```php
<?php
namespace MyPlugin\Payments;

use KitbixCommerce\Services\Payment\BaseGateway;

class BkashGateway extends BaseGateway
{
    public function id(): string
    {
        return 'bkash';
    }

    public function label(): string
    {
        return $this->getSetting('title', __('bKash', 'kitbix-commerce'));
    }

    public function supportedCurrencies(): array
    {
        // Limit the gateway to currencies bKash actually supports.
        return ['BDT'];
    }

    public function settingsFields(): array
    {
        $fields = parent::settingsFields();
        $fields[] = [
            'key' => 'merchant_number',
            'label' => __('Merchant Number', 'kitbix-commerce'),
            'type' => 'text',
            'required' => true,
        ];
        return $fields;
    }

    public function charge(array $orderData): array
    {
        // Use $orderData['amount'] and $orderData['currency'] (always the admin-selected currency)
        // to hit your provider API.
        return [
            'status' => 'pending',
            'transaction_id' => 'bkash_' . wp_generate_uuid4(),
            'message' => __('Complete the payment in your bKash app.', 'kitbix-commerce'),
        ];
    }
}

add_filter('kitbix_commerce_payment_gateways', function (array $gateways) {
    $gateways[] = new \MyPlugin\Payments\BkashGateway();
    return $gateways;
});
```

**Important:**

- Override `supportedCurrencies()` so the admin knows whether the gateway can be enabled for the selected currency. If it returns an empty array, the gateway is treated as "supports all currencies."  
- Implement `settingsFields()` to describe any merchant credentials required. The React admin UI renders these automatically in **Settings → Payments**.
- Kitbix Commerce passes canonical `amount` and `currency` values into `initiatePayment()` / `charge()`. Perform conversions or reformatting inside the gateway, never by editing the order totals upstream.

=== 3. Surfacing Gateways in the Admin UI ===

Once registered, gateways appear under **Kitbix Commerce → Settings → Payments**. Admin users can toggle them on, fill credentials, and the UI will automatically warn if a gateway does not support the currently-selected store currency.

=== 4. Frontend Checkout Considerations ===

- `CartService::availableGateways()` now filters out gateways that don’t support the stored currency, so the customer will only see valid payment options.  
- The checkout REST routes (`/kitbix-commerce/v1/payments`) send the store currency to every gateway integration, guaranteeing totals and settlements stay in sync.

=== Addon Integration ===

Kitbix Commerce ships with an addon registry so you can deliver modular features (like Product Q&A, back-in-stock alerts, etc.) without patching core files. Addons are standard PHP classes that implement `KitbixCommerce\Addons\AddonContract`.

1. **Create the addon class**

```
<?php
namespace KitbixCommerce\Addons\back_in_stock;

use KitbixCommerce\Addons\AddonContract;

class BackInStockAddon implements AddonContract {
    public function id(): string { return 'back_in_stock'; }

    public function definition(): array {
        return [
            'id' => $this->id(),
            'title' => __( 'Back In Stock Alerts', 'kitbix-commerce' ),
            'description' => __( 'Collect notify-me requests on sold-out items.', 'kitbix-commerce' ),
            'category' => 'marketing',
            'is_pro' => false,
            'icon' => 'dashicons-email',
        ];
    }

    public function bootstrap(): void {
        add_action( 'kitbix_commerce_after_product', [ $this, 'render_widget' ], 20, 2 );
        add_action( 'rest_api_init', [ $this, 'register_routes' ] );
    }

    public function render_widget( array $product, array $settings ): void {
        // Output storefront markup or enqueue assets.
    }

    public function register_routes(): void {
        register_rest_route( 'kitbix-commerce/v1', '/back-in-stock', [
            'methods'             => 'POST',
            'callback'            => [ $this, 'handle_submission' ],
            'permission_callback' => '__return_true',
        ] );
    }
}
```

2. **Register the addon** – Hook into `kitbix_commerce_register_addons` from your plugin or theme.

```
add_filter( 'kitbix_commerce_register_addons', function ( array $addons ) {
    $addons[] = \KitbixCommerce\Addons\back_in_stock\BackInStockAddon::class;
    return $addons;
} );
```

3. **Admin settings** – Return a `settings_fields` array inside `definition()` to render controls on **Kitbix Commerce → Addons**. Values are stored automatically and can be fetched via `AddonRegistry::getSettings( 'back_in_stock' )`.

4. **Conditional rendering** – Always gate frontend/admin hooks behind `AddonRegistry::isEnabled( 'back_in_stock' )` so disabled addons stay dormant.

Following this pattern (mirroring the Product Q&A addon) lets new developers build fully-featured modules: run migrations, register REST endpoints, enqueue public/admin assets, and expose settings, all without editing the Kitbix Commerce core plugin.

== Screenshots ==

1. Products dashboard – wp-admin screen listing every product with search, filters, stock and price columns, plus quick “Edit” and “Delete” actions and a “+ Add Product” CTA.
2. Cart & checkout UI – storefront cart powered by the Kitbix REST API with cutoff timer, inline quantity controls, total summary, and buttons for “Empty Cart” or “Proceed to Checkout.”
3. Orders detail drawer – modal inside the Orders page showing customer contact info, line items, totals, shipping, and dropdowns to update order/payment status.
4. Analytics overview – admin analytics dashboard with time-range tabs, KPI cards (orders, revenue, new customers), trend charts, status pie chart, and per-bucket bar charts.
5. Customers list – wp-admin table of customers with email, total paid, order count, and whether each customer is tied to a WordPress user.
6. Store settings – tabbed settings page (Store, Layout, Brand Colors, Payments, Email & SMTP) showing currency, tax rate, and shipping inputs with “Save Settings.”
7. Addon manager – grid of the seven bundled addons (Live Purchase Toast, Live View Counter, Payment Trust Badge, Product Q&A, Related Products, Shipping Cutoff Clock, WhatsApp Contact) each with toggle, message fields, and layout controls.

== Changelog ==

= 1.0.0 =
- Initial release.

== Upgrade Notice ==

= 1.0.0 =
- Initial public release of Kitbix Commerce.