=== apLedger — QuickBooks Online for WordPress ===
Contributors: artistpro
Tags: quickbooks, qbo, sync, invoices, accounting, woocommerce, stripe
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The complete WordPress ↔ QuickBooks Online sync engine. Core + Console + Connector Framework.

== Description ==

apLedger is a complete QuickBooks Online sync engine for WordPress: a local accounting console plus a connector framework for your commerce and payment data.

**Three layers that work together:**

1. **Core Engine** — OAuth 2.0, local mirror tables, job locking, CDC sync, audit log
2. **Built-in Console** — View/edit customers, invoices, payments directly in WordPress
3. **Connector Framework** — Easy buttons for WooCommerce, Stripe, forms, and any webhook

**Requirements:** WordPress 6.0 or newer and PHP 7.4 or newer.

**Database:** Nine purpose-built tables for customers, invoices, payments, items, audit history, locking, external links, recipes, and recipe runs.

**Why this plugin exists:** Every other WordPress-to-QuickBooks integration requires middleware fees, breaks under load, or creates duplicates. We built this for reliability-first accounting sync.

= Core Engine Features =

* **Guided OAuth 2.0** — Sign in with your normal QuickBooks email; no Intuit developer account or app credentials
* **Local Mirror (Truth Store)** — Customers, invoices, payments, items stored locally
* **Change Data Capture** — Only syncs records that changed (30-minute polling)
* **Sync Locking** — Prevents concurrent syncs and race conditions
* **Conflict Detection** — Detects when local and QBO data both changed
* **Dry-Run Mode** — Preview what would sync before committing
* **Hash-Based Change Detection** — Knows exactly which local records changed
* **Full Audit Log** — Every sync action logged with before/after data
* **Rate Limit Protection** — Automatic 30-minute backoff on 429 responses

= Built-in Console =

* **Health Dashboard** — System status, sync stats, issue alerts
* **Customers List** — Search, filter, export, push to QBO
* **Invoices List** — Payment status, overdue tracking, sync status
* **Payments List** — Received payments with unapplied tracking
* **Conflict Resolution** — Choose local or QBO when data conflicts

= Connector Framework =

* **REST API Webhook Intake** — Any system can POST to create customers/invoices/payments
* **WooCommerce Connector** — Order → Sales Receipt, Refund → Credit Memo
* **Stripe Connector** — Payment Intent → Sales Receipt (direct, non-WooCommerce)
* **Recipe System** — Trigger → Map → Action → Conditions
* **Duplicate Prevention** — Links table tracks what's already synced
* **Field Mapping** — Flexible dot-notation mapping with transforms

= Supported QBO Entities =

* Customers (bidirectional)
* Invoices (bidirectional)
* Payments (bidirectional)
* Items/Products (pull from QBO)


= What This Plugin Handles (v1.1) =

**✅ Fully Supported:**
* Full payments (complete invoice payment)
* Partial payments (displayed with balance remaining)
* Customer sync (bidirectional with email matching)
* Invoice sync (bidirectional with status tracking)
* Payment sync (bidirectional)
* WooCommerce orders → Sales Receipts
* WooCommerce refunds → Credit Memos
* Stripe payments → Sales Receipts
* Conflict detection with manual resolution

**⚠️ Partial Support:**
* Unapplied payments (synced, link manually in QBO)
* Refunds (WooCommerce only in v1.1, Stripe planned v1.2)

**❌ Not Yet Supported (Roadmap for v2.0):**
* Write-offs / Bad debt (handle manually in QuickBooks)
* Multi-currency transactions
* Class tracking
* Department tracking
* Location tracking
* Real-time webhooks from QuickBooks (polling only)

**Why we list exclusions:** We believe in transparency. If you need write-offs or multi-currency, handle those in QuickBooks directly. Our sync handles the 95% use case reliably.

= Sync Reliability =

**Observed in production:** up to 10,000 records/day (varies by host and QBO limits)

**Sync Methods:**
1. **WP-Cron (Default)** — Works out of the box, checks every 30 minutes
2. **Action Scheduler (Recommended)** — Auto-detects if installed, more reliable under load
3. **Server Cron (Optional)** — For mission-critical reliability, add to your server:
   ```
   */30 * * * * (copy the exact cron command from apLedger → Health)
   ```

**Duplicate Prevention:**
* Email-based matching links existing customers automatically
* Links table prevents creating duplicates
* Sync log shows exactly what was created vs. linked

= For Developers =

Register custom entity mappings:

`add_action( 'artistpro_qbo_loaded', function() {
    ArtistPro_QBO_Entity_Mapper::register( 'Customer', [
        'table'  => 'my_contacts',
        'fields' => [
            'DisplayName'              => 'full_name',
            'PrimaryEmailAddr.Address' => 'email',
        ],
    ]);
});`

== Installation ==

1. Upload the apLedger ZIP through Plugins → Add Plugin
2. Activate through the Plugins menu
3. Go to apLedger → Settings and activate the license sent to your purchase email
4. Click "Connect to QuickBooks"
5. Sign in with your normal QuickBooks email, choose your company, and approve access
6. apLedger returns to your WordPress site automatically and begins the initial sync

== Frequently Asked Questions ==

= Do I need WooCommerce? =

No. This plugin works with any WordPress installation.

= How often does it sync? =

The CDC engine checks QuickBooks for changes every 30 minutes automatically. You can also trigger a manual full sync from the dashboard.

= Is my QuickBooks data stored locally? =

Yes, synced data is stored in your WordPress database for fast access. The plugin creates its own tables and does not modify existing WordPress tables.

= Can I map to my own custom tables? =

Yes. Use the `ArtistPro_QBO_Entity_Mapper::register()` function to map QBO entities to any WordPress database table with any field mapping you need.

== Changelog ==

= 2.0.0 =
* Renamed the customer-facing product to apLedger
* Removed the bundled Gemini integration and API key
* Added encrypted AES-256-GCM storage for OAuth tokens and credentials
* Added one-click brokered QuickBooks authorization for arbitrary customer sites
* Added ArtistProWP license activation and automatic commercial updates
* Removed development backups and logs from the distribution
* Removed API-key query-string authentication

= 1.1.0 =
* **Connector Framework** — Base class for building integrations
* **WooCommerce Connector** — Order completed/refunded → QBO
* **Stripe Connector** — Payment webhook → Sales Receipt
* **REST API** — Generic webhook intake at `/wp-json/apqbo/v1/intake`
* **Admin Console** — Health, Customers, Invoices, Payments pages
* **Sync Locking** — Prevents concurrent sync operations
* **Hash-Based Change Detection** — Track local changes accurately
* **Conflict Detection** — Flag records changed both locally and in QBO
* **Dry-Run Mode** — Preview sync operations before committing
* **Enhanced Logging** — Before/after data stored in sync log
* **Items Table** — Products/services catalog from QBO
* **Links Table** — Connect external sources to QBO entities
* **Recipes Table** — Store automation rules
* **Export Feature** — CSV/JSON export of any entity type
* **API Key Authentication** — Secure REST endpoints

= 1.0.0 =
* Initial release
* OAuth 2.0 with proactive token refresh
* CDC-based sync engine
* Batch processing with progress tracking
* Rate limit protection with automatic backoff
* Configurable entity mapping system
* Adapter interface for third-party integrations
* Admin dashboard with sync status
* Default tables for customers, invoices, payments

== Upgrade Notice ==

= 1.1.0 =
Major feature release with connector framework, admin console, and REST API. Database upgrade runs automatically.

= 1.0.0 =
Initial release.
