=== Recast Paywall ===
Contributors: recastplugin
Tags: paywall, content-gating, premium-content, monetization, micropayments
Requires at least: 6.2
Tested up to: 6.8
Requires PHP: 8.0
Stable tag: 0.0.30
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Integrates RecastPay to monetize your content. Features automatic content synchronization and theme customization options.

== Description ==

Transform your WordPress site into a premium content platform with Recast Paywall - a flexible paywall solution for WordPress.

### Themeable Design
* Custom paywalls with theme integration support
* Responsive design that works on all devices
* Dark mode support
* Smooth animations and hover effects
* Theme customization via WordPress hooks and filters

### Content Gating
* Post-level gating - Gate entire posts
* Block-level gating - Gate individual blocks
* Toolbar integration - Easy toggle controls in the block editor toolbar
* Excerpt-based previews - Paywalls display post excerpts as preview text
* Automatic content synchronization with Recast inventory
* Real-time pricing display from your Recast dashboard

### User Experience
* Login-first flow - Users must log in before purchasing (WordPress authentication)
* Seamless purchase process with immediate content access
* Status indicators showing availability (Pre-sale, Available, Coming Soon)
* One-click purchase with automatic content reveal
* Progressive enhancement for optimal performance

### Developer & Theme Integration
* HTML customization via WordPress filters
* CSS framework with modern design patterns
* JavaScript hooks for custom purchase flows
* REST API for custom integrations
* WP-CLI support for command-line management
* Logging for troubleshooting

### Performance & Reliability
* Smart caching - Entitlement decisions cached for 5 minutes
* Memory optimization - Efficient processing for large sites
* Webhook support - Real-time updates from Recast
* Multisite ready - Works with WordPress multisite installations
* Security focused - API secrets never exposed, proper nonces, XSS protection

### Dual Editor Support
* Classic Editor - Meta box integration for traditional workflows
* Block Editor (Gutenberg) - Native block support with Document Settings
* Toolbar Integration - Easy toggle controls for block-level gating
* Shortcode support - Easy integration with any theme
* Custom blocks - Dedicated Recast Paywall blocks

### Modern Web Standards
* Mobile-first responsive design
* Accessibility compliant (WCAG guidelines)
* Keyboard navigation support
* Screen reader friendly
* Modern CSS with fallbacks

## Use Cases:
* Content creators looking to monetize premium articles
* News sites wanting to gate exclusive content
* Educational platforms selling courses and tutorials
* Membership sites with tiered access levels
* Theme developers needing customizable paywall solutions
* Agencies building premium content sites for clients  

== Frequently Asked Questions ==

= What is Recast Paywall? =

Recast Paywall is a WordPress plugin that integrates with RecastPay to monetize your content. It allows you to gate posts or individual blocks behind paywalls.

= What are the system requirements? =

* WordPress 6.2 or higher
* PHP 8.0 or higher
* Recast account with API credentials
* Modern web browser with JavaScript enabled

= How do I set up the plugin? =

1. Install and activate the plugin
2. Go to Settings > Recast Paywall
3. Enter your Recast API credentials (API Key, API Secret, Brand ID)
4. Configure your content settings
5. Start creating premium content!

= What are the different gating modes? =

**Post-Level Gating**: Gates the entire post content behind a paywall
**Block-Level Gating**: Allows selective gating of individual blocks within a post using the toolbar

= How do I customize the paywall appearance? =

The plugin provides extensive customization options via WordPress hooks and filters. You can customize HTML, CSS, and JavaScript to match your theme's design.

= Is the plugin compatible with my theme? =

Yes! The plugin is designed to work with any WordPress theme and provides comprehensive customization options for seamless integration.

= Does it work with multisite? =

Yes, the plugin is fully compatible with WordPress multisite installations.

= How do I handle user authentication? =

The plugin uses WordPress's built-in authentication system. Users must log in to your WordPress site before they can purchase content.

= Can I customize the purchase flow? =

Yes, the plugin provides JavaScript hooks and REST API endpoints for customizing the purchase flow to match your needs.

= Is the plugin secure? =

Yes, the plugin follows WordPress security best practices including proper nonces, input sanitization, and API secret protection.

== External Services ==

This plugin connects to the Recast API service to manage content monetization, inventory synchronization, and user entitlements. The Recast API is essential for the plugin's core functionality.

Sandbox keys are obtained via: http://business.recast-sandbox.tv/api-register

To setup a production Recast Merchant Account and obtain API keys, visit: http://business.recast.tv/api-register

### Recast API Service

**Service Provider**: Recast (recastpay.com)

**Production API**: `https://api.recast.tv/api/v0`  
**Sandbox API**: `https://api.recast-sandbox.tv/api/v0` (used when sandbox mode is enabled in settings)

**What the service is used for:**
* Managing content inventory - Syncing WordPress posts as products in Recast inventory
* Checking user entitlements - Verifying if users have purchased access to premium content
* Creating purchase intents - Initiating purchase flows for users to buy premium content
* Receiving webhooks - Processing real-time updates about entitlements and inventory changes

