@sly_ai/sdk 0.1.0

package/dist/cards.d.ts

@@ -0,0 +1,750 @@
+import { S as SlyClient } from './client-CyJe3uWO.js';
+import './types-df1EICn_.js';
+
+/**
+ * Card Network Types
+ *
+ * Type definitions for Visa VIC and Mastercard Agent Pay integration
+ */
+/**
+ * Supported card networks
+ */
+type CardNetwork = 'visa' | 'mastercard';
+/**
+ * Card network status
+ */
+type NetworkStatus = 'active' | 'inactive' | 'not_configured';
+/**
+ * Agent signature verification request
+ */
+interface VerifyAgentSignatureRequest {
+    /** HTTP method (GET, POST, etc.) */
+    method: string;
+    /** Request path */
+    path: string;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Signature-Input header value */
+    signatureInput: string;
+    /** Signature header value */
+    signature: string;
+    /** Optional: specify which network to verify against */
+    network?: CardNetwork;
+}
+/**
+ * Agent signature verification result
+ */
+interface VerifyAgentSignatureResult {
+    /** Whether the signature is valid */
+    valid: boolean;
+    /** Detected card network */
+    network?: CardNetwork;
+    /** Key ID from the signature */
+    keyId?: string;
+    /** AI agent provider (e.g., 'anthropic', 'openai') */
+    agentProvider?: string;
+    /** Error message if verification failed */
+    error?: string;
+    /** Verification timestamp */
+    verifiedAt?: string;
+}
+/**
+ * Individual network configuration
+ */
+interface NetworkConfig {
+    /** Whether the network is configured */
+    configured: boolean;
+    /** Network status */
+    status: NetworkStatus;
+    /** Connected account ID */
+    accountId: string | null;
+    /** Whether using sandbox mode */
+    sandbox: boolean;
+    /** When the network was connected */
+    connectedAt: string | null;
+}
+/**
+ * Card networks response
+ */
+interface CardNetworksResponse {
+    /** Network configurations */
+    networks: {
+        visa: NetworkConfig;
+        mastercard: NetworkConfig;
+    };
+    /** Available capabilities based on configuration */
+    capabilities: {
+        webBotAuth: boolean;
+        paymentInstructions: boolean;
+        agentRegistration: boolean;
+        tokenization: boolean;
+    };
+}
+/**
+ * Verification statistics
+ */
+interface VerificationStats {
+    /** Total verification attempts */
+    total: number;
+    /** Successful verifications */
+    successful: number;
+    /** Failed verifications */
+    failed: number;
+    /** Breakdown by network */
+    byNetwork: {
+        visa: number;
+        mastercard: number;
+    };
+    /** Breakdown by AI provider */
+    byProvider: Record<string, number>;
+}
+/**
+ * Transaction statistics
+ */
+interface TransactionStats {
+    /** Total transactions */
+    total: number;
+    /** Total volume in USD */
+    volume: number;
+    /** Breakdown by status */
+    byStatus: {
+        completed: number;
+        pending: number;
+        failed: number;
+    };
+    /** Breakdown by network */
+    byNetwork: {
+        visa: number;
+        mastercard: number;
+    };
+}
+/**
+ * Recent transaction
+ */
+interface RecentTransaction {
+    id: string;
+    network: CardNetwork;
+    amount: number;
+    currency: string;
+    merchantName: string;
+    status: string;
+    createdAt: string;
+}
+/**
+ * Card analytics response
+ */
+interface CardAnalyticsResponse {
+    /** Verification statistics */
+    verifications: VerificationStats & {
+        successRate: number;
+    };
+    /** Transaction statistics */
+    transactions: TransactionStats;
+    /** Recent transactions */
+    recentTransactions: RecentTransaction[];
+    /** Analytics period */
+    period: {
+        days: number;
+        from: string;
+        to: string;
+    };
+}
+/**
+ * Merchant information for Visa instructions
+ */
+interface VisaMerchant {
+    /** Merchant name */
+    name: string;
+    /** MCC code */
+    categoryCode: string;
+    /** Country code (default: US) */
+    country?: string;
+    /** Merchant URL */
+    url?: string;
+}
+/**
+ * Payment restrictions for Visa instructions
+ */
+interface VisaRestrictions {
+    /** Maximum transaction amount */
+    maxAmount?: number;
+    /** Allowed merchant categories */
+    allowedCategories?: string[];
+    /** Blocked merchant categories */
+    blockedCategories?: string[];
+    /** Allowed countries */
+    allowedCountries?: string[];
+}
+/**
+ * Create Visa payment instruction request
+ */
+interface CreateVisaInstructionRequest {
+    /** Payment amount */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Merchant information */
+    merchant: VisaMerchant;
+    /** Payment restrictions */
+    restrictions?: VisaRestrictions;
+    /** Expiration time in seconds (default: 900) */
+    expiresInSeconds?: number;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Visa payment instruction
+ */
+interface VisaPaymentInstruction {
+    /** Instruction ID */
+    instructionId: string;
+    /** Merchant reference */
+    merchantRef: string;
+    /** Payment amount */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Merchant information */
+    merchant: VisaMerchant;
+    /** Payment restrictions */
+    restrictions?: VisaRestrictions;
+    /** Instruction status */
+    status: string;
+    /** Expiration timestamp */
+    expiresAt: string;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Paginated list response
+ */
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+    };
+}
+/**
+ * Create Visa token request
+ */
+interface CreateVisaTokenRequest {
+    /** Payment instruction ID */
+    instructionId: string;
+    /** Card token */
+    cardToken: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Visa token
+ */
+interface VisaToken {
+    /** VTS token ID */
+    tokenId: string;
+    /** Instruction ID */
+    instructionId: string;
+    /** Last 4 digits of card */
+    cardLastFour: string;
+    /** Token status */
+    status: string;
+    /** Expiration timestamp */
+    expiresAt?: string;
+    /** Provisioned timestamp */
+    provisionedAt: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Register Mastercard agent request
+ */
+interface RegisterMastercardAgentRequest {
+    /** PayOS agent ID */
+    agentId: string;
+    /** Agent display name */
+    agentName?: string;
+    /** Agent's public key for signing */
+    publicKey: string;
+    /** Agent capabilities */
+    capabilities?: string[];
+    /** AI provider name */
+    provider?: string;
+    /** Callback URL for notifications */
+    callbackUrl?: string;
+}
+/**
+ * Mastercard agent registration
+ */
+interface MastercardAgentRegistration {
+    /** PayOS agent ID */
+    agentId: string;
+    /** Mastercard agent ID */
+    mcAgentId: string;
+    /** Agent display name */
+    agentName: string;
+    /** Agent's public key */
+    publicKey: string;
+    /** Agent capabilities */
+    capabilities: string[];
+    /** Registration status */
+    status: string;
+    /** AI provider name */
+    provider?: string;
+    /** Callback URL */
+    callbackUrl?: string;
+    /** Registration timestamp */
+    registeredAt: string;
+}
+/**
+ * Create Mastercard token request
+ */
+interface CreateMastercardTokenRequest {
+    /** PayOS agent ID */
+    agentId: string;
+    /** Card token */
+    cardToken: string;
+    /** Expiration time in seconds (default: 3600) */
+    expiresInSeconds?: number;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Mastercard agentic token
+ */
+interface MastercardToken {
+    /** Token reference */
+    tokenReference: string;
+    /** Mastercard agent ID */
+    mcAgentId: string;
+    /** Dynamic Transaction Verification Code */
+    dtvc: string;
+    /** Last 4 digits of card */
+    cardLastFour: string;
+    /** Token status */
+    status: string;
+    /** Expiration timestamp */
+    expiresAt: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Card network transaction
+ */
+interface CardTransaction {
+    id: string;
+    network: CardNetwork;
+    status: string;
+    amount: number;
+    currency: string;
+    merchantName?: string;
+    createdAt: string;
+}
+/**
+ * Network test result
+ */
+interface NetworkTestResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Network configure request
+ */
+interface ConfigureVisaRequest {
+    api_key: string;
+    shared_secret?: string;
+    sandbox?: boolean;
+}
+/**
+ * Network configure request
+ */
+interface ConfigureMastercardRequest {
+    consumer_key: string;
+    private_key_pem?: string;
+    sandbox?: boolean;
+}
+/**
+ * Configure result
+ */
+interface ConfigureResult {
+    id: string;
+    message: string;
+}
+/**
+ * Generate signing key request
+ */
+interface GenerateSigningKeyRequest {
+    /** Signing algorithm (default: ed25519) */
+    algorithm?: 'ed25519' | 'rsa-sha256';
+}
+/**
+ * Generated signing key result
+ */
+interface GenerateSigningKeyResult {
+    /** Public key identifier used in signatures */
+    keyId: string;
+    /** Base64 encoded public key */
+    publicKey: string;
+    /** Signing algorithm */
+    algorithm: 'ed25519' | 'rsa-sha256';
+    /** Key status */
+    status: 'active' | 'suspended' | 'revoked';
+    /** Networks where public key is registered */
+    registeredNetworks: string[];
+    /** When the key was created */
+    createdAt: string;
+}
+/**
+ * Signing key status result
+ */
+interface SigningKeyStatus {
+    /** Whether the agent has a signing key */
+    hasKey: boolean;
+    /** Public key identifier */
+    keyId?: string;
+    /** Base64 encoded public key */
+    publicKey?: string;
+    /** Signing algorithm */
+    algorithm?: 'ed25519' | 'rsa-sha256';
+    /** Key status */
+    status?: 'active' | 'suspended' | 'revoked';
+    /** Networks where public key is registered */
+    registeredNetworks?: string[];
+    /** Usage statistics */
+    stats?: {
+        useCount: number;
+        lastUsedAt?: string;
+    };
+    /** When the key was created */
+    createdAt?: string;
+}
+/**
+ * Payment information for signing request
+ */
+interface SigningPaymentInfo {
+    /** Payment amount */
+    amount: number;
+    /** Currency code (default: USD) */
+    currency?: string;
+    /** Merchant name for audit trail */
+    merchantName?: string;
+}
+/**
+ * Sign request input
+ */
+interface SignRequestInput {
+    /** HTTP method */
+    method: string;
+    /** Request path */
+    path: string;
+    /** Host header value */
+    host?: string;
+    /** Request headers (lowercase keys) */
+    headers?: Record<string, string>;
+    /** Request body */
+    body?: string;
+    /** Payment info for spending limit check */
+    payment?: SigningPaymentInfo;
+}
+/**
+ * Sign request result
+ */
+interface SignRequestResult {
+    /** The Signature-Input header value */
+    signatureInput: string;
+    /** The Signature header value */
+    signature: string;
+    /** The Content-Digest header value (if body was provided) */
+    contentDigest?: string;
+    /** All headers to add to the request */
+    headers: Record<string, string>;
+    /** When the signature expires */
+    expiresAt: string;
+    /** ID of the signing request for audit trail */
+    signingRequestId?: string;
+}
+/**
+ * Delete signing key result
+ */
+interface DeleteSigningKeyResult {
+    success: boolean;
+    message: string;
+    keyId: string;
+}
+
+/**
+ * Card Networks Module
+ *
+ * Provides SDK integration for Visa VIC and Mastercard Agent Pay
+ * for accepting payments from AI agents.
+ */
+
+/**
+ * Visa-specific operations
+ */
+declare class VisaClient {
+    private client;
+    constructor(client: SlyClient);
+    /**
+     * Create a Visa VIC payment instruction
+     */
+    createInstruction(params: CreateVisaInstructionRequest): Promise<VisaPaymentInstruction>;
+    /**
+     * Get a specific Visa payment instruction
+     */
+    getInstruction(instructionId: string): Promise<VisaPaymentInstruction>;
+    /**
+     * List Visa payment instructions
+     */
+    listInstructions(options?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<VisaPaymentInstruction>>;
+    /**
+     * Provision a VTS token for an instruction
+     */
+    createToken(params: CreateVisaTokenRequest): Promise<VisaToken>;
+    /**
+     * Get a specific Visa token
+     */
+    getToken(tokenId: string): Promise<VisaToken>;
+    /**
+     * List Visa tokens
+     */
+    listTokens(options?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<VisaToken>>;
+    /**
+     * Suspend a Visa token
+     */
+    suspendToken(tokenId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
+/**
+ * Mastercard-specific operations
+ */
+declare class MastercardClient {
+    private client;
+    constructor(client: SlyClient);
+    /**
+     * Register an agent with Mastercard Agent Pay
+     */
+    registerAgent(params: RegisterMastercardAgentRequest): Promise<MastercardAgentRegistration>;
+    /**
+     * Get a specific Mastercard agent registration
+     */
+    getAgent(agentId: string): Promise<MastercardAgentRegistration>;
+    /**
+     * List registered Mastercard agents
+     */
+    listAgents(): Promise<{
+        data: MastercardAgentRegistration[];
+    }>;
+    /**
+     * Create a Mastercard agentic token with DTVC
+     */
+    createToken(params: CreateMastercardTokenRequest): Promise<MastercardToken>;
+    /**
+     * Get a Mastercard token, optionally refreshing the DTVC
+     */
+    getToken(tokenReference: string, options?: {
+        refresh?: boolean;
+    }): Promise<MastercardToken>;
+    /**
+     * List Mastercard tokens
+     */
+    listTokens(options?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<MastercardToken>>;
+    /**
+     * Revoke a Mastercard token
+     */
+    revokeToken(tokenReference: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
+/**
+ * Cards Module - Main client for card network operations
+ *
+ * Provides unified access to:
+ * - Web Bot Auth signature verification
+ * - Network configuration and status
+ * - Visa VIC payment instructions and tokens
+ * - Mastercard Agent Pay registration and tokens
+ * - Analytics and transactions
+ */
+declare class CardsClient {
+    private client;
+    /** Visa-specific operations */
+    readonly visa: VisaClient;
+    /** Mastercard-specific operations */
+    readonly mastercard: MastercardClient;
+    constructor(client: SlyClient);
+    /**
+     * Verify an AI agent's Web Bot Auth signature
+     *
+     * @example
+     * ```typescript
+     * const result = await payos.cards.verifyAgentSignature({
+     *   method: 'POST',
+     *   path: '/checkout',
+     *   headers: req.headers,
+     *   signatureInput: req.headers['signature-input'],
+     *   signature: req.headers['signature'],
+     * });
+     *
+     * if (result.valid) {
+     *   console.log(`Verified ${result.network} agent from ${result.agentProvider}`);
+     * }
+     * ```
+     */
+    verifyAgentSignature(params: VerifyAgentSignatureRequest): Promise<VerifyAgentSignatureResult>;
+    /**
+     * Get configured card networks and their status
+     *
+     * @example
+     * ```typescript
+     * const { networks, capabilities } = await payos.cards.getNetworks();
+     *
+     * if (networks.visa.configured) {
+     *   console.log(`Visa: ${networks.visa.status}`);
+     * }
+     * ```
+     */
+    getNetworks(): Promise<CardNetworksResponse>;
+    /**
+     * Test connection to a card network
+     */
+    testNetwork(network: 'visa' | 'mastercard'): Promise<NetworkTestResult>;
+    /**
+     * Configure Visa VIC credentials
+     */
+    configureVisa(params: ConfigureVisaRequest): Promise<ConfigureResult>;
+    /**
+     * Configure Mastercard Agent Pay credentials
+     */
+    configureMastercard(params: ConfigureMastercardRequest): Promise<ConfigureResult>;
+    /**
+     * Disconnect a card network
+     */
+    disconnectNetwork(network: 'visa' | 'mastercard'): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Get comprehensive card network analytics
+     *
+     * @param days - Number of days to analyze (default: 30)
+     *
+     * @example
+     * ```typescript
+     * const analytics = await payos.cards.getAnalytics(30);
+     *
+     * console.log(`Success rate: ${analytics.verifications.successRate}%`);
+     * console.log(`Total volume: $${analytics.transactions.volume}`);
+     * ```
+     */
+    getAnalytics(days?: number): Promise<CardAnalyticsResponse>;
+    /**
+     * Get verification statistics
+     *
+     * @param days - Number of days to analyze (default: 30)
+     */
+    getVerificationStats(days?: number): Promise<VerificationStats>;
+    /**
+     * List card network transactions
+     */
+    listTransactions(options?: {
+        network?: 'visa' | 'mastercard';
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<CardTransaction>>;
+    /**
+     * Get a specific transaction
+     */
+    getTransaction(transactionId: string): Promise<CardTransaction>;
+    /**
+     * Generate a signing key for an agent
+     *
+     * Creates an Ed25519 or RSA-SHA256 key pair for the agent to sign
+     * payment requests according to RFC 9421 (HTTP Message Signatures).
+     *
+     * @example
+     * ```typescript
+     * const key = await payos.cards.generateSigningKey('agent_123');
+     * console.log(`Public key: ${key.publicKey}`);
+     * // Register this public key with card networks (Visa TAP, MC Agent Pay)
+     * ```
+     */
+    generateSigningKey(agentId: string, options?: GenerateSigningKeyRequest): Promise<GenerateSigningKeyResult>;
+    /**
+     * Get the signing key status for an agent
+     *
+     * @example
+     * ```typescript
+     * const status = await payos.cards.getSigningKey('agent_123');
+     * if (status.hasKey) {
+     *   console.log(`Key: ${status.keyId}, Uses: ${status.stats.useCount}`);
+     * }
+     * ```
+     */
+    getSigningKey(agentId: string): Promise<SigningKeyStatus>;
+    /**
+     * Revoke an agent's signing key
+     *
+     * After revocation, the agent will need a new key to sign requests.
+     */
+    revokeSigningKey(agentId: string): Promise<DeleteSigningKeyResult>;
+    /**
+     * Sign a payment request for an agent
+     *
+     * Signs an HTTP request according to RFC 9421 so the agent can
+     * authenticate with merchants and card networks.
+     *
+     * Requirements:
+     * - Agent must have KYA tier >= 1
+     * - Agent must be active
+     * - Agent must have a signing key
+     * - Payment must be within spending limits
+     *
+     * @example
+     * ```typescript
+     * // Sign a payment request
+     * const signed = await payos.cards.signRequest('agent_123', {
+     *   method: 'POST',
+     *   path: '/api/checkout',
+     *   host: 'merchant.com',
+     *   body: JSON.stringify({ items: [...], total: 99.99 }),
+     *   payment: {
+     *     amount: 99.99,
+     *     currency: 'USD',
+     *     merchantName: 'Acme Store',
+     *   },
+     * });
+     *
+     * // Agent uses signed headers to call merchant
+     * const response = await fetch('https://merchant.com/api/checkout', {
+     *   method: 'POST',
+     *   headers: {
+     *     ...signed.headers,
+     *     'Content-Type': 'application/json',
+     *   },
+     *   body: JSON.stringify({ items: [...], total: 99.99 }),
+     * });
+     * ```
+     */
+    signRequest(agentId: string, request: SignRequestInput): Promise<SignRequestResult>;
+}
+
+export { type CardAnalyticsResponse, type CardNetwork, type CardNetworksResponse, type CardTransaction, CardsClient, type ConfigureMastercardRequest, type ConfigureResult, type ConfigureVisaRequest, type CreateMastercardTokenRequest, type CreateVisaInstructionRequest, type CreateVisaTokenRequest, type DeleteSigningKeyResult, type GenerateSigningKeyRequest, type GenerateSigningKeyResult, type MastercardAgentRegistration, MastercardClient, type MastercardToken, type NetworkConfig, type NetworkStatus, type NetworkTestResult, type PaginatedResponse, type RecentTransaction, type RegisterMastercardAgentRequest, type SignRequestInput, type SignRequestResult, type SigningKeyStatus, type SigningPaymentInfo, type TransactionStats, type VerificationStats, type VerifyAgentSignatureRequest, type VerifyAgentSignatureResult, VisaClient, type VisaMerchant, type VisaPaymentInstruction, type VisaRestrictions, type VisaToken };