site-agent-pro 1.0.0

package/dist/index.js

@@ -0,0 +1,84 @@
+/**
+ * site-agent-pro — programmatic API
+ *
+ * Use `runAudit()` for the simplest integration:
+ *
+ * @example
+ * ```ts
+ * import { runAudit } from "site-agent-pro";
+ *
+ * const result = await runAudit({
+ *   url: "http://localhost:3000",
+ *   tasks: [
+ *     "Open the pricing page and note the visible plans",
+ *     "Click the sign-up button and check the form fields",
+ *   ],
+ * });
+ *
+ * console.log(`Score: ${result.report.overall_score}/10`);
+ * console.log(`Report saved to: ${result.runDir}`);
+ *
+ * // Fail CI if quality drops below your threshold
+ * if (result.report.overall_score < 7) {
+ *   process.exit(1);
+ * }
+ * ```
+ *
+ * Use `runAuditJob()` directly for full control over task suites
+ * and internal configuration.
+ */
+import { buildCustomTaskSuite } from "./core/customTaskSuite.js";
+import { runAuditJob } from "./core/runAuditJob.js";
+import { normalizeCustomTasks } from "./submissions/customTasks.js";
+// ─── Public lower-level exports ────────────────────────────────────────────
+export { runAuditJob } from "./core/runAuditJob.js";
+export { buildCustomTaskSuite } from "./core/customTaskSuite.js";
+export { normalizeCustomTasks } from "./submissions/customTasks.js";
+/**
+ * Run an Site Agent Pro audit programmatically against any URL,
+ * including localhost dev servers.
+ *
+ * Returns the full run result including the scored report,
+ * the run directory where artifacts were saved, and the
+ * raw task execution data.
+ *
+ * @example
+ * ```ts
+ * // package.json devDependency usage:
+ * // "site-agent-pro": "^1.0.0"
+ *
+ * import { runAudit } from "site-agent-pro";
+ *
+ * const result = await runAudit({
+ *   url: "http://localhost:3000",
+ *   tasks: ["Check the homepage CTA", "Try the signup flow"],
+ * });
+ *
+ * console.log(`Score: ${result.report.overall_score}/10`);
+ *
+ * // Gate your CI pipeline on audit score
+ * if (result.report.overall_score < 7) {
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export async function runAudit(options) {
+    const normalizedTasks = normalizeCustomTasks(options.tasks);
+    const suite = buildCustomTaskSuite(normalizedTasks);
+    return runAuditJob({
+        baseUrl: options.url,
+        suiteOverride: suite,
+        ...(options.headed !== undefined ? { headed: options.headed } : {}),
+        ...(options.mobile !== undefined ? { mobile: options.mobile } : {}),
+        ...(options.ignoreHttpsErrors !== undefined ? { ignoreHttpsErrors: options.ignoreHttpsErrors } : {}),
+        ...(options.llmProvider !== undefined ? { llmProvider: options.llmProvider } : {}),
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options.ollamaBaseUrl !== undefined ? { ollamaBaseUrl: options.ollamaBaseUrl } : {}),
+        ...(options.runDir !== undefined ? { runDir: options.runDir } : {}),
+        extraInputs: {
+            customTasks: normalizedTasks,
+            instructionText: normalizedTasks.join("\n"),
+            instructionFileName: null,
+        },
+    });
+}

package/dist/llm/client.js

@@ -0,0 +1,188 @@
+import OpenAI from "openai";
+import { toJSONSchema } from "zod";
+import { config, resolveLlmRuntime } from "../config.js";
+function getOpenAIClient() {
+    if (!config.openaiApiKey) {
+        throw new Error("OPENAI_API_KEY is required when the selected LLM provider is openai.");
+    }
+    return new OpenAI({
+        apiKey: config.openaiApiKey,
+        ...(config.openaiBaseUrl ? { baseURL: config.openaiBaseUrl } : {})
+    });
+}
+function cleanErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.replace(/\u001b\[[0-9;]*m/g, "").replace(/\s+/g, " ").trim() || "Unknown LLM error";
+}
+function stripJsonCodeFence(value) {
+    const trimmed = value.trim();
+    const fencedMatch = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+    return fencedMatch?.[1]?.trim() ?? trimmed;
+}
+async function generateWithOpenAI(options) {
+    const response = await getOpenAIClient().chat.completions.create({
+        model: options.model,
+        messages: [
+            { role: "system", content: options.systemPrompt },
+            {
+                role: "user",
+                content: JSON.stringify(options.userPayload, null, 2)
+            }
+        ],
+        response_format: {
+            type: "json_schema",
+            json_schema: {
+                name: options.schemaName,
+                schema: toJSONSchema(options.schema)
+            }
+        },
+        ...(config.openaiTemperature !== undefined ? { temperature: config.openaiTemperature } : {}),
+        ...(config.openaiMaxTokens !== undefined ? { max_tokens: config.openaiMaxTokens } : {})
+    }, {
+        ...(options.timeoutMs !== undefined ? { timeout: options.timeoutMs } : {}),
+        ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {})
+    });
+    const rawContent = response.choices[0]?.message?.content?.trim() ?? "";
+    if (!rawContent) {
+        throw new Error("OpenAI-compatible API returned an empty message content.");
+    }
+    return options.schema.parse(JSON.parse(stripJsonCodeFence(rawContent)));
+}
+const ollamaReachableCache = new Map();
+async function ensureOllamaReachable(baseUrl) {
+    if (ollamaReachableCache.has(baseUrl)) {
+        return;
+    }
+    try {
+        const response = await fetch(new URL("/api/tags", baseUrl), {
+            method: "GET",
+            signal: AbortSignal.timeout(5000)
+        });
+        if (!response.ok) {
+            throw new Error(`Ollama server at ${baseUrl} returned ${response.status} ${response.statusText}. ` +
+                `Make sure Ollama is running — start it with: ollama serve`);
+        }
+        ollamaReachableCache.set(baseUrl, true);
+    }
+    catch (error) {
+        if (error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) {
+            throw new Error(`Ollama server at ${baseUrl} did not respond within 5 seconds. ` +
+                `Make sure Ollama is running — start it with: ollama serve`);
+        }
+        if (error instanceof TypeError || (error instanceof Error && /fetch failed|ECONNREFUSED|ENOTFOUND/.test(error.message))) {
+            throw new Error(`Cannot connect to Ollama at ${baseUrl}. ` +
+                `Make sure Ollama is installed and running — start it with: ollama serve`);
+        }
+        throw error;
+    }
+}
+async function requestOllama(options) {
+    await ensureOllamaReachable(options.baseUrl);
+    const controller = new AbortController();
+    const timeoutId = options.timeoutMs !== undefined
+        ? setTimeout(() => controller.abort(new Error(`Ollama request timed out after ${options.timeoutMs}ms.`)), options.timeoutMs)
+        : null;
+    try {
+        const response = await fetch(new URL("/api/chat", options.baseUrl), {
+            method: "POST",
+            headers: {
+                "content-type": "application/json"
+            },
+            body: JSON.stringify({
+                model: options.model,
+                messages: [
+                    { role: "system", content: options.systemPrompt },
+                    { role: "user", content: JSON.stringify(options.userPayload, null, 2) }
+                ],
+                stream: false,
+                format: toJSONSchema(options.schema),
+                options: {
+                    temperature: 0
+                }
+            }),
+            signal: controller.signal
+        });
+        const responseText = await response.text();
+        if (!response.ok) {
+            throw new Error(`Ollama request failed with ${response.status} ${response.statusText}: ${responseText.slice(0, 400)}`);
+        }
+        const parsedResponse = JSON.parse(responseText);
+        if (parsedResponse.error) {
+            throw new Error(`Ollama returned an error: ${parsedResponse.error}`);
+        }
+        const rawContent = parsedResponse.message?.content?.trim() ?? "";
+        if (!rawContent) {
+            throw new Error("Ollama returned an empty message content.");
+        }
+        return options.schema.parse(JSON.parse(stripJsonCodeFence(rawContent)));
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(options.timeoutMs !== undefined ? `Ollama request timed out after ${options.timeoutMs}ms.` : "Ollama request timed out.");
+        }
+        throw error;
+    }
+    finally {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+async function generateWithOllama(options) {
+    const maxAttempts = 1 + Math.max(0, options.maxRetries ?? 0);
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            return await requestOllama(options);
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxAttempts) {
+                break;
+            }
+        }
+    }
+    throw new Error(cleanErrorMessage(lastError));
+}
+/** Minimum delay (ms) between consecutive LLM requests to avoid rate-limiting. */
+const LLM_REQUEST_DELAY_MS = Math.max(0, Number(process.env.LLM_REQUEST_DELAY_MS) || 4000);
+let lastLlmRequestTimestamp = 0;
+async function throttleLlmRequest() {
+    if (LLM_REQUEST_DELAY_MS <= 0) {
+        return;
+    }
+    const now = Date.now();
+    const elapsed = now - lastLlmRequestTimestamp;
+    if (elapsed < LLM_REQUEST_DELAY_MS) {
+        await new Promise((resolve) => setTimeout(resolve, LLM_REQUEST_DELAY_MS - elapsed));
+    }
+    lastLlmRequestTimestamp = Date.now();
+}
+export async function generateStructured(options) {
+    await throttleLlmRequest();
+    const runtime = resolveLlmRuntime({
+        ...(options.provider ? { provider: options.provider } : {}),
+        ...(options.model ? { model: options.model } : {}),
+        ...(options.ollamaBaseUrl ? { ollamaBaseUrl: options.ollamaBaseUrl } : {})
+    });
+    if (runtime.provider === "ollama") {
+        return generateWithOllama({
+            baseUrl: runtime.ollamaBaseUrl,
+            model: runtime.model,
+            systemPrompt: options.systemPrompt,
+            userPayload: options.userPayload,
+            schema: options.schema,
+            ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+            ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {})
+        });
+    }
+    return generateWithOpenAI({
+        model: runtime.model,
+        systemPrompt: options.systemPrompt,
+        userPayload: options.userPayload,
+        schemaName: options.schemaName,
+        schema: options.schema,
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {})
+    });
+}

