=== EGF MiniApp ===
Tags: woocommerce, telegram, max, web app, mini app
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect WooCommerce to Telegram and MAX Mini Apps through the Ecommerce GodFather cloud platform.

== Description ==

EGF MiniApp connects a WooCommerce store to Telegram and MAX Mini Apps. The customer-facing React application is served from files included with the plugin, while the WordPress REST API reads products, customers, carts, wishlists, reviews, consent choices, and orders from the local WooCommerce installation.

The plugin is the WordPress/WooCommerce connector for the external Ecommerce GodFather service (`egodfather.app`). The cloud service provides bot webhook processing, messenger CRM features, notifications, broadcasts, abandoned-cart workflows, and remote order management. An Ecommerce GodFather account and an active service connection are required; the plugin is not a standalone Mini App without that connection.

Ecommerce GodFather offers free and paid service plans. Available cloud features and usage limits depend on the selected plan and may change over time. Current plan information is available at https://egodfather.app/en#pricing. The WordPress plugin itself does not contain premium code, local trial limits, or features that are unlocked by a license check.

== Features ==

* Serve a responsive WooCommerce storefront inside Telegram and MAX Mini Apps.
* Read products, categories, prices, stock status, reviews, and order history directly from WooCommerce.
* Create WooCommerce customers and orders from verified messenger users.
* Store persistent carts and customer wishlists in WordPress.
* Synchronize customers, carts, wishlists, consent choices, and orders with Ecommerce GodFather.
* Integrate with the cloud messenger CRM, customer-support workflow, notifications, broadcasts, and abandoned-cart tools available for the selected service plan.
* Allow managers to receive order information and update supported order statuses through the connected service.
* Support optional Google Analytics and Yandex.Metrica integration with configurable consent settings.
* Include readable React/TypeScript source code and the complete frontend build configuration.

== External services ==

This plugin communicates with the external services described below. Installing, configuring, and connecting the plugin is an explicit action by the site administrator to use these services.

= Ecommerce GodFather (egodfather.app) — required =

Ecommerce GodFather is the required SaaS backend for the Mini App. It provides functionality of substance outside WordPress, including bot webhook handling, cloud CRM profiles, messaging and notification delivery, broadcasts, abandoned-cart workflows, and remote order-status management.

The service offers free and paid plans. Feature availability and service limits depend on the current plan selected for the Ecommerce GodFather account.

The plugin uses the service for:

* connecting and validating the shop domain and API key;
* sending and retrieving Telegram/MAX bot settings;
* synchronizing messenger users with the cloud CRM;
* synchronizing carts and wishlists;
* synchronizing user consent choices;
* sending WooCommerce orders and later order-status changes;
* retrying failed order delivery;
* receiving authenticated order-status and messaging-related callbacks from the service.

Requests may be made:

* when an administrator connects the store or synchronizes bot settings;
* when protected Mini App endpoints verify the local connection state and a periodic remote validation is due;
* when a messenger user is first recognized;
* when a wishlist or consent choice changes;
* when an order is created or changes status;
* when a cart is cleared; and
* during the recurring cart synchronization task, normally every five minutes.

Connection credentials and configuration:

* the API key and Telegram/MAX bot tokens are stored in WordPress options on the merchant's site;
* initial connection and periodic validation send the API key and shop domain in the HTTPS request body;
* subsequent authenticated API requests send the API key in the `X-Api-Key` HTTPS request header;
* bot-settings synchronization may transmit the Telegram and MAX bot tokens, administrator IDs, support-group IDs, the selected messenger platform, and translated bot-command texts;
* the API key and bot tokens are not returned by the Mini App `/settings` REST endpoint and are not embedded in the frontend bundle.

Categories of data that may be transmitted to Ecommerce GodFather:

* shop domain and connection credentials described above;
* messenger type, messenger user ID, username, and customer display name;
* cart items, quantities, product names, prices, product image URLs, cart totals, and update timestamps;
* wishlist actions and product IDs, names, prices, and image URLs;
* order ID, status, currency, totals, customer note, purchased items, quantities, SKU values, customer name, phone number, and billing address;
* consent choices for terms, analytics, and marketing, together with the selected jurisdiction.

The service may return authenticated callbacks that update supported WooCommerce order statuses or provide notification text. These callbacks are protected by the stored API credential.

To stop using Ecommerce GodFather, deactivate the plugin and remove the connection credentials if they should not remain stored. Without a valid service connection, protected Mini App endpoints are unavailable.

Service website and current plans: https://egodfather.app/en
Terms of Service: https://blog.egodfather.app/en/terms-of-service/
Privacy Policy: https://blog.egodfather.app/en/privacy-policy/

= Telegram Web App SDK (telegram.org) — required in Telegram =

When the Mini App is opened in Telegram, the plugin loads the official Telegram Web App SDK from `https://telegram.org/js/telegram-web-app.js`.

