{"_id":"@breeeve/solana-payment-core","_rev":"2-e84d804b020e5c2cd6890eff9a7b187f","name":"@breeeve/solana-payment-core","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@breeeve/solana-payment-core","version":"0.1.0","keywords":["solana","payment","blockchain","web3","cryptocurrency","usdc"],"author":{"name":"Breeeve"},"license":"MIT","_id":"@breeeve/solana-payment-core@0.1.0","maintainers":[{"name":"thejustinson","email":"joelnwachukwu67@gmail.com"}],"homepage":"https://github.com/thejustinson/solana-payment-core#readme","bugs":{"url":"https://github.com/thejustinson/solana-payment-core/issues"},"dist":{"shasum":"e68deee4aca76fffcfda2baaf47ee7e448fa8501","tarball":"https://registry.npmjs.org/@breeeve/solana-payment-core/-/solana-payment-core-0.1.0.tgz","fileCount":38,"integrity":"sha512-e/4HVNY0MZwTEU1Is9p2rDv+KS9wdFyZQlh3q1CgMc6Ew9gQKyDQM5/2d/+Wck3jY7hv0O7eazugpYp29hSrtw==","signatures":[{"sig":"MEUCIAhIUo7TjYne80rBU0+VbdMXQnTXO3axau8TkrazqhX9AiEAtY/RjhBP5W9JuH3ckrwflScZc0ip5JOezI/b5S1S8dE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51820},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.ts","test":"jest","build":"tsc","clean":"rimraf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"thejustinson","email":"joelnwachukwu67@gmail.com"},"repository":{"url":"git+https://github.com/thejustinson/solana-payment-core.git","type":"git"},"_npmVersion":"11.1.0","description":"Core functionality for Solana payment processing","directories":{},"_nodeVersion":"22.12.0","dependencies":{"@solana/web3.js":"^1.87.6","@solana/spl-token":"^0.3.9"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.56.0","rimraf":"^5.0.5","ts-jest":"^29.1.1","typescript":"^5.3.3","@types/bs58":"^4.0.4","@types/jest":"^29.5.11","@types/node":"^20.10.5","@typescript-eslint/parser":"^6.15.0","@typescript-eslint/eslint-plugin":"^6.15.0"},"peerDependencies":{"@solana/web3.js":"^1.87.6","@solana/spl-token":"^0.3.9"},"_npmOperationalInternal":{"tmp":"tmp/solana-payment-core_0.1.0_1745337931118_0.19002773673256868","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@breeeve/solana-payment-core","version":"0.2.0","description":"A TypeScript library for processing Solana payments using temporary wallets","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","test":"jest","prepare":"npm run build"},"keywords":["solana","blockchain","payment","wallet","temporary-wallet","solana-payment-core","USDC"],"author":{"name":"Breeeve"},"license":"MIT","dependencies":{"@solana/spl-token":"^0.3.9","@solana/web3.js":"^1.87.6"},"devDependencies":{"@types/jest":"^29.5.11","@types/node":"^20.10.5","jest":"^29.7.0","ts-jest":"^29.1.1","typescript":"^5.3.3"},"publishConfig":{"access":"public"},"_id":"@breeeve/solana-payment-core@0.2.0","gitHead":"3d1557221d4ebcdec4e9c61af368982277aaf98e","_nodeVersion":"22.12.0","_npmVersion":"11.1.0","dist":{"integrity":"sha512-5nSpYF5XbveSbu6Oh+ofiCSmlxYhvDBhV5nc5wIbS/ecOW5lZaBWpEo1PWGC+7O1ymGI9LeqGMqdKsnhuZsicg==","shasum":"3d9de149b92ec951cfb16fc5df852a9e436e473b","tarball":"https://registry.npmjs.org/@breeeve/solana-payment-core/-/solana-payment-core-0.2.0.tgz","fileCount":11,"unpackedSize":31792,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGz4SK6ll87vbzk6+1t5TamShekZLcA63SoSeFqdnMdwAiEAjsgJeeDWKIdM3u4Sm2TYq+PpeCr2AzlW5rV2tyY7G/A="}]},"_npmUser":{"name":"thejustinson","email":"joelnwachukwu67@gmail.com"},"directories":{},"maintainers":[{"name":"thejustinson","email":"joelnwachukwu67@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/solana-payment-core_0.2.0_1745422991825_0.001121683452005362"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-22T16:05:31.038Z","modified":"2025-04-23T15:43:12.217Z","0.1.0":"2025-04-22T16:05:31.358Z","0.2.0":"2025-04-23T15:43:11.992Z"},"author":{"name":"Breeeve"},"license":"MIT","keywords":["solana","blockchain","payment","wallet","temporary-wallet","solana-payment-core","USDC"],"description":"A TypeScript library for processing Solana payments using temporary wallets","maintainers":[{"name":"thejustinson","email":"joelnwachukwu67@gmail.com"}],"readme":"# @breeeve/solana-payment-core\r\n\r\nA TypeScript library for processing Solana payments using temporary wallets. This package provides a secure and efficient way to handle payments by creating temporary wallets for receiving payments and forwarding them to a seller's address.\r\n\r\n## Features\r\n\r\n- 🔒 Secure payment processing using temporary wallets\r\n- 💰 Automatic gas fee management\r\n- 💸 Automatic refund of remaining SOL\r\n- ⏱️ Configurable payment window\r\n- 🔄 Automatic payment status checking\r\n- 📊 Detailed payment state tracking\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @breeeve/solana-payment-core\r\n```\r\n\r\n## Usage\r\n\r\n### Basic Setup\r\n\r\n```typescript\r\nimport { Connection, Keypair } from '@solana/web3.js';\r\nimport { createPaymentProcessor, PaymentConfig } from '@breeeve/solana-payment-core';\r\n\r\n// Create a connection to Solana network\r\nconst connection = new Connection('https://api.devnet.solana.com');\r\n\r\n// Configure the payment processor\r\nconst config: PaymentConfig = {\r\n  sellerAddress: '9RKnB9eWaBxX33spWTLm2333nE5QXgWfaC8BoS5Cj9Pf',\r\n  amount: 1, // 1 USDC\r\n  paymentWindow: 5 * 60, // 5 minutes\r\n  pollingInterval: 5000 // 5 seconds\r\n};\r\n\r\n// Create a funding wallet (required for gas fees)\r\nconst fundingWalletPrivateKey = process.env.FUNDING_WALLET_PRIVATE_KEY;\r\nconst privateKeyBytes = new Uint8Array(JSON.parse(fundingWalletPrivateKey));\r\nconst fundingWallet = Keypair.fromSecretKey(privateKeyBytes);\r\n\r\n// Create the payment processor\r\nconst paymentProcessor = createPaymentProcessor(connection, config, fundingWallet);\r\n```\r\n\r\n### Starting a Payment Flow\r\n\r\n```typescript\r\n// Start a new payment flow\r\nawait paymentProcessor.startPaymentFlow();\r\n\r\n// Get the temporary wallet address\r\nconst state = paymentProcessor.getState();\r\nconst tempWalletAddress = state.tempWallet?.publicKey.toString();\r\n```\r\n\r\n### Checking Payment Status\r\n\r\n```typescript\r\n// Check payment status\r\nconst result = await paymentProcessor.checkPaymentStatus();\r\nconsole.log(`Token balance: ${result.tokenBalance}`);\r\nconsole.log(`SOL balance: ${result.solBalance}`);\r\nconsole.log(`Needs gas: ${result.needsGas}`);\r\n\r\n// If gas is needed, fund it\r\nif (result.needsGas) {\r\n  const fundingResult = await paymentProcessor.fundGasFee();\r\n  console.log(`Gas funded: ${fundingResult.success}`);\r\n}\r\n```\r\n\r\n### Processing Payment\r\n\r\n```typescript\r\n// If payment is received, process it\r\nif (state.status === 'received') {\r\n  const paymentResult = await paymentProcessor.processPayment();\r\n  console.log(`Payment processed: ${paymentResult.success}`);\r\n  console.log(`Transaction signature: ${paymentResult.txSignature}`);\r\n}\r\n```\r\n\r\n### React Integration Example\r\n\r\n```typescript\r\nimport { useEffect, useState } from 'react';\r\nimport { Connection, Keypair } from '@solana/web3.js';\r\nimport { createPaymentProcessor, PaymentConfig, PaymentState } from '@breeeve/solana-payment-core';\r\n\r\nfunction PaymentComponent() {\r\n  const [state, setState] = useState<PaymentState | null>(null);\r\n  const [processor, setProcessor] = useState<any>(null);\r\n  \r\n  useEffect(() => {\r\n    const connection = new Connection('https://api.devnet.solana.com');\r\n    const config: PaymentConfig = {\r\n      sellerAddress: '9RKnB9eWaBxX33spWTLm2333nE5QXgWfaC8BoS5Cj9Pf',\r\n      amount: 1\r\n    };\r\n    \r\n    // Initialize funding wallet from environment variable\r\n    const fundingWalletPrivateKey = process.env.NEXT_PUBLIC_FUNDING_WALLET_PRIVATE_KEY;\r\n    const privateKeyBytes = new Uint8Array(JSON.parse(fundingWalletPrivateKey));\r\n    const fundingWallet = Keypair.fromSecretKey(privateKeyBytes);\r\n    \r\n    const paymentProcessor = createPaymentProcessor(connection, config, fundingWallet);\r\n    setProcessor(paymentProcessor);\r\n    setState(paymentProcessor.getState());\r\n  }, []);\r\n  \r\n  const startPayment = async () => {\r\n    if (!processor) return;\r\n    await processor.startPaymentFlow();\r\n    setState(processor.getState());\r\n  };\r\n  \r\n  const checkStatus = async () => {\r\n    if (!processor) return;\r\n    const result = await processor.checkPaymentStatus();\r\n    setState(processor.getState());\r\n    \r\n    if (result.needsGas) {\r\n      await processor.fundGasFee();\r\n    }\r\n    \r\n    if (processor.getState().status === 'received') {\r\n      await processor.processPayment();\r\n      setState(processor.getState());\r\n    }\r\n  };\r\n  \r\n  return (\r\n    <div>\r\n      <h1>Payment Status: {state?.status}</h1>\r\n      {state?.tempWallet && (\r\n        <div>\r\n          <p>Temp Wallet Address: {state.tempWallet.publicKey.toString()}</p>\r\n          <p>Token Balance: {state.tokenBalance}</p>\r\n          <p>SOL Balance: {state.balance}</p>\r\n        </div>\r\n      )}\r\n      <button onClick={startPayment}>Start Payment</button>\r\n      <button onClick={checkStatus}>Check Status</button>\r\n    </div>\r\n  );\r\n}\r\n```\r\n\r\n## API Reference\r\n\r\n### Types\r\n\r\n#### `PaymentConfig`\r\n```typescript\r\ninterface PaymentConfig {\r\n  sellerAddress: string;\r\n  amount: number;\r\n  paymentWindow?: number; // in seconds\r\n  pollingInterval?: number; // in milliseconds\r\n}\r\n```\r\n\r\n#### `PaymentState`\r\n```typescript\r\ninterface PaymentState {\r\n  tempWallet: Keypair | null;\r\n  timeLeft: number;\r\n  status: PaymentStatus;\r\n  balance: number;\r\n  tokenBalance: number;\r\n  previousTokenBalance: number;\r\n  txSignature?: string;\r\n  error?: string;\r\n}\r\n```\r\n\r\n#### `PaymentStatus`\r\n```typescript\r\ntype PaymentStatus = 'setup' | 'waiting' | 'received' | 'forwarding' | 'forwarded' | 'expired';\r\n```\r\n\r\n### Methods\r\n\r\n#### `createPaymentProcessor(connection, config, fundingWallet?)`\r\nCreates a new payment processor instance.\r\n\r\n- `connection`: Solana Connection instance\r\n- `config`: Payment configuration\r\n- `fundingWallet`: Keypair for funding gas fees (required)\r\n\r\n#### `PaymentProcessor`\r\n\r\n- `getState()`: Get the current payment state\r\n- `startPaymentFlow()`: Start a new payment flow\r\n- `resetFlow()`: Reset the payment flow\r\n- `checkPaymentStatus()`: Check the current payment status\r\n- `processPayment()`: Process the payment if received\r\n- `fundGasFee()`: Fund gas fees for the temporary wallet\r\n- `refundRemainingSol()`: Refund remaining SOL to the funding wallet\r\n\r\n## Security Considerations\r\n\r\n1. Always store the funding wallet's private key securely in environment variables\r\n2. Never expose the private key in client-side code\r\n3. Use appropriate network endpoints (devnet/mainnet) for your use case\r\n4. Monitor payment windows and handle expired payments appropriately\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Support\r\n\r\nFor support, please open an issue in the GitHub repository or contact the maintainers. ","readmeFilename":"README.md"}