Athenian Credits Manager

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

Technical Architecture

Bootstrap Flow

The main plugin file performs the following sequence:

1. Defines constants for plugin file, directory, URL, version, and database version.
2. Loads plugin translations.
3. Checks for WooCommerce and shows an admin notice when WooCommerce is inactive.
4. Requires the core include files after WooCommerce is present.
5. Runs database upgrade checks.
6. Initializes core singletons for credits, dashboard, admin, and products.
7. Registers ASU person-score integration hooks.
8. Registers legacy shortcode sinks for removed buybox shortcodes.
9. Registers activation, deactivation, uninstall, and REST routes.

Main Classes and Responsibilities

| Class / File | Responsibility | | --- | --- | | CPM_Credits | Authoritative ledger, balance API, DB install/upgrade, WooCommerce award/reversal hooks, reservations, transfers, cashouts, balance AJAX, WP-CLI reconciliation. | | CPM_Admin | WooCommerce admin submenu, settings fields, user search, ledger filters, manual adjustments, reconciliation, transfer/cashout actions, bulk cleanup/testing tools. | | CPM_Products | Product/variation credit-pack settings, credit-pack discovery, custom credit cart item data, dynamic cart prices, order-item meta, quick-buy AJAX. | | CPM_Account_Endpoint | WooCommerce My Account credits endpoint, account dashboard, transaction pagination, credit top-up panel. | | CPM_Dashboard | [cpm_credit_dashboard] shortcode, dashboard assets, AJAX transaction pagination. | | CPM_Transaction_View | Normalizes ledger rows and renders badges, deltas, and expandable transaction details. | | CPM_Action_Rewards | Registration/Google signup reward events, settings UI, programmatic reward triggers. | | CPM_User_Profile | Adds credit balance, recent history, and manual adjustments to WordPress user profile screens. | | CPM_AI_Usage_Pricing | Centralized AI usage credit quote engine for image and chat capabilities. | | CPM_Product_Shadow | Embedded product/add-to-cart panel shortcode. | | CPM_Tier_Fetch | Best-effort tier-pricing rule discovery and debug output. | | helpers.php | Public helper functions for charging, granting, logging, reserving, transferring, cashing out, and quoting credits. |

Database Model

The plugin creates a custom table named:

{$wpdb->prefix}cpm_credits

Important columns include:

| Column | Purpose | | --- | --- | | id | Primary key. | | user_id | User whose balance or credit history is affected. | | delta | Positive, negative, or zero credit movement. | | type | Transaction/event type such as purchase, usage, refund, transfer, cashout, reservation. | | status | Normalized transaction status. | | context | Workflow-specific context label. | | related_id | General related object/request/order reference. | | order_id | WooCommerce order ID when relevant. | | product_id | Product or variation context when relevant. | | source | Source subsystem, such as purchase, refund, admin, transfer, cashout, or rest. | | event_key | Optional unique idempotency key. | | note | Human-readable ledger note. | | prompt | Prompt/request text for AI or creative workflows. | | image_url | Generated image/media reference. | | attachments_json | JSON payload of normalized attachment references. | | meta_json | Rich structured metadata. | | failure_code | Failure identifier when applicable. | | failure_message | Failure explanation when applicable. | | created_by | User/admin/system actor ID. | | created_at | Ledger timestamp. |

Indexes are created for user_id, related_id, order_id, product_id, type, status, created_at, and a unique event_key.

User Meta

The ledger is authoritative, while user meta stores fast-access cached balance data.

| Meta Key | Purpose | | --- | --- | | _cpm_credit_balance | Cached current credit balance. | | _cpm_credit_reserved | Credits reserved for pending settlement or workflow locks. | | _cpm_awarded_register | Standard registration reward already granted flag. | | _cpm_awarded_register_google | Google registration reward already granted flag. |

Product and Order Item Meta

| Meta Key | Surface | Purpose | | --- | --- | --- | | _cpm_is_credit_pack | Product / variation | Marks a product or variation as a credit pack. | | _cpm_credit_amount | Product / variation | Credits granted per unit. | | _cpm_custom_credit_amount | Order item | Custom top-up credit quantity purchased. | | _cpm_custom_credit_price | Order item | Custom top-up price calculated from credits-per-USD. | | _cpm_credits_processed | Order | Prevents duplicate order-credit awards. |

Settings / Options