* The Telegram SDK is loaded only when Telegram is detected.
* It provides the Telegram Mini App environment and signed `initData`.
* The signed `initData` is sent to the REST API of the same WordPress site for server-side signature and freshness verification.
* The plugin does not send the received `initData` back to Telegram in a separate request.

Terms of Service: https://telegram.org/tos
Mini Apps Terms: https://telegram.org/tos/mini-apps
Privacy Policy: https://telegram.org/privacy

= MAX Web App SDK (st.max.ru) — required in MAX =

When the Mini App is opened in MAX, the plugin loads the MAX Web App SDK from `https://st.max.ru/js/max-web-app.js`.

* The MAX SDK is loaded only when MAX is detected.
* It provides the MAX Mini App environment and signed `initData`.
* The signed `initData` is sent to the REST API of the same WordPress site for server-side signature and freshness verification.
* The plugin does not send the received `initData` back to MAX in a separate request.

Terms of Service: https://legal.max.ru/ps
Privacy Policy: https://legal.max.ru/pp

= Google Analytics (googletagmanager.com) — optional =

Google Analytics is optional.

* The `gtag.js` script is loaded from `www.googletagmanager.com` only when a Google Analytics ID is configured and analytics consent has been granted.
* Data that may be transmitted includes the page path, messenger user ID as `user_id`, ecommerce data, and interface events.
* This data must not be treated as fully anonymous.
* Remove the Google Analytics ID or withhold analytics consent to prevent the integration from loading.

Terms of Service: https://policies.google.com/terms
Privacy Policy: https://policies.google.com/privacy

= Yandex.Metrica (mc.yandex.ru) — optional =

Yandex.Metrica is optional.

* The tag script is loaded from `mc.yandex.ru` when a counter ID is configured.
* Normally the script is loaded only after analytics consent.
* In FZ-152 mode, the site owner may enable the "Metrica always on" setting, which allows Metrica to load without a separate analytics-consent checkbox.
* Data that may be transmitted includes the counter ID, messenger user ID through `setUserID`, page views, goals, and ecommerce events.
* Remove the counter ID and disable the corresponding setting to prevent the integration from loading.

Terms of Service: https://yandex.ru/legal/metrica_termsofuse/
Privacy Policy: https://yandex.ru/legal/confidential/

== Automatic WooCommerce customer creation ==

When the frontend initializes a user after successful Telegram or MAX `initData` verification, the plugin creates or reuses a WordPress/WooCommerce customer record.

* The role is explicitly assigned as the WooCommerce `customer` role.
* The login is generated as `tg_<id>` for Telegram or `max_<id>` for MAX.
* A technical local email such as `tg_<id>@telegram.local` or `max_<id>@max.local` is generated only to satisfy WordPress's unique-email requirement.
* A strong random password is generated.
* Authentication cookies are not set; the record is used for WooCommerce data binding rather than a normal browser login session.
* The customer ID is used to associate addresses, orders, wishlists, reviews, and consent records.
* Identical numeric IDs from Telegram and MAX are treated as different identities.

The technical local email is not a customer contact address and must not be used for communication.

== Locally stored data ==

The plugin stores the following data on the WordPress site:

* options prefixed with `egf_miniapp_*`, including connection credentials, bot settings, design settings, analytics IDs, and consent/legal settings;
* user meta prefixed with `_egf_miniapp_*`, including messenger identity, wishlist, and consent state;
* order meta prefixed with `_egf_miniapp_order_*`;
* review/comment meta prefixed with `_egf_miniapp_review_*`;
* the custom table `{table_prefix}egf_miniapp_persistent_cart` for persistent carts;
* a transient used as a cart-sync lock;
* WP-Cron events and Action Scheduler actions for cart synchronization and order-delivery retries; and
* frontend `localStorage` entries for interface state, consent state, and recently viewed products.

Standard WordPress and WooCommerce data, such as billing/shipping fields and WooCommerce review ratings, is not plugin-specific metadata.

== Privacy ==

The site owner is the party that decides why and how customer data is processed. Ecommerce GodFather processes data on behalf of the merchant as described in its Privacy Policy.

The site owner is responsible for:

* describing the processing and external services in the site's own Privacy Policy;
* informing customers that messenger identity, cart, wishlist, order, and consent data may be processed by Ecommerce GodFather;
* configuring all policy links and consent-screen text;
* establishing an appropriate lawful basis for processing;
* obtaining any consent required before analytics or marketing features are enabled;
* reviewing the service provider's current data-retention and international-transfer terms; and
* determining whether GDPR, FZ-152, CCPA/CPRA, or other laws apply to the store.

This plugin provides technical consent and integration tools and does not constitute legal advice. Installing the plugin does not by itself make a site compliant with any law.

== Installation ==

