@aifinpay/agent 0.1.0-alpha.1 → 0.3.0-alpha.0

package/dist/unifiedAgent.d.ts

@@ -0,0 +1,222 @@
+import { type PrivateKeyAccount } from "viem/accounts";
+import { AiFinPayError } from "./errors.js";
+import { Agent, type AgentOptions } from "./agent.js";
+export type ChainId = "solana" | "polygon";
+export interface ProviderEntry {
+    name: string;
+    display_name?: string;
+    preferred_chain: ChainId;
+    accepted_chains: ChainId[];
+    price_usd: number;
+    mode: "per_call" | "session" | "both";
+    bridge_url: string;
+    merchant_wallet: string;
+    service_type?: string;
+    url?: string;
+}
+export interface CallOptions {
+    provider: string;
+    cost?: number;
+    chain?: ChainId;
+    bridgeUrl?: string;
+    body?: unknown;
+    method?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface BalanceSnapshot {
+    agent_balance_usd: number;
+    chains: {
+        solana: {
+            sol: number;
+            usdc: number;
+            msecco_balance: number;
+        };
+        polygon: {
+            matic: number;
+            usdc: number;
+            msecco_balance: number;
+        };
+    };
+    spend_24h_usd: number;
+    budget_caps: {
+        daily_usd?: number;
+        per_call_usd?: number;
+    };
+    priced_at: number;
+}
+export interface ReputationSnapshot {
+    trust_score: number;
+    spend_score: number;
+    tenure_days: number;
+    verified: boolean;
+    flags: string[];
+}
+export interface BudgetCaps {
+    daily_usd?: number;
+    per_call_usd?: number;
+}
+export interface SessionHandle {
+    id: string;
+    provider: string;
+    chain: ChainId;
+    budget_usd: number;
+    spent_usd: number;
+    remaining_usd: number;
+    expires_at: number;
+    call(body: unknown): Promise<Response>;
+    close(): Promise<SessionReceipt>;
+    abandon(): Promise<void>;
+}
+export interface SessionReceipt {
+    session_id: string;
+    spent_usd: number;
+    refund_usd: number;
+    settlement_tx: string;
+    block: number | string;
+}
+export interface AiFinPayAgentOptions extends AgentOptions {
+    registryUrl?: string;
+    evmPrivateKey?: `0x${string}`;
+    budgetCaps?: BudgetCaps;
+    telemetry?: boolean;
+    polygonRpc?: string;
+}
+export declare class ProviderUnknownError extends AiFinPayError {
+}
+export declare class WrongChainBalanceError extends AiFinPayError {
+    has: ChainId[];
+    needed: ChainId;
+    constructor(has: ChainId[], needed: ChainId, msg: string);
+}
+export declare class InsufficientFundsError extends AiFinPayError {
+    needed_usd: number;
+    available_usd: number;
+    constructor(needed_usd: number, available_usd: number, msg: string);
+}
+export declare class BudgetCapExceededError extends AiFinPayError {
+    kind: "daily" | "per_call";
+    constructor(kind: "daily" | "per_call", msg: string);
+}
+export declare class SettlementError extends AiFinPayError {
+    reason: string;
+    txHash?: string | undefined;
+    constructor(reason: string, txHash?: string | undefined);
+}
+export declare class SessionExpiredError extends AiFinPayError {
+    session_id: string;
+    constructor(session_id: string);
+}
+export declare class AiFinPayAgent {
+    readonly inner: Agent;
+    readonly evmAccount: PrivateKeyAccount;
+    readonly registryUrl: string;
+    readonly polygonRpc: string;
+    private cachedRegistry?;
+    private budgetCaps;
+    private spend24h;
+    private telemetry;
+    private _polygonPublic?;
+    private _polygonWallet?;
+    private constructor();
+    private polygonClients;
+    /**
+     * Generate a fresh agent — new Solana keypair + new EVM keypair.
+     * Use `fromSeed()` to derive both from a single backup phrase instead.
+     */
+    static new(opts?: AiFinPayAgentOptions): Promise<AiFinPayAgent>;
+    /**
+     * Derive both keypairs from a single 32-byte hex seed. Same seed →
+     * deterministic Solana pubkey AND EVM address. One backup phrase, two
+     * chains.
+     *
+     * Solana key = nacl.sign.keyPair.fromSeed(seed)
+     * EVM key    = keccak256(seed)[:32]    (independent path; not BIP-44
+     *                                       compatible — see design notes
+     *                                       in 23 - Unified SDK Design).
+     *
+     * TODO(phase-1): replace with BIP-39/BIP-44 derivation
+     *   m/44'/501'/0'/0' (Solana) + m/44'/60'/0'/0/0 (EVM) once the
+     *   wallet-import audit recommendation lands.
+     */
+    static fromSeed(seedHex: string, opts?: AiFinPayAgentOptions): Promise<AiFinPayAgent>;
+    /**
+     * Legacy: load the Solana side from an existing keypair, then either
+     * generate a fresh EVM key or import one with `attachEvmKey`.
+     */
+    static fromSolanaSecret(secretB58: string, opts?: AiFinPayAgentOptions): Promise<AiFinPayAgent>;
+    get id(): string;
+    get solanaAddress(): string;
+    get evmAddress(): string;
+    fetchRegistry(force?: boolean): Promise<ProviderEntry[]>;
+    resolveProvider(name: string): Promise<ProviderEntry>;
+    setBudget(caps: BudgetCaps): void;
+    private checkBudget;
+    /**
+     * Chain selection heuristic — see Obsidian/23 - Unified SDK Design §Routing.
+     *
+     *   1. Explicit override always wins (subject to provider acceptance).
+     *   2. Cost ≤ $0.005 + Solana per-call live + Solana accepted → Solana
+     *      (low gas wins for tiny calls).
+     *   3. Cost > $0.05 + Polygon accepted → Polygon
+     *      (better finality for high-value calls).
+     *   4. Middle band → provider.preferred_chain.
+     *   5. Fallback → first accepted chain.
+     *
+     * Solana per-call is gated on the deploy of `b2b_pay_with_split` —
+     * until then `solana` selection raises in `call()`.
+     */
+    private pickChain;
+    /**
+     * TODO(phase-4): mint AgentPassport on the cheapest chain available
+     * with the requested `stake_usd`. For now wires only the Solana side
+     * via the existing `reserveSeatInvoice` semantics.
+     */
+    verify(_args?: {
+        stake_usd?: number;
+    }): Promise<{
+        verified: boolean;
+    }>;
+    /**
+     * TODO(phase-1): pick a chain (preferred USDC on Polygon for stability;
+     * fallback Solana SOL). Return signed-tx instructions for the wallet.
+     */
+    deposit(_usd: number, _opts?: {
+        asset?: "USDC" | "USDT" | "SOL" | "MATIC";
+        chain?: ChainId;
+    }): Promise<unknown>;
+    /**
+     * High-level paid call. Resolves the provider, picks a chain, builds the
+     * payment, sends to the bridge, retries with payment proof.
+     *
+     * Phase 1 implementation: Polygon per-call splitter via on-chain
+     * `B2BSplitter.payMatic()`. Solana per-call branch lights up after
+     * Phase 2 (b2b_pay_with_split deploy via Squads).
+     */
+    call(opts: CallOptions): Promise<Response>;
+    /**
+     * TODO(phase-3): open a metered budget session.
+     */
+    openSession(_args: {
+        provider: string;
+        budget_usd: number;
+        ttl_seconds?: number;
+    }): Promise<SessionHandle>;
+    /**
+     * Snapshot the agent's funds across both chains, USD-normalised.
+     *
+     * Phase 1.4: native MATIC + native SOL via RPC; ERC-20 / SPL token balances
+     * deferred (we don't yet need them for the unified `call()` flow which
+     * settles in MATIC). Pyth feeds are TODO; for now uses
+     * `AIFINPAY_MATIC_USD` and `AIFINPAY_SOL_USD` env, defaulting to 0.7 and 200.
+     */
+    balance(): Promise<BalanceSnapshot>;
+    private fetchPolygonNative;
+    private fetchSolanaNative;
+    /**
+     * TODO(phase-4 / phase-5): query operator backend reputation engine.
+     */
+    reputation(): Promise<ReputationSnapshot>;
+    private reportTelemetry;
+}
+//# sourceMappingURL=unifiedAgent.d.ts.map

package/dist/unifiedAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unifiedAgent.d.ts","sourceRoot":"","sources":["../src/unifiedAgent.ts"],"names":[],"mappings":"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"}