package/dist/paystack/account.js

@@ -0,0 +1,123 @@
+import fs from 'fs';
+import path from 'path';
+import { getPaystackClient } from './client.js';
+import { PaystackCustomerSchema, PaystackDVASchema, } from './types.js';
+/**
+ * Manages the agent's Dedicated Virtual Account (DVA).
+ *
+ * On first call, createAgentAccount() will:
+ *   1. Create (or retrieve) a Paystack customer for the agent
+ *   2. Create a dedicated virtual bank account tied to that customer
+ *   3. Cache the result locally so restarts don't re-create it
+ *
+ * The cached account file is written to:
+ *   <SITE_AGENT_DATA_DIR>/paystack/dva.json   (if env var set)
+ *   ./data/paystack/dva.json                  (fallback)
+ */
+const DVA_PROVIDER = process.env['PAYSTACK_DVA_PROVIDER'] ??
+    'wema-bank';
+const AGENT_EMAIL = process.env['PAYSTACK_AGENT_EMAIL'] || 'agent@site-agent-pro.com';
+const AGENT_FIRST_NAME = process.env['PAYSTACK_AGENT_FIRST_NAME'] ?? 'Site';
+const AGENT_LAST_NAME = process.env['PAYSTACK_AGENT_LAST_NAME'] ?? 'Agent';
+const AGENT_PHONE = process.env['PAYSTACK_AGENT_PHONE'] ?? '';
+function dvaCachePath() {
+    const base = process.env['SITE_AGENT_DATA_DIR'] ?? path.join(process.cwd(), 'data');
+    return path.join(base, 'paystack', 'dva.json');
+}
+function loadCachedDVA() {
+    try {
+        const raw = fs.readFileSync(dvaCachePath(), 'utf8');
+        const parsed = PaystackDVASchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function cacheDVA(dva) {
+    const p = dvaCachePath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(dva, null, 2), 'utf8');
+}
+// ─── Customer helpers ─────────────────────────────────────────────────────────
+async function findOrCreateCustomer() {
+    const client = getPaystackClient();
+    // Search for existing customer by email
+    try {
+        const existing = await client.get(`/customer/${encodeURIComponent(AGENT_EMAIL)}`);
+        const parsed = PaystackCustomerSchema.safeParse(existing);
+        if (parsed.success) {
+            console.log(`[paystack/account] Found existing customer: ${parsed.data.customer_code}`);
+            // If live and phone is missing, update it
+            if (AGENT_PHONE && !parsed.data.phone) {
+                console.log(`[paystack/account] Updating customer ${parsed.data.customer_code} with missing phone number…`);
+                await client.put(`/customer/${parsed.data.customer_code}`, { phone: AGENT_PHONE });
+            }
+            return parsed.data;
+        }
+    }
+    catch {
+        // 404 → customer doesn't exist yet, fall through to create
+    }
+    const created = await client.post('/customer', {
+        email: AGENT_EMAIL,
+        first_name: AGENT_FIRST_NAME,
+        last_name: AGENT_LAST_NAME,
+        phone: AGENT_PHONE,
+    });
+    const parsed = PaystackCustomerSchema.parse(created);
+    console.log(`[paystack/account] Created new customer: ${parsed.customer_code}`);
+    return parsed;
+}
+// ─── DVA helpers ──────────────────────────────────────────────────────────────
+async function createDVA(customerCode) {
+    const client = getPaystackClient();
+    const raw = await client.post('/dedicated_account', {
+        customer: customerCode,
+        preferred_bank: DVA_PROVIDER,
+    });
+    return PaystackDVASchema.parse(raw);
+}
+async function listDVAsForCustomer(customerCode) {
+    const client = getPaystackClient();
+    const raw = await client.get('/dedicated_account', {
+        customer: customerCode,
+    });
+    return Array.isArray(raw) ? raw.map((d) => PaystackDVASchema.parse(d)) : [];
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Returns the agent's dedicated virtual account, creating it on first call.
+ * Subsequent calls return the locally cached result (no extra API hit).
+ */
+export async function getAgentAccount() {
+    const cached = loadCachedDVA();
+    if (cached) {
+        return cached;
+    }
+    const customer = await findOrCreateCustomer();
+    // Check if a DVA already exists for this customer
+    const existing = await listDVAsForCustomer(customer.customer_code);
+    if (existing.length > 0) {
+        const dva = existing[0];
+        cacheDVA(dva);
+        return dva;
+    }
+    // Create a new DVA
+    const dva = await createDVA(customer.customer_code);
+    cacheDVA(dva);
+    console.log(`[paystack/account] DVA created: ${dva.account_number} (${dva.bank.name})`);
+    return dva;
+}
+/**
+ * Pretty-prints the agent's virtual account details.
+ */
+export function formatAccountDetails(dva) {
+    return [
+        `Bank:           ${dva.bank.name}`,
+        `Account Number: ${dva.account_number}`,
+        `Account Name:   ${dva.account_name}`,
+        `Currency:       ${dva.currency}`,
+        `Active:         ${dva.active ? 'Yes' : 'No'}`,
+    ].join('\n');
+}

package/dist/paystack/client.js

@@ -0,0 +1,100 @@
+/**
+ * Thin fetch-based wrapper for the Paystack REST API.
+ * Uses Node 20+ built-in fetch — no external dependencies required.
+ * Reads PAYSTACK_SECRET_KEY from the environment.
+ *
+ * All public methods return the unwrapped `data` field from
+ * Paystack's standard { status, message, data } envelope, and
+ * throw a descriptive PaystackError on any non-2xx response.
+ */
+const BASE_URL = 'https://api.paystack.co';
+const TIMEOUT_MS = 30_000;
+export class PaystackError extends Error {
+    statusCode;
+    raw;
+    constructor(statusCode, message, raw) {
+        super(`Paystack API error (${statusCode}): ${message}`);
+        this.statusCode = statusCode;
+        this.raw = raw;
+        this.name = 'PaystackError';
+    }
+}
+export class PaystackClient {
+    headers;
+    constructor(secretKey) {
+        const key = secretKey ?? process.env['PAYSTACK_SECRET_KEY'];
+        if (!key) {
+            throw new Error('PAYSTACK_SECRET_KEY is not set. Add it to your .env file.');
+        }
+        this.headers = {
+            Authorization: `Bearer ${key}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+    }
+    // ─── Core request helpers ─────────────────────────────────────────────────
+    async get(path, params) {
+        const url = new URL(`${BASE_URL}${path}`);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined && v !== null) {
+                    url.searchParams.set(k, String(v));
+                }
+            }
+        }
+        return this.request(url.toString(), { method: 'GET' });
+    }
+    async post(path, body) {
+        return this.request(`${BASE_URL}${path}`, {
+            method: 'POST',
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+    }
+    async put(path, body) {
+        return this.request(`${BASE_URL}${path}`, {
+            method: 'PUT',
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+    }
+    // ─── Internal fetch with timeout ─────────────────────────────────────────
+    async request(url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        let res;
+        try {
+            res = await fetch(url, {
+                ...init,
+                headers: this.headers,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new PaystackError(0, `Request timed out after ${TIMEOUT_MS}ms`);
+            }
+            throw new PaystackError(0, String(err), err);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let json;
+        try {
+            json = (await res.json());
+        }
+        catch {
+            throw new PaystackError(res.status, `Non-JSON response from Paystack (${res.status})`);
+        }
+        if (!res.ok || !json.status) {
+            throw new PaystackError(res.status, json.message ?? `HTTP ${res.status}`, json);
+        }
+        return json.data;
+    }
+}
+// Singleton — reuse across the process lifetime
+let _client = null;
+export function getPaystackClient() {
+    if (!_client)
+        _client = new PaystackClient();
+    return _client;
+}

package/dist/paystack/index.js

@@ -0,0 +1,13 @@
+/**
+ * src/paystack/index.ts
+ * ─────────────────────
+ * Public surface of the Paystack module.
+ * Import from here rather than individual files.
+ *
+ * @example
+ * import { getAgentAccount, sendMoney, paystackWebhookMiddleware } from './paystack/index.js';
+ */
+export { PaystackClient, PaystackError, getPaystackClient } from './client.js';
+export { getAgentAccount, formatAccountDetails } from './account.js';
+export { ensureRecipient, sendTransfer, sendMoney, listBanks, resolveBankCode, listTransactions, } from './transfer.js';
+export { handleWebhook, paystackWebhookMiddleware, } from './webhook.js';

package/dist/paystack/test-paystack.js

@@ -0,0 +1,83 @@
+/**
+ * Paystack integration smoke-test.
+ *
+ * Run with:
+ *   npx tsx src/paystack/test-paystack.ts
+ *
+ * What it does (in order):
+ *   1. Verifies PAYSTACK_SECRET_KEY is set
+ *   2. Creates / retrieves the agent's Dedicated Virtual Account (DVA)
+ *   3. Prints the bank account details
+ *   4. Fetches the list of supported banks and resolves a sample bank name
+ *   5. Runs a DRY-RUN transfer (no money moves unless PAYSTACK_TRANSFER_ENABLED=true)
+ *
+ * No flags needed — all config is read from .env.
+ */
+import 'dotenv/config';
+import { getAgentAccount, formatAccountDetails, sendMoney, listBanks, resolveBankCode, } from './index.js';
+const DIVIDER = '─'.repeat(56);
+function section(title) {
+    console.log(`\n${DIVIDER}`);
+    console.log(`  ${title}`);
+    console.log(DIVIDER);
+}
+async function main() {
+    console.log('\n🚀  Site Agent Pro — Paystack Integration Test\n');
+    // ── 1. Env check ────────────────────────────────────────────────────────────
+    section('1 / 5  Environment');
+    const key = process.env['PAYSTACK_SECRET_KEY'];
+    if (!key) {
+        console.error('❌  PAYSTACK_SECRET_KEY is not set in .env — aborting.');
+        process.exit(1);
+    }
+    const mode = key.startsWith('sk_live') ? 'LIVE 🔴' : 'TEST 🟡';
+    console.log(`  Key mode : ${mode}`);
+    console.log(`  Transfers: ${process.env['PAYSTACK_TRANSFER_ENABLED'] === 'true'
+        ? 'ENABLED (real money will move)'
+        : 'DRY-RUN (safe — nothing will be sent)'}`);
+    // ── 2. Dedicated Virtual Account ────────────────────────────────────────────
+    section('2 / 5  Dedicated Virtual Account');
+    console.log('  Fetching / creating agent DVA…');
+    const dva = await getAgentAccount();
+    console.log('\n' + formatAccountDetails(dva).replace(/^/gm, '  '));
+    // ── 3. Bank list ─────────────────────────────────────────────────────────────
+    section('3 / 5  Bank List');
+    console.log('  Fetching supported banks…');
+    const banks = await listBanks();
+    console.log(`  ${banks.length} banks returned from Paystack.\n`);
+    // Show first 5 as a sample
+    banks.slice(0, 5).forEach((b) => {
+        console.log(`  ${b.code.padEnd(6)} ${b.name}`);
+    });
+    if (banks.length > 5) {
+        console.log(`  … and ${banks.length - 5} more`);
+    }
+    // ── 4. Bank code resolution ──────────────────────────────────────────────────
+    section('4 / 5  Bank Code Resolution');
+    const samples = ['guaranty', 'zenith', 'access', 'firstbank'];
+    for (const name of samples) {
+        const code = await resolveBankCode(name);
+        console.log(`  "${name}" → ${code ?? '(not found)'}`);
+    }
+    // ── 5. Dry-run transfer ──────────────────────────────────────────────────────
+    section('5 / 5  Transfer (dry-run safe)');
+    console.log('  Initiating test transfer…\n');
+    const { recipient, transfer } = await sendMoney({
+        accountNumber: '0123456789', // ← replace with a real account for live tests
+        bankCode: '058', // GTBank
+        recipientName: 'Test Recipient',
+        amountNaira: 100,
+        reason: 'Site Agent Pro smoke test',
+    });
+    console.log(`  Recipient code : ${recipient.recipient_code}`);
+    console.log(`  Transfer code  : ${transfer.transfer_code}`);
+    console.log(`  Amount         : ₦${(transfer.amount / 100).toLocaleString()}`);
+    console.log(`  Status         : ${transfer.status}`);
+    console.log(`  Reference      : ${transfer.reference}`);
+    console.log(`\n${DIVIDER}`);
+    console.log('  ✅  All checks passed.\n');
+}
+main().catch((err) => {
+    console.error('\n❌  Test failed:', err);
+    process.exit(1);
+});