site-agent-pro 1.0.9 → 1.0.12

package/README.md

@@ -427,7 +427,7 @@ If you specifically need to test how a dApp interacts with the MetaMask UI, you
 The agent has built-in support for the Paystack API (Nigeria) to handle Naira payments and payouts. This enables "Agent-as-a-Service" monetization flows.
 
 ### Features
-- **Dedicated Virtual Accounts (DVA):** Automatically provisions a unique bank account number (Wema/GTB) for each agent persona.
+- **Dedicated Virtual Accounts (DVA):** Provisions or reuses a real Nigerian bank account number (Wema/GTB) for the agent to receive payments.
 - **Naira Transfers:** Initiates outbound transfers to any Nigerian bank account via the Transfers API.
 - **Webhook Processing:** Securely handles `charge.success` and `transfer.success` events with HMAC-SHA512 verification.
 - **Zero-Dependency Client:** Uses Node 20+ native `fetch` (no `axios` required).
@@ -435,26 +435,65 @@ The agent has built-in support for the Paystack API (Nigeria) to handle Naira pa
 ### Quick Setup
 Configure Paystack in `.env`:
 ```bash
-PAYSTACK_SECRET_KEY=sk_test_...
-PAYSTACK_PUBLIC_KEY=pk_test_...
+PAYSTACK_SECRET_KEY=sk_live_...
+PAYSTACK_PUBLIC_KEY=pk_live_...
 PAYSTACK_DVA_PROVIDER=wema-bank
-PAYSTACK_AGENT_PHONE=+234...  # Required for Live DVAs
+PAYSTACK_AGENT_EMAIL=agent@example.com   # Email of the Paystack customer that holds the DVA
+PAYSTACK_AGENT_FIRST_NAME=Site
+PAYSTACK_AGENT_LAST_NAME=Agent
+PAYSTACK_AGENT_PHONE=+234...             # Required for Live DVA creation
+PAYSTACK_TRANSFER_ENABLED=false          # Set to true only when ready for real transfers
+```
+
+### Reusing an Existing DVA (Recommended for Live Keys)
+
+On startup, `getAgentAccount()` looks up the customer by `PAYSTACK_AGENT_EMAIL` first. If that customer already has a DVA on your Paystack account, it is returned immediately — **no new DVA is created**. This means you can point the agent at any existing Paystack customer and reuse their bank account number without provisioning anything new.
+
+To find your existing DVAs:
+```bash
+source .env && curl -s \
+  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
+  "https://api.paystack.co/dedicated_account" | python3 -m json.tool
+```
+
+Then set `PAYSTACK_AGENT_EMAIL` to the email of whichever customer owns the DVA you want to use.
+
+### Settlement Timing & Balance
+
+> **Important:** DVA receipts (money sent to the virtual account number) are **not immediately spendable**. Paystack settles DVA payments to your Paystack balance on a **T+1 business day** schedule.
+
+Two funding strategies:
+
+| Strategy | Receiving Account | Spend Delay |
+|---|---|---|
+| **DVA receipts** | Share the DVA account number | T+1 business day |
+| **Pre-fund balance** | Fund via Paystack Dashboard → Fund Balance | Available immediately |
+
+The agent's outbound transfers always draw from the **Paystack balance** (`source: 'balance'`), not the DVA directly. If you pre-fund the balance via the dashboard, the agent can spend immediately without waiting for settlement.
+
+To check your current spendable balance:
+```bash
+source .env && curl -s \
+  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
+  "https://api.paystack.co/balance" | python3 -m json.tool
 ```
 
 ### Autonomous Transfers & Verification
 The agent can autonomously fulfill payment requests and **verify incoming funds or tokens** using its direct API/on-chain access:
-- **Sending Naira**: When it encounters a task like "Pay the vendor ₦500," it extracts the bank details from the page and initiates a transfer using the `pay` action.
+- **Sending Naira**: When it encounters a task like "Pay the vendor ₦500," it extracts the bank details from the page and initiates a transfer using the `pay` action with format `amount:bankCode:accountNumber` (e.g. `5000:058:0123456789`).
 - **Verifying Naira**: If tasked to "wait for payment before releasing tokens," the agent monitors its own Paystack transaction history. It will only proceed to click "Release" or "Confirm" once it sees the matching successful transaction in its account.
 - **Verifying Tokens**: If tasked to "confirm tokens have arrived before paying Naira," the agent monitors its actual on-chain wallet balance via its RPC connection. It ignores potentially fake website UIs and only pays once the blockchain confirms the receipt of funds.
 
 **Safety:** Transfers are only broadcast if `PAYSTACK_TRANSFER_ENABLED=true`. Otherwise, it performs a dry-run validation.
 
 ### Testing the Integration
-Run the standalone smoke test to verify your API keys and DVA provisioning:
+Run the standalone smoke test to verify your API keys and DVA connectivity:
 ```bash
 npm run paystack:test
 ```
 
+> **Note on live keys:** The smoke test's step 5 (transfer) uses a placeholder account number. On live keys, Paystack validates that the account exists at the specified bank — the test will fail at step 5 unless you replace `0123456789` with a real account. Steps 1–4 (environment, DVA, bank list, bank code resolution) are the meaningful validation checks.
+
 ---
 
 

package/dist/paystack/types.js

@@ -28,7 +28,8 @@ export const PaystackDVASchema = z.object({
     bank: PaystackBankSchema,
     customer: PaystackCustomerSchema,
     active: z.boolean(),
-    createdAt: z.string(),
+    createdAt: z.string().optional(), // returned by POST /dedicated_account
+    created_at: z.string().optional(), // returned by GET /dedicated_account (list)
 });
 // ─── Transfer Recipient ───────────────────────────────────────────────────────
 export const PaystackRecipientSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "site-agent-pro",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "type": "module",
   "description": "AI-powered browser agent that tests websites like a real user and produces evidence-based, scored reports.",
   "bin": {
@@ -17,6 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "postbuild": "chmod +x dist/bin.js",
     "prepublishOnly": "npm run build",
     "check": "tsc --noEmit -p tsconfig.json",
     "start": "node dist/cli/run.js",