1. Install and activate WooCommerce.
2. Upload the `egf-miniapp` folder to `/wp-content/plugins/`, or install the plugin ZIP through the WordPress Plugins screen.
3. Activate EGF MiniApp.
4. Create an Ecommerce GodFather account at https://egodfather.app. Free and paid plans are available; cloud features and limits depend on the selected plan.
5. Generate an API key in the Ecommerce GodFather dashboard and enter it in the EGF MiniApp settings in WordPress.
6. Add the Telegram and/or MAX bot token, administrator IDs, support-group settings, and selected platform, then synchronize the settings with Ecommerce GodFather.
7. Configure the Mini App/Web App URL in the selected messenger as `https://your-site.example/app/` and follow the current bot-setup instructions in the Ecommerce GodFather documentation.
8. Configure the storefront, legal-policy URLs, consent options, and optional analytics integrations.
9. Open the Mini App from Telegram or MAX and test customer creation, cart, wishlist, consent, and order flows.

Documentation: https://blog.egodfather.app/en/docs/

== Frequently Asked Questions ==

= Is an Ecommerce GodFather account required? =

Yes. The plugin is the WordPress/WooCommerce connector for the Ecommerce GodFather cloud service and does not operate as a standalone Mini App without an active connection.

= Is the external service free? =

Ecommerce GodFather offers free and paid plans. The features and usage limits available to a store depend on the selected service plan. Check the service website for current plan details.

= Does the plugin contain paid or locked WordPress features? =

No. The plugin code distributed here is fully available under the GPL. Plan-dependent functionality is provided by the external Ecommerce GodFather service, not unlocked from hidden or premium code inside this plugin.

= Are API keys or bot tokens exposed to Mini App visitors? =

No. They are stored in WordPress options and used for local verification or server-to-server HTTPS requests. They are not returned by the frontend `/settings` endpoint or embedded in the production frontend bundle.

= Do I need to create customers manually? =

No. A WooCommerce customer record is created automatically when a messenger user is initialized after valid Telegram or MAX `initData` verification.

= What happens if the Ecommerce GodFather connection is unavailable? =

Temporary network or server errors do not immediately disconnect the shop. Repeated explicit validation failures eventually change the local connection status to `disconnected`, after which protected Mini App endpoints are unavailable until the connection is restored.

= Does uninstalling the plugin delete customers or orders? =

No. Customers, orders, reviews, products, and attachments are never deleted by the plugin's uninstall routine. Optional plugin-specific data removal is described below.

== Uninstall behavior ==

The "Delete plugin data on uninstall" option is off by default.

When the option is OFF:

* scheduled WP-Cron events and Action Scheduler actions are cancelled;
* the cart-sync lock transient is deleted; and
* plugin options, credentials, the persistent-cart table, and plugin-prefixed metadata are retained for a possible reinstall.

When the option is ON:

* all `egf_miniapp_*` options are removed;
* the custom persistent-cart table is dropped;
* plugin-prefixed user and review metadata is removed;
* plugin-prefixed order metadata is removed through the WooCommerce CRUD API for HPOS compatibility; and
* WordPress/WooCommerce customers, orders, reviews, products, attachments, and standard platform data are not deleted.

== Source code and build instructions ==

Readable React/TypeScript source code and the complete build configuration are included in:

`source/`

The directory includes `src/`, `public/`, `index.html`, `package.json`, `package-lock.json`, `vite.config.ts`, TypeScript configuration, and the Tailwind/PostCSS/ESLint configuration used by the build.

Build commands:

`cd source`
`npm ci`
`npm run build`

The command creates the build output in:

`source/dist/`

For a release package, copy the contents of `source/dist/` into:

`webapp/`

The production files already distributed with the plugin are located in `webapp/`.

== Credits ==

Sortable.js — MIT License — https://github.com/SortableJS/Sortable

== Changelog ==

= 1.0.3 =

* Tightened order ownership verification and returned the same neutral response for missing and unauthorized orders.
* Explicitly assigned the WooCommerce `customer` role when messenger users are created and hardened concurrent-creation handling.
* Hardened Telegram/MAX `initData` signature and freshness verification.
* Protected the `/settings` REST endpoint with verified `initData`.
* Removed global REST error handlers and stopped exposing exception details or filesystem paths in error responses.
* Removed the unnecessary global REST CORS behavior while preserving the headers required to serve the Mini App frontend.
* Added direct-access protection to applicable PHP controller files and removed production debug logging.
* Added plugin-specific prefixes to WordPress metadata and cron schedule identifiers.
* Improved uninstall behavior with an explicit data-removal option that is off by default.
* Updated the database migration annotations used by WordPress Coding Standards without changing the migration SQL.
* Changed the frontend loader so only the Telegram or MAX SDK required for the detected messenger is loaded.
* Included readable frontend source code and reproducible build configuration.
* Expanded the external-services, privacy, local-data, and uninstall documentation.
* Aligned plugin, readme, and translation version metadata at 1.0.3.

= 1.0.0 =

* Initial release.
