=== TimeQuota – User Time Limits ===

Contributors: roardev
Tags: time limit, user quota, session limit, access control, time management
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Control and restrict active browsing time per user, role, and guest visitor. Measures real engagement and blocks access when daily limits are reached.

== Description ==

**TimeQuota** is a lightweight, production-ready WordPress plugin that empowers website owners to set daily active time limits for users and guest visitors.

Unlike simple session timeout plugins that merely calculate `current_time - login_time`, TimeQuota accurately tracks **true active engagement**. If a user switches to another tab, minimizes their browser, or walks away from their keyboard, the timer instantly pauses.

### Key Features:

* **True Active Time Tracking**: Uses Page Visibility API, window focus/blur, and user activity events (mouse movement, keystrokes, scrolling) to measure genuine active engagement.
* **Server-Side Enforcement**: Client timers are never trusted. All limits, timestamps, and heartbeats are authoritatively validated and calculated on the WordPress backend.
* **Smart Multi-Tab Coordination**: Prevents double-counting and timer exploitation when users have multiple browser tabs open simultaneously.
* **Guest & Anonymous Visitor Limits**: Issue secure first-party visitor tokens to enforce browsing quotas even for non-logged-in and incognito visitors.
* **Role-Based Time Limits**: Configure distinct allowances per user role (e.g., 30 mins for Subscribers, 120 mins for Authors, Unlimited for Administrators).
* **Smooth Live Countdown**: Configurable floating or fixed widget displays remaining time smoothly without hammering your server.
* **Customizable Warning Banners**: Warn users before their time runs out (e.g., at 5 minutes remaining).
* **Modern Expiration Screen**: When the daily quota is exhausted, users see a sleek blocking screen informing them when access resets (or redirect them to a custom upgrade URL).
* **Automatic Daily Resets**: Quotas reset automatically every day at midnight based on your WordPress timezone—no dependency on WP-Cron reliability.
* **Excluded Pages**: Whitelist critical pages (login, registration, checkout, account, contact) from quota restrictions.
* **Real-time Admin Dashboard**: View total tracked users today, currently active users, total site usage time, and top users.
* **Zero External Dependencies**: 100% self-hosted within your WordPress database. No external APIs, third-party tracking, or analytics services required.

== Installation ==

1. Upload the `timequota-user-time-limits` folder to the `/wp-content/plugins/` directory, or install the ZIP file via **Plugins → Add New → Upload Plugin**.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Navigate to **Settings → TimeQuota** to configure your daily time limits, role rules, and expiration behavior.

== Frequently Asked Questions ==

= How does TimeQuota detect if a user is active? =
TimeQuota monitors Page Visibility events, browser focus, and user interaction (mouse moves, scrolling, keyboard input). If the tab is hidden, blurred, or idle for longer than the configured timeout (default 60 seconds), the countdown pauses automatically.

= Can users cheat the timer by modifying JavaScript? =
No. The frontend timer is purely visual. The server receives lightweight heartbeat requests, validates time deltas, and maintains the authoritative database record. If a user tampers with the JavaScript timer, the server will still reject access and block the page upon reaching the quota.

= What happens if a user opens multiple tabs? =
TimeQuota synchronizes tab state locally. Only the tab currently active in the foreground increments time and sends heartbeats. Opening 3 tabs simultaneously will not consume 3x the quota or give the user extra time.

= Does TimeQuota support guest and incognito visitors? =
Yes. TimeQuota issues a secure first-party cookie token to track active browsing time for anonymous visitors and enforces daily guest quotas configured in settings.

= How do daily resets work? =
Usage is logged against the calendar date according to your WordPress site's configured timezone (`wp_date('Y-m-d')`). When the date changes at midnight, the user's used seconds for that new date start at 0, instantly resetting their daily quota.

= Are administrators blocked when their time expires? =
By default, Administrators are set to Unlimited (0 minutes), meaning they are never blocked. You can customize limits for any role under **Settings → TimeQuota → User Roles & Guests**.

== Screenshots ==

1. **Admin Dashboard**: Live statistics of tracked users, active sessions, and top active users.
2. **General Settings**: Daily quota limits, heartbeat intervals, and inactivity timeouts.
3. **Role & Guest Limits**: Granular time allowances per WordPress user role and guest visitors.
4. **Floating Countdown Widget**: Sleek frontend timer with active pulsing indicator.
5. **Expiration Screen**: Modern glassmorphism blocking screen displayed when daily time runs out.

== Changelog ==

= 1.1.0 =
* Added Guest / Anonymous visitor active time tracking with cookie-based identification.
* Configurable daily guest browsing quotas in settings.
* Improved database migration and safe auto-upgrades.
* Updated compatibility for latest WordPress releases.

= 1.0.0 =
* Initial release of TimeQuota.
* Active browsing time tracking with Page Visibility and activity listeners.
* Role-based time quotas and automatic daily resets.
* REST API heartbeat synchronization with anti-tamper server validation.
* Multi-tab coordination via localStorage.
* Configurable floating countdown widget and warning notifications.
* Customizable blocking screen and redirect options.
* Admin dashboard with real-time site usage statistics.

== Support & Credits ==

If you find this plugin helpful, consider supporting its development with a donation.

[Buy Me a Coffee](https://buymeacoffee.com/iksopnil)

Developed by [RoarDev](https://roardev.xyz/)