| Option | Purpose | | --- | --- | | cpm_credit_pack_products | Optional comma-separated product IDs used as credit-pack products. | | cpm_main_credits_product_id | Primary credits product used for deriving credit-to-USD baseline. | | cpm_credit_unit_label | User-facing label for credits/tokens. | | cpm_credits_per_usd | Fallback conversion rate when product-derived baseline is unavailable. | | cpm_credit_transfers_enabled | Enables or disables self-service transfer REST behavior. |

> Source reference excerpt truncated; use the linked technical reference and repository baseline for the full implementation context.

Workflow Overview

Customer Purchase Workflow

1. Merchant marks a WooCommerce product or variation as a credit pack.
2. Customer purchases that product through WooCommerce.
3. When the order reaches processing or completed status, CPM checks each item.
4. CPM calculates credits from custom top-up metadata, variation meta, or parent product meta.
5. CPM records a purchase transaction using an idempotent event key.
6. The user’s cached balance is atomically incremented.
7. The customer can view the new balance and transaction history from My Account.

Refund / Cancellation Workflow

1. WooCommerce records a refund or cancellation.
2. CPM inspects refunded or cancelled items.
3. CPM calculates the original credit amount for the relevant item.
4. CPM records a negative ledger entry with refund or cancel type.
5. The cached user balance is atomically reduced.
6. The ledger preserves the reversal context for support and reconciliation.

AI Usage Workflow

1. A feature plugin requests a quote using cpm_quote_ai_usage().
2. The feature plugin confirms available balance using CPM helpers.
3. The feature plugin charges credits with cpm_charge_credits().
4. CPM deducts the credits and logs request metadata such as prompt, provider, model, media, files, and status.
5. If a request fails, the feature plugin can use cpm_log_credit_failure() to preserve failure context without changing the balance.
6. Customers and admins can inspect the details through dashboard/account/admin transaction views.

Reward Workflow

1. A new user registers through WordPress, WooCommerce, or Google/social sign-on.
2. CPM checks configured reward events.
3. If the event is enabled and not already awarded for that user, CPM grants the configured credits.
4. The award is recorded in the ledger with reward-specific type, source, context, note, and once-per-user meta.

Cashout Workflow

1. Cashout is enabled in CPM settings.
2. User or integration requests a cashout amount.
3. CPM validates available balance and minimum threshold.
4. CPM calculates gross amount, fee percentage, fee amount, and net amount.
5. CPM deducts credits and builds an OwlPay-style ledger credit payload.
6. CPM attempts to bridge into OwlPay through the OwlPay plugin instance or action hook.
7. If OwlPay crediting fails, CPM reverses the cashout deduction.
8. If successful, CPM fires cpm_credit_cashout_requested for downstream integrations.

Athenian Platform Integration Story

Athenian Social Users Core

The plugin publishes sanitized credit signals into ASU Core scoring. It adds a credit_pack_manager snapshot containing balance, reserved credits, available credits, purchase counts, refund counts, usage counts, failed counts, transfer counts, and cashout counts. It also adds badges such as credit_pack_customer, credits_available, and credit_cashout_history where appropriate.

OwlPay

CPM includes direct cashout integration logic for the Athenian OwlPay plugin. When a credit cashout succeeds, CPM can create/credit an OwlPay ledger payload for the relevant user/payee. The payout REST route also attempts to surface OwlPay payee, available balance, ledger, and payout information.

AI and Media Plugins

The helper functions and AI usage quote engine make CPM suitable as the credit layer behind Athenian AI tools such as image generation, product builders, video workflows, chat tools, or custom media request systems.

Swap / Marketplace Workflows

The account top-up flow supports contextual parameters such as cpm_required_credits, ath_swap_id, and return_to, indicating that CPM is intended to support marketplace or Swap checkout flows where a customer may need to add credits before continuing.

Technical Review Checklist

Before publishing or deploying this plugin broadly, review the following:

• Confirm WooCommerce HPOS behavior for order meta and refund/cancellation hooks.
• Confirm whether the legacy buybox shortcodes should remain silent or be replaced by a current embedded purchase experience.
• Confirm which frontend surface should own the quick-buy asset.
• Confirm whether cashout should create a pending request first or immediately deduct credits and bridge to OwlPay.
• Confirm whether uninstall should drop the ledger table in production environments or preserve data behind an explicit setting.
• Confirm exact AI usage pricing assumptions against current provider pricing before treating credit quotes as billable production logic.
• Confirm customer-facing transfer and cashout UX if the REST routes are enabled.
• Confirm privacy policy language for stored prompts, media references, attachments, failure messages, and usage metadata.