**What data is sent and when:**

* **API Credentials** (API Key, API Secret, Brand ID)
  * Sent: When authenticating API requests (used to generate JWT tokens)
  * When: On every API request after initial authentication
  * Stored: Only in WordPress database (never exposed to frontend)

* **User Identification Data** (WordPress User IDs, mapped to external user IDs)
  * Sent: When checking if a user has access to premium content
  * When: Every time a user views a paywalled post (if not cached)
  * Purpose: To verify purchase entitlements

* **Product/Post Data** (Post titles, descriptions, IDs, pricing, status, geographic availability)
  * Sent: When posts are published or updated in WordPress
  * When: Automatically when posts are saved if paywall is enabled
  * Purpose: To synchronize WordPress content with Recast inventory

* **Purchase Intent Data** (User ID, Product ID, optional pricing details)
  * Sent: When a user initiates a purchase of premium content
  * When: When the purchase button is clicked on a paywall
  * Purpose: To create purchase intents in the Recast system

* **Webhook Receipt** (Entitlement and inventory event data)
  * Received: When events occur in Recast (entitlements created/updated, products updated)
  * When: Real-time when webhooks are configured
  * Purpose: To keep WordPress in sync with Recast system state

**Links to Service Policies:**
* Merchant Terms of Service: https://recastpay.com/vendor-terms-and-conditions
* User Terms and Conditions: https://recastpay.com/terms-and-conditions 
* Privacy Policy: https://recastpay.com/privacy-policy

**Note**: All API communications use HTTPS encryption. API secrets are stored securely in your WordPress database and are never exposed to the frontend or transmitted in a way that could be intercepted.

== Screenshots ==

1. Plugin settings pages
2. Post paywall settings
3. Post-level paywall example 
4. Block-level gating with toolbar integration
5. Block-level paywall example

== Changelog ==

= 0.1.0 =
* Initial release
* Completely themeable paywall system
* Recast API integration
* Medium-style post paywalls
* Gutenberg block-level paywalls
* Login-first user flow
* Real-time pricing display from Recast Inventory
* Comprehensive theme customization hooks
* Toolbar integration for block-level gating
* Webhook handling (alpha)

== Installation ==

### 1. API Setup

1. Log in to your [RecastPay Dashboard](https://business.recast.tv)
2. Navigate to **API Settings**
3. Copy your **API Key**, **API Secret** and **Brand ID**
4. In WordPress, go to **Settings > Recast Paywall**
5. Enter your credentials and save

### 2. Content Settings

* **Show Teaser to Search Engines**: Allow search engines to see full content (use carefully)
* **Archive on Delete**: Archive Recast inventory items when posts are deleted

**Note**: Paywalls always display the WordPress post excerpt as the preview text. Set the excerpt in the post editor to control what visitors see before purchasing.

### 3. Webhook Setup (Alpha)

1. In your Recast Dashboard, go to **Webhooks**
2. Add a new webhook with the URL: `https://yoursite.com/?recast_webhook=1`
3. Select the events you want to receive (entitlement and inventory events)
4. Save the webhook

== Usage ==

### Content Gating Modes

The plugin supports two gating modes that can be toggled per post:

#### **Post-Level Gating (Default)**
* Gates the entire post content behind a paywall
* Shows a beautiful Medium.com-style paywall with post excerpt
* Best for premium articles and exclusive content
* **Preview Text**: Uses the post excerpt (set in post editor sidebar)

#### **Block-Level Gating**
* Allows selective gating of individual blocks within a post
* Provides more granular control over what content is premium
* Perfect for mixed free/premium content strategies

### Setting Up Content Gating

#### 1. Choose Your Gating Mode

1. Create or edit a post
2. In the **Document Settings** panel (Block Editor) or **"Recast Paywall"** meta box (Classic Editor)
3. Select your gating mode:
   * **"Post"** - Gate the entire post (default)
   * **"Block"** - Enable block-level gating
4. Save and Publish the post - it will automatically sync with Recast

#### 2. Post-Level Gating

When using **Post** mode:
* The entire post content is gated behind a paywall
* Users see the post excerpt and purchase options
* On archive/list pages, only the excerpt is shown (no content leak)
* **Tip**: Set a compelling excerpt to encourage purchases!

#### 3. Block-Level Gating

When using **Block** mode:
* Individual blocks can be marked for gating using the block's toolbar
* Users see full content except for gated blocks
* Gated blocks show streamlined paywall sections

### Block-Level Gating with Toolbar Integration

#### Using the Block Toolbar

1. **Enable Block Mode**: Set the post gating mode to **"Block"** in Document Settings
2. **Select a Block**: Click on any block in the editor
3. **Access the Toolbar**: Look for the **"Recast Paywall"** toggle in the block toolbar
4. **Toggle Gating**: Click the toggle to mark/unmark the block for gating
5. **Visual Indicator**: Gated blocks show a paywall icon in the editor

#### Supported Block Types

Block-level gating works with most Gutenberg blocks:
* Paragraphs
* Headings
* Images
* Videos
* Lists
* Custom blocks
* And more!
