Wallet integration

When a wallet plugin is active, the assistant can read a signed-in shopper's real store credit, shop within that balance, and share their real referral link. WalletPro ships the adapter that connects it, so the assistant talks to the wallet ledger without ever depending on it directly.

How the connection works

The assistant core never hard-depends on any wallet plugin. Instead it resolves a provider adapter at runtime through a WordPress filter, fahad_ai_wallet_provider. The wallet plugin owns the money ledger; the assistant ships the tools that talk to it. Either side can change independently.

WalletPro registers its adapter on that filter, so on a store running WalletPro the integration is automatic with no glue code to write:

add_filter( 'fahad_ai_wallet_provider', fn() => new My_WalletPro_Adapter() );

The adapter is an object (or an array of callables) that exposes a small contract: read the balance, quote a deposit bonus, add funds, charge credit, and return referral details. Every amount is a float in the store currency. Anything the wallet cannot service is returned as an error, never thrown, so a failure is always a clean no-op on the assistant's side.

The wallet tools

The assistant adds four tools the model can call. They are always registered, so the model can answer honestly whether or not a wallet is present:

• get_wallet_balance reads the signed-in customer's current balance and returns the amount, currency, and a display-formatted figure.
• top_up adds funds by a stated amount and returns the new balance. If the store offers a deposit bonus for that amount, it is included so the model can mention it factually, never as pressure.
• pay_with_credit charges the wallet for an order or cart. The balance is checked first; if it cannot cover the amount the payment is refused and nothing is charged.
• get_referral_link returns the customer's real referral code, share link, and reward terms so the assistant can help them refer a friend.

Grounded, never from memory

The assistant treats the wallet the same way it treats every other store fact: it reports only what the tool returns. It will not state a balance, claim a customer has credit, or invent a referral code from memory. When a shopper asks about their balance, the model calls get_wallet_balance and reports only the amount it gets back.

Shopping within the balance

When a shopper asks to find something within their credit, for example "what can I get with my balance?", the assistant first reads the real balance, then passes that figure as max_price to product search. Every option it returns stays within the balance. It will not propose an item priced above the balance unless the shopper chooses to top up first.

1. get_wallet_balance        -> { amount: 50.00, currency: "USD", formatted: "$50.00" }
2. search_products           -> { max_price: 50.00, ... }   only items the credit covers

Referrals, with real data

Ask the assistant how to refer a friend and it calls get_referral_link, then shares only the real code, link, and reward amounts the wallet returns. The shape is straightforward:

{ "enabled": true, "code": "...", "url": "...", "referrer_reward": "...", "referee_reward": "..." }

If the wallet reports the programme is disabled, the assistant tells the shopper the store has no referral programme right now, rather than inventing one.

No wallet? It degrades gracefully

On a store with no wallet provider, the tools still exist but return a clear, single message: the wallet is not available on this store. Nothing is fatal, and no balance is ever invented. The model can then explain honestly that the store has no wallet, instead of the capability silently vanishing.