@everestan/protocolbanks-sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @everestan/protocolbanks-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agent execution, payments and invoicing for Protocol Banks.
+
+```bash
+npm install @everestan/protocolbanks-sdk
+```
+
+## Agent API
+
+One API key, one policy the server enforces (operations, per-call cap, daily
+cap, coin allowlist). `order` executes through the account's Hyperliquid agent
+wallet (trading-only rights); `pay`, `swap` and `invoice` return something the
+agent signs itself — the platform holds no keys.
+
+```ts
+import { ProtocolBanks } from "@everestan/protocolbanks-sdk"
+
+const pb = new ProtocolBanks({ apiKey: process.env.PB_KEY! })
+
+const state = await pb.agent.state() // mode, equity, positions, policy
+const order = await pb.agent.order({ coin: "BTC", side: "long", sizeUsd: 20 })
+
+// Refusals are returned with the HTTP status — they are not exceptions.
+if (!order.ok) console.log(order.status, order.error) // 403 policy · 409 guard
+```
+
+```ts
+await pb.agent.pay({ to: "0x…", amountUsd: 25, token: "USDC", chain: "base" })
+await pb.agent.swap({ from: { symbol: "USDC", blockchain: "base" }, to: { symbol: "ETH", blockchain: "base" }, amount: "25", amountUsd: 25 })
+const invoice = await pb.agent.invoice({ to: "0x…", amount: 25, description: "agent work" })
+await pb.agent.invoiceStatus(invoice.invoice!.invoiceId, "sig-from-paymentLink")
+```
+
+- Reference: https://github.com/everest-an/protocol-banks---web3/blob/main/docs/AGENT_API.md
+- Contract: https://protocolbanks.com/api/agent.openapi.json
+- Tool manifest: `@everestan/protocolbanks-agent-tools`
+
+## Payments
+
+`pb.paymentLinks`, `pb.invoices`, `pb.checkout`, `pb.webhooks` and
+`pb.embed()` cover the payment surfaces. See the docs above for the contracts.
+
+## License
+
+GPL-3.0-only.

package/dist/index.d.mts

