@alleyboss/micropay-solana-x402-paywall 2.3.0 → 2.3.1

package/dist/agent/index.d.cts

@@ -0,0 +1,212 @@
+import { Connection, Keypair } from '@solana/web3.js';
+import { P as PriorityFeeConfig } from '../priority-fees-C-OH4Trr.cjs';
+import { a as SessionConfig, S as SessionData } from '../session-D2IoWAWV.cjs';
+
+/** Parameters for executing an agent payment */
+interface ExecuteAgentPaymentParams {
+    /** Solana connection */
+    connection: Connection;
+    /** Agent's keypair (server-side only!) */
+    agentKeypair: Keypair;
+    /** Recipient wallet address (base58) */
+    recipientAddress: string;
+    /** Amount to send in lamports */
+    amountLamports: bigint;
+    /** Optional memo for the transaction */
+    memo?: string;
+    /** Optional priority fee configuration */
+    priorityFee?: PriorityFeeConfig;
+    /** Timeout for confirmation in ms (default: 60000) */
+    confirmationTimeout?: number;
+}
+/** Result of an agent payment execution */
+interface AgentPaymentResult {
+    /** Whether the payment was successful */
+    success: boolean;
+    /** Transaction signature (if successful) */
+    signature?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** Block time when confirmed (Unix timestamp) */
+    confirmedAt?: number;
+    /** Slot number */
+    slot?: number;
+    /** Amount sent in lamports */
+    amountLamports?: bigint;
+    /** Amount sent in SOL */
+    amountSol?: number;
+}
+/**
+ * Execute an autonomous SOL payment from the agent's wallet
+ *
+ * This is the core utility for AI agents to pay for x402-protected resources.
+ * The agent keypair must be loaded server-side only (never exposed to client).
+ *
+ * @example
+ * ```typescript
+ * import { executeAgentPayment } from '@alleyboss/micropay-solana-x402-paywall/agent';
+ * import { Keypair, Connection } from '@solana/web3.js';
+ * import bs58 from 'bs58';
+ *
+ * // Load agent keypair from environment (server-side only!)
+ * const agentKeypair = Keypair.fromSecretKey(
+ *   bs58.decode(process.env.AGENT_KEYPAIR_SECRET!)
+ * );
+ *
+ * const connection = new Connection('https://api.devnet.solana.com');
+ *
+ * const result = await executeAgentPayment({
+ *   connection,
+ *   agentKeypair,
+ *   recipientAddress: 'RecipientWallet...',
+ *   amountLamports: 20_000_000n, // 0.02 SOL
+ *   priorityFee: { enabled: true, microLamports: 5000 },
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Payment sent:', result.signature);
+ * }
+ * ```
+ */
+declare function executeAgentPayment(params: ExecuteAgentPaymentParams): Promise<AgentPaymentResult>;
+/**
+ * Get the agent wallet's SOL balance
+ */
+declare function getAgentBalance(connection: Connection, agentKeypair: Keypair): Promise<{
+    balance: bigint;
+    balanceSol: number;
+}>;
+/**
+ * Check if agent has sufficient balance for a payment
+ */
+declare function hasAgentSufficientBalance(connection: Connection, agentKeypair: Keypair, requiredLamports: bigint): Promise<{
+    sufficient: boolean;
+    balance: bigint;
+    required: bigint;
+}>;
+/**
+ * Create a Keypair from a base58-encoded secret key string
+ *
+ * @example
+ * ```typescript
+ * const keypair = keypairFromBase58(process.env.AGENT_KEYPAIR_SECRET!);
+ * ```
+ */
+declare function keypairFromBase58(base58Secret: string): Keypair;
+/**
+ * Create a new random Keypair for agent use
+ * Returns both the keypair and its base58-encoded secret for storage
+ */
+declare function generateAgentKeypair(): {
+    keypair: Keypair;
+    secretBase58: string;
+    publicKey: string;
+};
+
+/** Credit claims stored in session JWT */
+interface CreditSessionClaims {
+    /** Number of remaining credits */
+    credits: number;
+    /** Unix timestamp when bundle expires (optional) */
+    bundleExpiry?: number;
+    /** Bundle type identifier (e.g., 'starter', 'pro') */
+    bundleType?: string;
+}
+/** Extended session data with credit information */
+type CreditSessionData = SessionData & CreditSessionClaims;
+/** Configuration for credit sessions */
+interface CreditSessionConfig extends SessionConfig {
+    /** Initial number of credits */
+    initialCredits: number;
+    /** Bundle expiry in hours (optional, defaults to session duration) */
+    bundleExpiryHours?: number;
+    /** Bundle type identifier */
+    bundleType?: string;
+}
+/**
+ * Create a new credit session after bundle purchase
+ *
+ * @example
+ * ```typescript
+ * import { createCreditSession } from '@alleyboss/micropay-solana-x402-paywall/agent';
+ *
+ * const { token, session } = await createCreditSession(
+ *   walletAddress,
+ *   'bundle-purchase',
+ *   {
+ *     secret: process.env.SESSION_SECRET!,
+ *     durationHours: 24 * 30, // 30 days
+ *     initialCredits: 10,
+ *     bundleType: 'starter',
+ *   }
+ * );
+ *
+ * // Set as cookie
+ * response.cookies.set('x402_credits', token, { httpOnly: true });
+ * ```
+ */
+declare function createCreditSession(walletAddress: string, purchaseId: string, config: CreditSessionConfig): Promise<{
+    token: string;
+    session: CreditSessionData;
+}>;
+/** Result of validating a credit session */
+interface CreditValidation {
+    valid: boolean;
+    session?: CreditSessionData;
+    reason?: string;
+}
+/**
+ * Validate a credit session token
+ */
+declare function validateCreditSession(token: string, secret: string): Promise<CreditValidation>;
+/** Result of using a credit */
+interface UseCreditResult {
+    /** Whether the credit was successfully used */
+    success: boolean;
+    /** Remaining credits after use */
+    remainingCredits: number;
+    /** New token with decremented credits (if successful) */
+    newToken?: string;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Use one credit from the session
+ * Returns a new token with decremented credit count
+ *
+ * @example
+ * ```typescript
+ * import { useCredit } from '@alleyboss/micropay-solana-x402-paywall/agent';
+ *
+ * const result = await useCredit(token, process.env.SESSION_SECRET!);
+ *
+ * if (result.success) {
+ *   console.log(`Credit used. ${result.remainingCredits} remaining`);
+ *   // Update cookie with new token
+ *   response.cookies.set('x402_credits', result.newToken!);
+ * } else {
+ *   console.log('No credits:', result.error);
+ * }
+ * ```
+ */
+declare function useCredit(token: string, secret: string, creditsToUse?: number): Promise<UseCreditResult>;
+/**
+ * Add credits to an existing session
+ * Useful for top-ups or rewards
+ */
+declare function addCredits(token: string, secret: string, creditsToAdd: number): Promise<{
+    success: boolean;
+    newToken?: string;
+    totalCredits?: number;
+    error?: string;
+}>;
+/**
+ * Get remaining credits from a session token (quick check without full validation)
+ */
+declare function getRemainingCredits(token: string, secret: string): Promise<{
+    credits: number;
+    valid: boolean;
+    bundleExpiry?: number;
+}>;
+
+export { type AgentPaymentResult, type CreditSessionClaims, type CreditSessionConfig, type CreditSessionData, type CreditValidation, type ExecuteAgentPaymentParams, type UseCreditResult, addCredits, createCreditSession, executeAgentPayment, generateAgentKeypair, getAgentBalance, getRemainingCredits, hasAgentSufficientBalance, keypairFromBase58, useCredit, validateCreditSession };

package/dist/agent/index.d.ts

@@ -0,0 +1,212 @@
+import { Connection, Keypair } from '@solana/web3.js';
+import { P as PriorityFeeConfig } from '../priority-fees-C-OH4Trr.js';
+import { a as SessionConfig, S as SessionData } from '../session-D2IoWAWV.js';
+
+/** Parameters for executing an agent payment */
+interface ExecuteAgentPaymentParams {
+    /** Solana connection */
+    connection: Connection;
+    /** Agent's keypair (server-side only!) */
+    agentKeypair: Keypair;
+    /** Recipient wallet address (base58) */
+    recipientAddress: string;
+    /** Amount to send in lamports */
+    amountLamports: bigint;
+    /** Optional memo for the transaction */
+    memo?: string;
+    /** Optional priority fee configuration */
+    priorityFee?: PriorityFeeConfig;
+    /** Timeout for confirmation in ms (default: 60000) */
+    confirmationTimeout?: number;
+}
+/** Result of an agent payment execution */
+interface AgentPaymentResult {
+    /** Whether the payment was successful */
+    success: boolean;
+    /** Transaction signature (if successful) */
+    signature?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** Block time when confirmed (Unix timestamp) */
+    confirmedAt?: number;
+    /** Slot number */
+    slot?: number;
+    /** Amount sent in lamports */
+    amountLamports?: bigint;
+    /** Amount sent in SOL */
+    amountSol?: number;
+}
+/**
+ * Execute an autonomous SOL payment from the agent's wallet
+ *
+ * This is the core utility for AI agents to pay for x402-protected resources.
+ * The agent keypair must be loaded server-side only (never exposed to client).
+ *
+ * @example
+ * ```typescript
+ * import { executeAgentPayment } from '@alleyboss/micropay-solana-x402-paywall/agent';
+ * import { Keypair, Connection } from '@solana/web3.js';
+ * import bs58 from 'bs58';
+ *
+ * // Load agent keypair from environment (server-side only!)
+ * const agentKeypair = Keypair.fromSecretKey(
+ *   bs58.decode(process.env.AGENT_KEYPAIR_SECRET!)
+ * );
+ *
+ * const connection = new Connection('https://api.devnet.solana.com');
+ *
+ * const result = await executeAgentPayment({
+ *   connection,
+ *   agentKeypair,
+ *   recipientAddress: 'RecipientWallet...',
+ *   amountLamports: 20_000_000n, // 0.02 SOL
+ *   priorityFee: { enabled: true, microLamports: 5000 },
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Payment sent:', result.signature);
+ * }
+ * ```
+ */
+declare function executeAgentPayment(params: ExecuteAgentPaymentParams): Promise<AgentPaymentResult>;
+/**
+ * Get the agent wallet's SOL balance
+ */
+declare function getAgentBalance(connection: Connection, agentKeypair: Keypair): Promise<{
+    balance: bigint;
+    balanceSol: number;
+}>;
+/**
+ * Check if agent has sufficient balance for a payment
+ */
+declare function hasAgentSufficientBalance(connection: Connection, agentKeypair: Keypair, requiredLamports: bigint): Promise<{
+    sufficient: boolean;
+    balance: bigint;
+    required: bigint;
+}>;
+/**
+ * Create a Keypair from a base58-encoded secret key string
+ *
+ * @example
+ * ```typescript
+ * const keypair = keypairFromBase58(process.env.AGENT_KEYPAIR_SECRET!);
+ * ```
+ */
+declare function keypairFromBase58(base58Secret: string): Keypair;
+/**
+ * Create a new random Keypair for agent use
+ * Returns both the keypair and its base58-encoded secret for storage
+ */
+declare function generateAgentKeypair(): {
+    keypair: Keypair;
+    secretBase58: string;
+    publicKey: string;
+};
+
+/** Credit claims stored in session JWT */
+interface CreditSessionClaims {
+    /** Number of remaining credits */
+    credits: number;
+    /** Unix timestamp when bundle expires (optional) */
+    bundleExpiry?: number;
+    /** Bundle type identifier (e.g., 'starter', 'pro') */
+    bundleType?: string;
+}
+/** Extended session data with credit information */
+type CreditSessionData = SessionData & CreditSessionClaims;
+/** Configuration for credit sessions */
+interface CreditSessionConfig extends SessionConfig {
+    /** Initial number of credits */
+    initialCredits: number;
+    /** Bundle expiry in hours (optional, defaults to session duration) */
+    bundleExpiryHours?: number;
+    /** Bundle type identifier */
+    bundleType?: string;
+}
+/**
+ * Create a new credit session after bundle purchase
+ *
+ * @example
+ * ```typescript
+ * import { createCreditSession } from '@alleyboss/micropay-solana-x402-paywall/agent';
+ *
+ * const { token, session } = await createCreditSession(
+ *   walletAddress,
+ *   'bundle-purchase',
+ *   {
+ *     secret: process.env.SESSION_SECRET!,
+ *     durationHours: 24 * 30, // 30 days
+ *     initialCredits: 10,
+ *     bundleType: 'starter',
+ *   }
+ * );
+ *
+ * // Set as cookie
+ * response.cookies.set('x402_credits', token, { httpOnly: true });
+ * ```
+ */
+declare function createCreditSession(walletAddress: string, purchaseId: string, config: CreditSessionConfig): Promise<{
+    token: string;
+    session: CreditSessionData;
+}>;
+/** Result of validating a credit session */
+interface CreditValidation {
+    valid: boolean;
+    session?: CreditSessionData;
+    reason?: string;
+}
+/**
+ * Validate a credit session token
+ */
+declare function validateCreditSession(token: string, secret: string): Promise<CreditValidation>;
+/** Result of using a credit */
+interface UseCreditResult {
+    /** Whether the credit was successfully used */
+    success: boolean;
+    /** Remaining credits after use */
+    remainingCredits: number;
+    /** New token with decremented credits (if successful) */
+    newToken?: string;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Use one credit from the session
+ * Returns a new token with decremented credit count
+ *
+ * @example
+ * ```typescript
+ * import { useCredit } from '@alleyboss/micropay-solana-x402-paywall/agent';
+ *
+ * const result = await useCredit(token, process.env.SESSION_SECRET!);
+ *
+ * if (result.success) {
+ *   console.log(`Credit used. ${result.remainingCredits} remaining`);
+ *   // Update cookie with new token
+ *   response.cookies.set('x402_credits', result.newToken!);
+ * } else {
+ *   console.log('No credits:', result.error);
+ * }
+ * ```
+ */
+declare function useCredit(token: string, secret: string, creditsToUse?: number): Promise<UseCreditResult>;
+/**
+ * Add credits to an existing session
+ * Useful for top-ups or rewards
+ */
+declare function addCredits(token: string, secret: string, creditsToAdd: number): Promise<{
+    success: boolean;
+    newToken?: string;
+    totalCredits?: number;
+    error?: string;
+}>;
+/**
+ * Get remaining credits from a session token (quick check without full validation)
+ */
+declare function getRemainingCredits(token: string, secret: string): Promise<{
+    credits: number;
+    valid: boolean;
+    bundleExpiry?: number;
+}>;
+
+export { type AgentPaymentResult, type CreditSessionClaims, type CreditSessionConfig, type CreditSessionData, type CreditValidation, type ExecuteAgentPaymentParams, type UseCreditResult, addCredits, createCreditSession, executeAgentPayment, generateAgentKeypair, getAgentBalance, getRemainingCredits, hasAgentSufficientBalance, keypairFromBase58, useCredit, validateCreditSession };