# License Strategy and Logic Specification: TeknoTok AI Translator Pro

This document specifies the software licensing strategy, local validation rules, grace period implementation, and premium feature gating logic for **TeknoTok AI Translator Pro**.

---

## 1. Local Database Storage

License data must be stored securely inside the default WordPress `options` database table. The database contains the following entries:

### 1.1 Options Schema
- `teknotok_translator_license_key`: The raw license key string (e.g., `XXXX-XXXX-XXXX-XXXX`). Excluded from frontend scripts.
- `teknotok_translator_license_status`: Stored status flag string (`active`, `expired`, `invalid`, `inactive`).
- `teknotok_translator_license_expires`: Unix timestamp or Date string defining the expiration date.
- `teknotok_translator_license_last_check`: Unix timestamp tracking the last remote verification date.
- `teknotok_translator_license_error_count`: Integer counting sequential remote verification timeouts/failures.

---

## 2. Remote Validation Flow & Grace Period

To ensure the plugin remains functional when the TeknoTok licensing server is down or under maintenance, the plugin implements a local caching validation mechanism with a **48-hour Grace Period**.

### 2.1 Schedule Check Mechanics
1. A daily cron job (`teknotok_translator_license_check_cron`) executes to verify the license by calling the `/check` endpoint.
2. **Success (API Active)**:
   - Updates `teknotok_translator_license_status` based on API response.
   - Resets `teknotok_translator_license_error_count` to `0`.
   - Updates `teknotok_translator_license_last_check` to the current time.
3. **Failure (API Timeout/Server 500)**:
   - Increments `teknotok_translator_license_error_count` by 1.
   - Calculates the delta between the current timestamp and `teknotok_translator_license_last_check`.
   - **If delta < 48 hours**:
     - The license status remains `active`.
     - An admin alert notice is *not* triggered. The plugin behaves as active.
   - **If delta >= 48 hours**:
     - Status is set to `inactive`.
     - An admin alert warning is rendered: *"TeknoTok AI Translator Pro license could not be validated. Please check your connection or contact support."*
     - Premium features are temporarily disabled.

---

## 3. Premium Feature Gating Logic

All code pathways that access OpenAI providers, process background queues, or support multiple targets check the licensing state.

### 3.1 Gating Method Definition
A utility method inside `LicenseManager` is defined:

```php
namespace TeknoTok\AiTranslator\Integrations;

class LicenseManager {
    /**
     * Helper check to verify if premium operations are authorized.
     * Includes grace period evaluation.
     * 
     * @return bool
     */
    public static function is_premium_active(): bool {
        $status = get_option('teknotok_translator_license_status', 'inactive');
        if ('active' === $status) {
            return true;
        }

        // Grace period verification
        $last_check = (int) get_option('teknotok_translator_license_last_check', 0);
        $time_delta = time() - $last_check;
        
        if ($time_delta < 172800) { // 48 hours in seconds
            $errors = (int) get_option('teknotok_translator_license_error_count', 0);
            if ($errors > 0) {
                return true; // Allow active features within grace period
            }
        }

        return false;
    }
}
```

### 3.2 Gated Access Control List
The following functionalities check `LicenseManager::is_premium_active()` before executing:
1. **Target Languages count**: Free version allows only 1 target language. Premium version allows up to 10+ selected target languages.
2. **Auto-Translation Hook Execution**: Saving or editing post content will only trigger background queue insertion if the license is active.
3. **Manual Override Editor**: Reviewing and modifying translation memory segments from the editor screen is blocked for non-premium users.
4. **Browser Language Detection redirection**: Checking navigator attributes and prompting the visitor is a premium-only setting.