@@ -0,0 +1,555 @@
+/**
+ * SDK Type Definitions
+ */
+type TokenSymbol = "USDC" | "USDT" | "DAI";
+type ChainId = 1 | 8453 | 42161 | 137 | 10 | 56;
+type PaymentStatus = "pending" | "paid" | "expired" | "cancelled" | "failed";
+interface ProtocolBanksConfig {
+    /** API key for authentication (pk_* format) */
+    apiKey: string;
+    /** API secret (sk_* format, server-side only) */
+    apiSecret?: string;
+    /** Base URL for the Protocol Banks API */
+    baseUrl?: string;
+    /** Default chain ID */
+    defaultChainId?: ChainId;
+    /** Default token */
+    defaultToken?: TokenSymbol;
+}
+interface PaymentLinkConfig {
+    /** Payment title */
+    title: string;
+    /** Payment description */
+    description?: string;
+    /** Fixed amount (if not set, customer enters amount) */
+    amount?: string;
+    /** Payment token */
+    token?: TokenSymbol;
+    /** Recipient wallet address */
+    recipientAddress: string;
+    /** Redirect URL after payment */
+    redirectUrl?: string;
+    /** Expiration in seconds */
+    expiresIn?: number;
+    /** Custom branding */
+    branding?: {
+        color?: string;
+        logoUrl?: string;
+    };
+    /** Post-payment asset distribution */
+    assetDistribution?: {
+        type: "nft" | "token";
+        contractAddress: string;
+        tokenId?: string;
+        amount?: string;
+    };
+    /** Custom metadata */
+    metadata?: Record<string, any>;
+}
+interface InvoiceConfig {
+    /** Recipient wallet address */
+    recipientAddress: string;
+    /** Crypto amount */
+    amount: string;
+    /** Payment token */
+    token?: TokenSymbol;
+    /** Invoice description */
+    description: string;
+    /** Merchant/business name */
+    merchantName: string;
+    /** Fiat amount for dual-currency display */
+    amountFiat?: string;
+    /** Fiat currency code */
+    fiatCurrency?: string;
+    /** Customer info */
+    customer?: {
+        name?: string;
+        email?: string;
+    };
+    /** Expiration in hours */
+    expiresInHours?: number;
+    /** Custom metadata */
+    metadata?: Record<string, any>;
+}
+interface CheckoutConfig {
+    /** Order amount */
+    amount: string;
+    /** Currency (USD, EUR, etc.) */
+    currency?: string;
+    /** Payment token */
+    token?: TokenSymbol;
+    /** Merchant ID */
+    merchantId: string;
+    /** Notification URL for payment callbacks */
+    notifyUrl?: string;
+    /** Return URL after payment */
+    returnUrl?: string;
+    /** Custom metadata */
+    metadata?: Record<string, any>;
+}
+interface PaymentResult {
+    success: boolean;
+    /** Payment/order ID */
+    id: string;
+    /** Payment link URL */
+    paymentUrl: string;
+    /** Short URL */
+    shortUrl?: string;
+    /** QR code data */
+    qrCodeData?: string;
+    /** Payment status */
+    status: PaymentStatus;
+    /** Transaction hash (after payment) */
+    txHash?: string;
+    /** Error message */
+    error?: string;
+}
+
+/**
+ * Payment Links Module
+ *
+ * Create and manage no-code payment links.
+ */
+
+declare class PaymentLink {
+    private config;
+    constructor(config: ProtocolBanksConfig);
+    /**
+     * Create a new payment link
+     */
+    create(options: PaymentLinkConfig): Promise<PaymentResult>;
+    /**
+     * Get payment link details
+     */
+    get(linkId: string): Promise<any>;
+    /**
+     * List all payment links
+     */
+    list(merchantId?: string): Promise<any>;
+    /**
+     * Update a payment link
+     */
+    update(linkId: string, updates: Partial<PaymentLinkConfig> & {
+        status?: string;
+    }): Promise<any>;
+    /**
+     * Delete a payment link
+     */
+    delete(linkId: string): Promise<any>;
+}
+
+/**
+ * Invoice Module
+ *
+ * Create and manage crypto invoices.
+ */
+
+declare class Invoice {
+    private config;
+    constructor(config: ProtocolBanksConfig);
+    /**
+     * Create a new invoice
+     */
+    create(options: InvoiceConfig): Promise<PaymentResult>;
+    /**
+     * Get invoice details
+     */
+    get(invoiceId: string, signature?: string): Promise<any>;
+    /**
+     * Update invoice status (e.g., after payment)
+     */
+    updateStatus(invoiceId: string, status: string, txHash?: string, paidBy?: string): Promise<any>;
+    /**
+     * Get printable invoice export URL
+     */
+    getExportUrl(invoiceId: string, signature?: string): string;
+    /**
+     * List invoices for a merchant
+     */
+    list(options?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<any>;
+}
+
+/**
+ * Checkout Module
+ *
+ * Create checkout sessions for merchant acquiring.
+ */
+
+declare class Checkout {
+    private config;
+    constructor(config: ProtocolBanksConfig);
+    /**
+     * Create a new checkout order
+     */
+    create(options: CheckoutConfig): Promise<PaymentResult>;
+    /**
+     * Get order status
+     */
+    getStatus(orderNo: string): Promise<any>;
+    /**
+     * List orders for a merchant
+     */
+    listOrders(merchantId?: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<any>;
+    /**
+     * Open checkout in a popup window
+     */
+    openPopup(options: CheckoutConfig): Promise<PaymentResult>;
+}
+
+/**
+ * Webhook Module
+ *
+ * Verify incoming webhook signatures and manage webhook subscriptions.
+ */
+
+interface WebhookEvent {
+    event: string;
+    timestamp: string;
+    data: Record<string, any>;
+    delivery_id?: string;
+}
+interface WebhookConfig {
+    /** Webhook name */
+    name: string;
+    /** Delivery URL */
+    url: string;
+    /** Events to subscribe to */
+    events: string[];
+}
+declare class Webhook {
+    private config;
+    constructor(config: ProtocolBanksConfig);
+    /**
+     * Verify an incoming webhook signature (server-side only).
+     *
+     * Use this in your webhook handler to validate that the request
+     * came from Protocol Banks.
+     *
+     * @example
+     * ```ts
+     * const pb = new ProtocolBanks({ apiKey: 'pk_...' });
+     *
+     * app.post('/webhook', (req, res) => {
+     *   const signature = req.headers['x-webhook-signature'];
+     *   const timestamp = req.headers['x-webhook-timestamp'];
+     *   const body = JSON.stringify(req.body);
+     *
+     *   if (!pb.webhooks.verify(body, signature, 'whsec_...')) {
+     *     return res.status(401).send('Invalid signature');
+     *   }
+     *
+     *   // Process event
+     *   const event = req.body;
+     *   console.log('Received event:', event.event);
+     *   res.status(200).send('OK');
+     * });
+     * ```
+     */
+    verify(payload: string, signature: string, secret: string): boolean;
+    /**
+     * Browser-compatible signature verification using Web Crypto API
+     */
+    private verifyBrowser;
+    /**
+     * Async signature verification using Web Crypto API (works in browser and Node.js)
+     */
+    verifyAsync(payload: string, signature: string, secret: string): Promise<boolean>;
+    /**
+     * Construct a webhook event from a raw request
+     */
+    constructEvent(payload: string, signature: string, secret: string): WebhookEvent;
+    /**
+     * Create a new webhook subscription
+     */
+    create(options: WebhookConfig): Promise<any>;
+    /**
+     * List webhook subscriptions
+     */
+    list(): Promise<any>;
+    /**
+     * Delete a webhook subscription
+     */
+    delete(webhookId: string): Promise<any>;
+    /**
+     * Get recent webhook deliveries
+     */
+    getDeliveries(webhookId: string): Promise<any>;
+}
+
+/**
+ * Agent module
+ *
+ * The programmatic surface for AI agents: one API key, one policy the server
+ * enforces (operations, per-call cap, daily cap, coin allowlist). `order`
+ * executes through the account's Hyperliquid agent wallet (trading-only
+ * rights); `pay`, `swap` and `invoice` prepare something the agent signs
+ * itself, because the platform holds no keys.
+ *
+ * Every response is the API envelope plus the HTTP `status`, so a refusal
+ * (`ok: false` with 403/409) is returned, never thrown — a model should see
+ * the refusal and stop, not retry it.
+ */
+
+type AgentOp = "read" | "pay" | "swap" | "trade";
+interface AgentPolicy {
+    allowedOps: AgentOp[];
+    maxNotionalUsd: number;
+    dailyCapUsd: number;
+    allowedCoins: string[];
+    /** Present on `state` only: metered notional already spent today (UTC). */
+    spentTodayUsd?: number;
+}
+interface AgentAccount {
+    totalEquity: number;
+    mainWallet: number;
+    tradingWallet: number;
+    budget: number;
+    maxLoss: number;
+    todayPnl: number;
+    todayPnlPct: number;
+    allTimePnl: number;
+}
+interface AgentPosition {
+    symbol: string;
+    side: "long" | "short";
+    size: number;
+    entry: number;
+    mark: number;
+    pnl: number;
+    pnlPct: number;
+    leverage: number;
+    reason: string;
+}
+interface AgentActivity {
+    time: string;
+    type: "open" | "close" | "scan" | "guard" | "info" | "error";
+    text: string;
+    pnl: number | null;
+}
+interface AgentStateResponse {
+    ok?: boolean;
+    status?: number;
+    error?: string;
+    mode?: "paper" | "live";
+    agent?: {
+        status: "running" | "paused" | "stopped";
+        strategy: string;
+        lastScanAt: string;
+        marketsScanned: number;
+        confidenceHighSignals: number;
+    };
+    account?: AgentAccount;
+    equity?: {
+        t: string;
+        v: number;
+    }[];
+    positions?: AgentPosition[];
+    activity?: AgentActivity[];
+    pendingTrade?: {
+        symbol: string;
+        side: "long" | "short";
+        score: number;
+        reason: string;
+        markPx: number;
+        createdAt: string;
+    } | null;
+    approvalMode?: "auto" | "manual";
+    policy?: AgentPolicy;
+}
+interface AgentOrderRequest {
+    coin: string;
+    side: "long" | "short";
+    /** Notional in USD. Clamped to the platform position cap; refused above the key's cap. */
+    sizeUsd: number;
+    reason?: string;
+}
+interface AgentFill {
+    coin: string;
+    side: "long" | "short";
+    avgPx: number;
+    size: number;
+    notional: number;
+}
+interface AgentOrderResponse {
+    ok: boolean;
+    status?: number;
+    fill?: AgentFill;
+    fee?: number;
+    mode?: "live" | "paper";
+    /** dailyCapUsd − spentTodayUsd − this order */
+    remainingTodayUsd?: number;
+    error?: string;
+}
+interface AgentPayRequest {
+    to: string;
+    amountUsd: number;
+    token?: string;
+    chain?: string;
+    memo?: string;
+}
+interface AgentPayIntent {
+    kind: "evm-transfer" | "solana-transfer";
+    to: string;
+    token: string;
+    chain: string;
+    amountUsd: number;
+    memo?: string;
+    remainingTodayUsd: number;
+}
+interface AgentPayResponse {
+    ok: boolean;
+    status?: number;
+    intent?: AgentPayIntent;
+    note?: string;
+    error?: string;
+}
+interface AgentSwapAsset {
+    symbol: string;
+    blockchain: string;
+    address?: string | null;
+}
+interface AgentSwapRequest {
+    from: AgentSwapAsset;
+    to: AgentSwapAsset;
+    /** Amount in token units, as a string to avoid float precision loss. */
+    amount: string;
+    amountUsd: number;
+    slippage?: number;
+}
+interface AgentSwapResponse {
+    ok: boolean;
+    status?: number;
+    route?: {
+        requestId: string;
+        outputAmount: string;
+        outputAmountUsd: number;
+        swaps: unknown[];
+        tags: unknown[];
+        estimatedTimeInSeconds: number;
+        totalFeeUsd: number;
+        priceImpact: number;
+    };
+    note?: string;
+    error?: string;
+}
+interface AgentInvoiceRequest {
+    to: string;
+    amount: number;
+    token?: string;
+    chain?: string;
+    description?: string;
+    expiresInHours?: number;
+}
+interface AgentInvoice {
+    invoiceId: string;
+    status: "pending" | "paid" | "expired" | "cancelled";
+    to: string;
+    amount: number;
+    token: string;
+    chain: string;
+    description?: string;
+    expiresAt: string;
+    signed: boolean;
+    /** Give this to the payer: /pay?invoice=…&sig=… */
+    paymentLink: string;
+}
+interface AgentInvoiceResponse {
+    ok: boolean;
+    status?: number;
+    invoice?: AgentInvoice;
+    note?: string;
+    error?: string;
+}
+interface AgentInvoiceStatusResponse {
+    ok: boolean;
+    status: number;
+    invoice?: {
+        invoice_id: string;
+        status: string;
+        token: string;
+        chain: string | null;
+        amount: number;
+        paid_at: string | null;
+        customer_wallet: string | null;
+    };
+    error?: string;
+}
+declare class Agent {
+    private readonly config;
+    constructor(config: ProtocolBanksConfig);
+    private baseUrl;
+    private call;
+    /** Mode, equity, positions, activity and the key's policy with spentTodayUsd. */
+    state(): Promise<AgentStateResponse>;
+    /** Place one order. Executes through the trading-only agent wallet. */
+    order(request: AgentOrderRequest): Promise<AgentOrderResponse>;
+    /** Validate a payment and return the intent the agent signs itself. */
+    pay(request: AgentPayRequest): Promise<AgentPayResponse>;
+    /** Quote a swap; the agent signs and submits the returned transaction. */
+    swap(request: AgentSwapRequest): Promise<AgentSwapResponse>;
+    /** Create a pending invoice and get the payer's paymentLink. */
+    invoice(request: AgentInvoiceRequest): Promise<AgentInvoiceResponse>;
+    /**
+     * Read an invoice back with the id and signature from its paymentLink
+     * (`/pay?invoice=<id>&sig=<sig>`). A signed invoice answers 403 without sig.
+     */
+    invoiceStatus(invoiceId: string, sig?: string): Promise<AgentInvoiceStatusResponse>;
+}
+
+/**
+ * Protocol Banks SDK Client
+ *
+ * Main entry point for interacting with Protocol Banks APIs.
+ */
+
+declare class ProtocolBanks {
+    private config;
+    /** Payment Links module */
+    paymentLinks: PaymentLink;
+    /** Invoicing module */
+    invoices: Invoice;
+    /** Checkout module */
+    checkout: Checkout;
+    /** Webhooks module */
+    webhooks: Webhook;
+    /** Agent module — orders through the platform's risk envelope */
+    agent: Agent;
+    constructor(config: ProtocolBanksConfig);
+    /**
+     * Create an embeddable payment iframe
+     */
+    embed(options: {
+        container: HTMLElement | string;
+        to: string;
+        amount?: string;
+        token?: string;
+        merchantName?: string;
+        theme?: "light" | "dark";
+        onSuccess?: (result: PaymentResult) => void;
+        onError?: (error: Error) => void;
+    }): {
+        destroy: () => void;
+    };
+    /**
+     * Generate a payment URL for direct redirect
+     */
+    getPaymentUrl(options: {
+        to: string;
+        amount: string;
+        token?: string;
+        merchantName?: string;
+    }): string;
+    /**
+     * Make an authenticated API request
+     */
+    request<T = any>(path: string, options?: RequestInit): Promise<T>;
+}
+
+export { Agent, type AgentAccount, type AgentActivity, type AgentFill, type AgentInvoice, type AgentInvoiceRequest, type AgentInvoiceResponse, type AgentInvoiceStatusResponse, type AgentOp, type AgentOrderRequest, type AgentOrderResponse, type AgentPayIntent, type AgentPayRequest, type AgentPayResponse, type AgentPolicy, type AgentPosition, type AgentStateResponse, type AgentSwapAsset, type AgentSwapRequest, type AgentSwapResponse, type ChainId, Checkout, type CheckoutConfig, Invoice, type InvoiceConfig, PaymentLink, type PaymentLinkConfig, type PaymentResult, type PaymentStatus, ProtocolBanks, type ProtocolBanksConfig, type TokenSymbol, Webhook, type WebhookConfig, type WebhookEvent };