@sly_ai/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,662 @@
+import { f as CapabilitiesResponse, h as Capability, P as PayOSEnvironment, E as EnvironmentConfig, b as SlyConfig } from './types-df1EICn_.mjs';
+export { e as ComplianceCheckRequest, C as ComplianceCheckResponse, d as CreateSettlementRequest, l as Currency, i as PayOSConfig, j as PaymentProtocol, a as Settlement, S as SettlementQuote, c as SettlementQuoteRequest, k as SettlementRail, m as SettlementStatus, g as SlyEnvironment } from './types-df1EICn_.mjs';
+import { S as SlyClient } from './client-Cwe2CLU7.mjs';
+import { PayOSX402Client as SlyX402Client, PayOSX402Provider as SlyX402Provider } from './x402.mjs';
+import { AP2Client } from './ap2.mjs';
+import { ACPClient } from './acp.mjs';
+import { UCPClient } from './ucp.mjs';
+import { CardsClient } from './cards.mjs';
+import { A2AClient } from './a2a.mjs';
+import 'express';
+import '@sly/types';
+
+/**
+ * Formatters for converting PayOS capabilities to AI agent tool formats
+ * - OpenAI function-calling format
+ * - Claude tool format
+ */
+
+/**
+ * OpenAI function-calling schema
+ * https://platform.openai.com/docs/guides/function-calling
+ */
+interface OpenAIFunction {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+        }>;
+        required: string[];
+    };
+}
+/**
+ * Claude tool schema (Anthropic Messages API)
+ * https://docs.anthropic.com/claude/docs/tool-use
+ */
+interface ClaudeTool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+        }>;
+        required: string[];
+    };
+}
+
+/**
+ * Types for PayOS Capabilities API
+ * Re-exports from main types + additional client-specific types
+ */
+
+interface CapabilitiesFilter {
+    category?: string;
+    name?: string;
+}
+
+declare class CapabilitiesClient {
+    private client;
+    private cachedCapabilities;
+    private cacheTimestamp;
+    private cacheTTL;
+    constructor(client: SlyClient);
+    /**
+     * Get all PayOS capabilities
+     * Results are cached for 1 hour by default
+     */
+    getAll(forceFresh?: boolean): Promise<CapabilitiesResponse>;
+    /**
+     * Get capabilities filtered by category or name
+     */
+    filter(filter: CapabilitiesFilter): Promise<Capability[]>;
+    /**
+     * Get a single capability by name
+     */
+    get(name: string): Promise<Capability | undefined>;
+    /**
+     * Get all available categories
+     */
+    getCategories(): Promise<string[]>;
+    /**
+     * Clear the capabilities cache
+     */
+    clearCache(): void;
+    /**
+     * Get capabilities in OpenAI function-calling format
+     */
+    toOpenAI(): Promise<{
+        functions: OpenAIFunction[];
+        systemMessage: string;
+    }>;
+    /**
+     * Get capabilities in OpenAI function-calling format (alias)
+     */
+    toOpenAIFunctions(): Promise<OpenAIFunction[]>;
+    /**
+     * Get capabilities in Claude tool format
+     */
+    toClaude(): Promise<{
+        tools: ClaudeTool[];
+        systemMessage: string;
+    }>;
+    /**
+     * Get capabilities in Claude tool format (alias)
+     */
+    toClaudeTools(): Promise<ClaudeTool[]>;
+    /**
+     * Get capabilities in LangChain tool format
+     */
+    toLangChain(): Promise<any[]>;
+}
+
+/**
+ * LangChain Tools Wrapper for PayOS SDK
+ */
+
+declare class LangChainTools {
+    private payos;
+    constructor(payos: Sly);
+    /**
+     * Get all PayOS capabilities as LangChain tools
+     */
+    getTools(): Promise<any[]>;
+    /**
+     * Get a specific tool by name
+     */
+    getTool(name: string): Promise<any>;
+}
+
+/**
+ * Agent Wallets Client
+ *
+ * Epic 18: Agent Wallets & Contract Policies
+ * Story 18.6: SDK Methods
+ *
+ * Provides:
+ *   - evaluatePolicy()  — dry-run contract policy evaluation
+ *   - getExposures()     — list counterparty exposures
+ *   - getEvaluations()   — audit log of policy decisions
+ *   - getWallet()        — get agent's wallet
+ *   - freezeWallet()     — freeze agent's wallet
+ *   - unfreezeWallet()   — reactivate agent's wallet
+ *   - setContractPolicy() — set contract policy on agent's wallet
+ */
+
+interface ContractPolicy {
+    counterpartyBlocklist?: string[];
+    counterpartyAllowlist?: string[];
+    minCounterpartyKyaTier?: number;
+    minCounterpartyReputation?: number;
+    allowedContractTypes?: string[];
+    blockedContractTypes?: string[];
+    maxExposure24h?: number;
+    maxExposure7d?: number;
+    maxExposure30d?: number;
+    maxActiveContracts?: number;
+    maxActiveEscrows?: number;
+    escalateAbove?: number;
+}
+interface SpendingPolicy {
+    dailySpendLimit?: number;
+    monthlySpendLimit?: number;
+    requiresApprovalAbove?: number;
+    approvedVendors?: string[];
+    approvedCategories?: string[];
+    approvedEndpoints?: string[];
+    contractPolicy?: ContractPolicy;
+}
+interface PolicyEvaluateRequest {
+    amount: number;
+    currency?: string;
+    actionType: 'payment' | 'escrow_create' | 'escrow_release' | 'contract_sign' | 'negotiation_check' | 'counterparty_check';
+    contractType?: string;
+    counterpartyAgentId?: string;
+    counterpartyAddress?: string;
+    protocol?: string;
+}
+interface PolicyCheckDetail {
+    check: string;
+    result: 'pass' | 'fail' | 'skip';
+    detail: string;
+}
+interface PolicyEvaluateResponse {
+    decision: 'approve' | 'escalate' | 'deny';
+    reasons: string[];
+    checks: PolicyCheckDetail[];
+    suggestedCounterOffer: {
+        maxAmount: number;
+        reason: string;
+    } | null;
+    evaluationMs: number;
+}
+interface CounterpartyExposure {
+    id: string;
+    walletId: string;
+    counterpartyAgentId: string | null;
+    counterpartyAddress: string | null;
+    exposure24h: number;
+    exposure7d: number;
+    exposure30d: number;
+    activeContracts: number;
+    activeEscrows: number;
+    totalVolume: number;
+    transactionCount: number;
+    currency: string;
+}
+interface PolicyEvaluation {
+    id: string;
+    actionType: string;
+    amount: number;
+    currency: string;
+    contractType: string | null;
+    counterpartyAgentId: string | null;
+    counterpartyAddress: string | null;
+    decision: string;
+    decisionReasons: string[];
+    suggestedCounterOffer: any;
+    checksPerformed: PolicyCheckDetail[];
+    evaluationMs: number;
+    createdAt: string;
+}
+declare class AgentWalletsClient {
+    private client;
+    constructor(client: SlyClient);
+    /**
+     * Evaluate a contract policy in dry-run mode (negotiation guardrails).
+     *
+     * @example
+     * ```typescript
+     * const result = await sly.agentWallets.evaluatePolicy('agent-uuid', {
+     *   amount: 150,
+     *   actionType: 'payment',
+     *   counterpartyAgentId: 'other-agent-uuid',
+     * });
+     * console.log(result.decision); // 'approve' | 'escalate' | 'deny'
+     * ```
+     */
+    evaluatePolicy(agentId: string, request: PolicyEvaluateRequest): Promise<PolicyEvaluateResponse>;
+    /**
+     * List counterparty exposures for an agent's wallet.
+     *
+     * @example
+     * ```typescript
+     * const exposures = await sly.agentWallets.getExposures('agent-uuid');
+     * for (const exp of exposures) {
+     *   console.log(`${exp.counterpartyAgentId}: ${exp.exposure24h} (24h)`);
+     * }
+     * ```
+     */
+    getExposures(agentId: string): Promise<CounterpartyExposure[]>;
+    /**
+     * Get policy evaluation audit log for an agent's wallet.
+     */
+    getEvaluations(agentId: string, options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        data: PolicyEvaluation[];
+        pagination: any;
+    }>;
+    /**
+     * Get an agent's wallet details.
+     */
+    getWallet(agentId: string): Promise<any>;
+    /**
+     * Freeze an agent's wallet (disables all payments).
+     */
+    freezeWallet(agentId: string): Promise<any>;
+    /**
+     * Unfreeze an agent's wallet (re-enables payments).
+     */
+    unfreezeWallet(agentId: string): Promise<any>;
+    /**
+     * Set or update the contract policy on an agent's wallet.
+     *
+     * @example
+     * ```typescript
+     * await sly.agentWallets.setContractPolicy('agent-uuid', {
+     *   dailySpendLimit: 500,
+     *   contractPolicy: {
+     *     counterpartyBlocklist: ['bad-agent-id'],
+     *     maxExposure24h: 200,
+     *     escalateAbove: 100,
+     *   },
+     * });
+     * ```
+     */
+    setContractPolicy(agentId: string, policy: SpendingPolicy): Promise<any>;
+}
+
+/**
+ * Types for MPP (Machine Payments Protocol)
+ */
+interface MppPayRequest {
+    service_url: string;
+    amount: number;
+    currency?: string;
+    intent?: string;
+    agent_id: string;
+    wallet_id?: string;
+}
+interface MppPayResponse {
+    status: 'completed' | 'approval_required';
+    transfer_id?: string;
+    approval_id?: string;
+    message?: string;
+    payment?: {
+        receipt_id?: string;
+        payment_method?: string;
+        settlement_network?: string;
+        settlement_tx_hash?: string;
+        amount_paid?: number;
+        currency?: string;
+    };
+}
+interface MppOpenSessionRequest {
+    service_url: string;
+    deposit_amount: number;
+    max_budget?: number;
+    agent_id: string;
+    wallet_id: string;
+    currency?: string;
+}
+interface MppSession {
+    id: string;
+    tenant_id: string;
+    agent_id: string;
+    wallet_id: string;
+    service_url: string;
+    status: MppSessionStatus;
+    deposit_amount: number;
+    spent_amount: number;
+    remaining_amount: number;
+    max_budget?: number;
+    currency: string;
+    voucher_count: number;
+    created_at: string;
+    updated_at: string;
+    closed_at?: string;
+}
+type MppSessionStatus = 'active' | 'closed' | 'expired' | 'exhausted';
+interface MppSessionDetail extends MppSession {
+    vouchers: any[];
+}
+interface MppListSessionsOptions {
+    agent_id?: string;
+    status?: MppSessionStatus;
+    limit?: number;
+    offset?: number;
+}
+interface MppListSessionsResponse {
+    data: MppSession[];
+    pagination: {
+        limit: number;
+        offset: number;
+        total: number;
+    };
+}
+interface MppListTransfersOptions {
+    service_url?: string;
+    session_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface MppListTransfersResponse {
+    data: any[];
+    pagination?: {
+        limit: number;
+        offset: number;
+        total: number;
+    };
+    total?: number;
+}
+interface MppReceiptVerification {
+    verified: boolean;
+    receipt_id: string;
+    transfer_id?: string;
+    amount?: number;
+    currency?: string;
+    service_url?: string;
+    verified_at?: string;
+}
+interface MppProvisionWalletRequest {
+    agent_id: string;
+    owner_account_id: string;
+    testnet?: boolean;
+    initial_balance?: number;
+}
+
+/**
+ * MPP Client - Machine Payments Protocol
+ *
+ * Wraps PayOS MPP API endpoints for governed machine payments and sessions.
+ */
+
+declare class MPPClient {
+    private client;
+    constructor(client: SlyClient);
+    /**
+     * Make a one-shot MPP payment to a service
+     *
+     * @example
+     * ```typescript
+     * const result = await sly.mpp.pay({
+     *   service_url: 'https://api.example.com',
+     *   amount: 0.50,
+     *   agent_id: 'agent-uuid',
+     * });
+     * ```
+     */
+    pay(request: MppPayRequest): Promise<MppPayResponse>;
+    /**
+     * Open a streaming payment session
+     *
+     * @example
+     * ```typescript
+     * const session = await sly.mpp.openSession({
+     *   service_url: 'https://api.example.com',
+     *   deposit_amount: 10.00,
+     *   agent_id: 'agent-uuid',
+     *   wallet_id: 'wallet-uuid',
+     * });
+     * ```
+     */
+    openSession(request: MppOpenSessionRequest): Promise<MppSession>;
+    /**
+     * Get session details with voucher history
+     */
+    getSession(sessionId: string): Promise<MppSessionDetail>;
+    /**
+     * List MPP sessions with optional filtering
+     */
+    listSessions(options?: MppListSessionsOptions): Promise<MppListSessionsResponse>;
+    /**
+     * Close an active session
+     */
+    closeSession(sessionId: string): Promise<MppSession>;
+    /**
+     * List MPP payment transfers
+     */
+    listTransfers(options?: MppListTransfersOptions): Promise<MppListTransfersResponse>;
+    /**
+     * Verify an MPP payment receipt
+     */
+    verifyReceipt(receiptId: string): Promise<MppReceiptVerification>;
+    /**
+     * Provision a wallet for MPP payments
+     */
+    provisionWallet(request: MppProvisionWalletRequest): Promise<any>;
+    /**
+     * Browse the MPP service directory
+     */
+    browseServices(options?: {
+        category?: string;
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Get pricing info for a service
+     */
+    getServicePricing(domain: string): Promise<any>;
+}
+
+/**
+ * Environment-specific configuration
+ */
+declare const ENVIRONMENT_CONFIGS: Record<PayOSEnvironment, EnvironmentConfig>;
+/**
+ * Infer environment from API key prefix
+ * - pk_test_* or pk_sandbox_* → sandbox
+ * - pk_live_* → production
+ */
+declare function inferEnvironmentFromKey(apiKey: string): PayOSEnvironment | undefined;
+/**
+ * Get configuration for an environment
+ */
+declare function getEnvironmentConfig(environment: PayOSEnvironment): EnvironmentConfig;
+/**
+ * Validate environment configuration
+ */
+declare function validateEnvironment(environment: PayOSEnvironment, evmPrivateKey?: string): void;
+
+/**
+ * Authentication helpers for PayOS SDK
+ *
+ * Supports both API key and username/password authentication
+ */
+interface LoginCredentials {
+    email: string;
+    password: string;
+}
+interface LoginResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    user: {
+        id: string;
+        email: string;
+        tenant_id: string;
+    };
+}
+/**
+ * Authenticate with email and password to get an access token
+ *
+ * @param credentials - Email and password
+ * @param apiUrl - PayOS API URL (default: http://localhost:4000)
+ * @returns Login response with access token
+ *
+ * @example
+ * ```ts
+ * const auth = await loginWithPassword({
+ *   email: 'user@example.com',
+ *   password: 'mypassword'
+ * });
+ *
+ * const payos = new PayOS({
+ *   apiKey: auth.access_token,
+ *   environment: 'sandbox'
+ * });
+ * ```
+ */
+declare function loginWithPassword(credentials: LoginCredentials, apiUrl?: string): Promise<LoginResponse>;
+/**
+ * Create a PayOS SDK instance with username/password authentication
+ *
+ * @param credentials - Email and password
+ * @param environment - Environment to connect to
+ * @param apiUrl - PayOS API URL (default: http://localhost:4000)
+ * @returns PayOS instance authenticated with the user's session
+ *
+ * @example
+ * ```ts
+ * import { PayOS, createWithPassword } from '@sly/sdk';
+ *
+ * const payos = await createWithPassword({
+ *   email: 'user@example.com',
+ *   password: 'mypassword',
+ * }, 'sandbox');
+ *
+ * // Now use payos normally
+ * const mandate = await payos.ap2.createMandate({...});
+ * ```
+ */
+declare function createWithPassword(credentials: LoginCredentials, environment?: 'sandbox' | 'testnet' | 'production', apiUrl?: string): Promise<any>;
+/**
+ * Verify if an API key is valid
+ *
+ * @param apiKey - API key to verify
+ * @param apiUrl - PayOS API URL
+ * @returns True if valid, false otherwise
+ */
+declare function verifyApiKey(apiKey: string, apiUrl?: string): Promise<boolean>;
+
+/**
+ * @sly/sdk - Unified SDK for Sly multi-protocol settlement
+ *
+ * This SDK provides:
+ * - x402 micropayments (Coinbase/Cloudflare)
+ * - AP2 agent mandates (Google)
+ * - ACP checkout (Stripe/OpenAI)
+ * - Direct settlement API
+ * - Pix/SPEI local rails
+ *
+ * @example Auto-routing (environment inferred from key prefix)
+ * ```ts
+ * const sly = new Sly({ apiKey: 'pk_test_...' });  // → sandbox.getsly.ai
+ * const sly = new Sly({ apiKey: 'pk_live_...' });   // → api.getsly.ai
+ * ```
+ *
+ * @example Explicit environment
+ * ```ts
+ * const sly = new Sly({
+ *   apiKey: 'pk_live_...',
+ *   environment: 'production',
+ *   evmPrivateKey: '0x...',
+ * });
+ * ```
+ */
+
+/**
+ * Main Sly SDK class
+ *
+ * Provides unified access to all Sly settlement protocols:
+ * - x402 (micropayments)
+ * - AP2 (agent mandates)
+ * - ACP (checkout)
+ * - UCP (universal commerce - Google+Shopify)
+ * - Direct settlement API
+ * - Capabilities discovery for AI agents
+ */
+declare class Sly extends SlyClient {
+    /**
+     * x402 protocol client
+     * Create x402 payments with automatic 402 handling
+     */
+    readonly x402: {
+        /**
+         * Create an x402 client for making payments
+         */
+        createClient: (config?: Partial<SlyConfig>) => SlyX402Client;
+        /**
+         * Create an x402 provider for accepting payments
+         */
+        createProvider: (routes: Record<string, {
+            price: string;
+            description?: string;
+            token?: string;
+        }>) => SlyX402Provider;
+    };
+    /**
+     * AP2 (Agent-to-Agent Protocol) client
+     * Google's mandate-based payment protocol
+     */
+    readonly ap2: AP2Client;
+    /**
+     * ACP (Agentic Commerce Protocol) client
+     * Stripe/OpenAI's checkout-based payment protocol
+     */
+    readonly acp: ACPClient;
+    /**
+     * UCP (Universal Commerce Protocol) client
+     * Google+Shopify's agentic commerce protocol
+     */
+    readonly ucp: UCPClient;
+    /**
+     * Capabilities client for tool discovery
+     * Enables AI agents to discover available Sly operations
+     */
+    readonly capabilities: CapabilitiesClient;
+    /**
+     * LangChain tools integration
+     */
+    readonly langchain: LangChainTools;
+    /**
+     * Card network integration (Visa VIC, Mastercard Agent Pay)
+     * Accept payments from AI agents using Web Bot Auth
+     */
+    readonly cards: CardsClient;
+    /**
+     * A2A (Agent-to-Agent Protocol) client
+     * Google's task-based protocol for inter-agent communication
+     */
+    readonly a2a: A2AClient;
+    /**
+     * Agent Wallets client
+     * Contract policy evaluation, exposure tracking, wallet management
+     */
+    readonly agentWallets: AgentWalletsClient;
+    /**
+     * MPP (Machine Payments Protocol) client
+     * Governed machine-to-machine payments and streaming sessions
+     */
+    readonly mpp: MPPClient;
+    constructor(config: SlyConfig);
+}
+
+export { CapabilitiesResponse, Capability, ENVIRONMENT_CONFIGS, EnvironmentConfig, LangChainTools as L, type LoginCredentials, type LoginResponse, Sly as PayOS, SlyClient as PayOSClient, PayOSEnvironment, Sly, SlyClient, SlyConfig, createWithPassword, getEnvironmentConfig, inferEnvironmentFromKey, loginWithPassword, validateEnvironment, verifyApiKey };