knowledge/supabase_integration.md

# KB: Supabase Database Integration

The **Supabase Agent** provides the persistence layer for the EbookBuilder ecosystem, managing ebook metadata, sales records, and transaction logs.

## Core Capabilities
- **Metadata Management**: Uses `db_upsert_ebook` to keep track of book titles, authors, status (draft/published), and GCS/HF paths.
- **Sales Intelligence**: Uses `db_get_sales_report` to provide the author with real-time insights into book performance.
- **Audit Logging**: Uses `db_log_transaction` to maintain a secure and immutable record of every payment and generation event.

## Database Schema (Recommended)
1. **ebooks**: `id`, `title`, `author`, `status`, `content_url`, `created_at`
2. **sales**: `id`, `ebook_id`, `amount`, `currency`, `customer_email`, `created_at`
3. **transactions**: `id`, `event_type`, `payload`, `status`, `created_at`

## Workflow Integration
- **Post-Generation**: Automatically upsert ebook metadata after a successful manuscript completion.
- **Post-Sale**: Log the transaction details immediately after a successful Stripe Checkout callback.
- **Reporting**: Query the sales table to generate monthly performance reviews via the Meta Orchestrator.

## Connection
The agent uses the Service Key for administrative access, ensuring it can manage all tables within the `vrspcqzajxupormgqhpe` project.