{"_id":"@belacosaur/game-sdk","name":"@belacosaur/game-sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@belacosaur/game-sdk","version":"1.0.0","description":"Arcadia Game SDK for wallet integration and payment processing in Web3 games","main":"dist/esm/index.js","module":"dist/esm/index.js","browser":"dist/umd/arcadia-game-sdk.js","types":"dist/esm/index.d.ts","engines":{"node":">=20.0.0","npm":">=9.0.0"},"scripts":{"build":"rollup -c","build:watch":"rollup -c -w","build:prod":"rollup -c --environment NODE_ENV:production","type-check":"tsc --noEmit","lint":"eslint src --ext .ts"},"keywords":["arcadia","game-sdk","web3","solana","wallet","payments","gaming"],"author":{"name":"Arcadia"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/arcadia/game-sdk.git"},"devDependencies":{"@rollup/plugin-commonjs":"^28.0.1","@rollup/plugin-node-resolve":"^15.3.0","@rollup/plugin-terser":"^0.4.1","@rollup/plugin-typescript":"^12.1.0","@types/node":"^20.19.27","@typescript-eslint/eslint-plugin":"^6.19.0","@typescript-eslint/parser":"^6.19.0","eslint":"^8.56.0","rollup":"^4.21.0","typescript":"^5.9.3"},"_id":"@belacosaur/game-sdk@1.0.0","gitHead":"4046825f6683c5607467c907653896a1a097b922","bugs":{"url":"https://github.com/arcadia/game-sdk/issues"},"homepage":"https://github.com/arcadia/game-sdk#readme","_nodeVersion":"20.17.0","_npmVersion":"10.8.3","dist":{"integrity":"sha512-Mu33aK0oimXkdil4HYDWWU/SBE8Wza65RBVdOzBg3iwqx3AO7Zdxq42w7PrbHl+R0PmeVkRp2exlEIATLrM7AQ==","shasum":"3ba2cbb8e9cbf229fd8b4bb50ae1eba89bd2f4ca","tarball":"https://registry.npmjs.org/@belacosaur/game-sdk/-/game-sdk-1.0.0.tgz","fileCount":24,"unpackedSize":138652,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDXpH1mn33H736JQJS/1rFws/ejBpomRpBEIUYxGQcJbAIgNP0Z4oP9aSmnIvRQvfdCy3pdjbMwX5LDeHNHsThZZkw="}]},"_npmUser":{"name":"belacosaur","email":"calebjmartin@hotmail.com"},"directories":{},"maintainers":[{"name":"belacosaur","email":"calebjmartin@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/game-sdk_1.0.0_1766211887980_0.09278168045065849"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-20T06:24:47.916Z","1.0.0":"2025-12-20T06:24:48.143Z","modified":"2025-12-20T06:24:48.401Z"},"maintainers":[{"name":"belacosaur","email":"calebjmartin@hotmail.com"}],"description":"Arcadia Game SDK for wallet integration and payment processing in Web3 games","homepage":"https://github.com/arcadia/game-sdk#readme","keywords":["arcadia","game-sdk","web3","solana","wallet","payments","gaming"],"repository":{"type":"git","url":"git+https://github.com/arcadia/game-sdk.git"},"author":{"name":"Arcadia"},"bugs":{"url":"https://github.com/arcadia/game-sdk/issues"},"license":"MIT","readme":"# Arcadia Game SDK\r\n\r\nSDK for integrating Arcadia wallet and payment features into Web3 games. Enables games to access wallet addresses for account linking and process payments through the Arcadia platform.\r\n\r\n## Features\r\n\r\n- **Wallet Address Linking** - Get wallet address to use as user identifier\r\n- **Payment Processing** - Pay-to-play and in-game purchases via Solana/USDC\r\n- **Wallet Status** - Monitor wallet connection status\r\n- **Iframe Support** - Works seamlessly in iframe environments\r\n- **Zero Dependencies** - Minimal bundle size\r\n- **TypeScript Support** - Full type definitions included\r\n\r\n## Installation\r\n\r\n### NPM\r\n\r\n```bash\r\nnpm install @arcadia/game-sdk\r\n```\r\n\r\n### CDN\r\n\r\n```html\r\n<!-- Development -->\r\n<script src=\"https://cdn.arcadia.com/sdk/v1/arcadia-game-sdk.js\"></script>\r\n\r\n<!-- Production (Minified) -->\r\n<script src=\"https://cdn.arcadia.com/sdk/v1/arcadia-game-sdk.min.js\"></script>\r\n```\r\n\r\n## Quick Start\r\n\r\n### NPM Usage\r\n\r\n```typescript\r\nimport { ArcadiaSDK } from '@arcadia/game-sdk';\r\n\r\n// Initialize SDK\r\nconst arcadia = new ArcadiaSDK({\r\n  gameId: 'your-game-id',\r\n});\r\n\r\nawait arcadia.init();\r\n\r\n// Get wallet address (use as user ID)\r\nconst walletAddress = await arcadia.getWalletAddress();\r\n\r\nif (!walletAddress) {\r\n  console.log('Please connect your wallet in Arcadia');\r\n  return;\r\n}\r\n\r\n// Link save data to wallet address\r\nconst saveData = await loadSaveDataByWallet(walletAddress);\r\n\r\n// Pay to play\r\nconst result = await arcadia.payment.payToPlay(0.5, 'SOL');\r\nconsole.log('Payment successful:', result.txSignature);\r\n```\r\n\r\n### CDN Usage\r\n\r\n```html\r\n<!DOCTYPE html>\r\n<html>\r\n<head>\r\n  <script src=\"https://cdn.arcadia.com/sdk/v1/arcadia-game-sdk.min.js\"></script>\r\n</head>\r\n<body>\r\n  <script>\r\n    // Initialize SDK\r\n    const arcadia = new ArcadiaGameSDK({\r\n      gameId: 'your-game-id',\r\n    });\r\n\r\n    arcadia.init().then(async () => {\r\n      // Get wallet address\r\n      const walletAddress = await arcadia.getWalletAddress();\r\n      \r\n      if (!walletAddress) {\r\n        alert('Please connect your wallet in Arcadia');\r\n        return;\r\n      }\r\n\r\n      // Use wallet address as user ID\r\n      console.log('User wallet:', walletAddress);\r\n    });\r\n  </script>\r\n</body>\r\n</html>\r\n```\r\n\r\n## API Reference\r\n\r\n### Initialization\r\n\r\n#### `new ArcadiaSDK(config: SDKConfig)`\r\n\r\nCreate a new SDK instance.\r\n\r\n**Parameters:**\r\n- `config.gameId` (string, required) - Your unique game identifier\r\n- `config.parentOrigin` (string, optional) - Parent window origin for security (default: '*')\r\n- `config.timeout` (number, optional) - Request timeout in milliseconds (default: 30000)\r\n\r\n**Example:**\r\n```typescript\r\nconst arcadia = new ArcadiaSDK({\r\n  gameId: 'my-awesome-game',\r\n  parentOrigin: 'https://arcadia.com', // Optional: restrict to specific origin\r\n  timeout: 30000, // Optional: 30 second timeout\r\n});\r\n```\r\n\r\n#### `init(): Promise<void>`\r\n\r\nInitialize SDK and request initialization data from parent window. Call this after creating the SDK instance.\r\n\r\n**Example:**\r\n```typescript\r\nawait arcadia.init();\r\n```\r\n\r\n### Wallet Address\r\n\r\n#### `getWalletAddress(): Promise<string | null>`\r\n\r\nGet the connected wallet address. Use this as your user identifier and link all save data to it.\r\n\r\n**Returns:** Wallet address (string) or null if not connected\r\n\r\n**Example:**\r\n```typescript\r\nconst walletAddress = await arcadia.getWalletAddress();\r\n\r\nif (!walletAddress) {\r\n  // Wallet not connected\r\n  showMessage('Please connect your wallet');\r\n  return;\r\n}\r\n\r\n// Use wallet address as user ID\r\nconst userId = walletAddress;\r\nconst saveData = await loadSaveDataByWallet(walletAddress);\r\n```\r\n\r\n#### `isWalletConnected(): Promise<boolean>`\r\n\r\nCheck if wallet is currently connected.\r\n\r\n**Returns:** true if connected, false otherwise\r\n\r\n**Example:**\r\n```typescript\r\nconst connected = await arcadia.isWalletConnected();\r\nif (!connected) {\r\n  showMessage('Please connect your wallet');\r\n}\r\n```\r\n\r\n#### `onWalletChange(callback: (connected: boolean, address: string | null) => void): void`\r\n\r\nListen for wallet connection changes.\r\n\r\n**Example:**\r\n```typescript\r\narcadia.onWalletChange((connected, address) => {\r\n  if (!connected) {\r\n    // Wallet disconnected - pause game\r\n    pauseGame();\r\n    showMessage('Wallet disconnected. Please reconnect.');\r\n  } else {\r\n    // Wallet reconnected - resume game\r\n    resumeGame();\r\n  }\r\n});\r\n```\r\n\r\n#### `offWalletChange(callback: Function): void`\r\n\r\nRemove a wallet change listener.\r\n\r\n**Example:**\r\n```typescript\r\nconst callback = (connected, address) => { /* ... */ };\r\narcadia.onWalletChange(callback);\r\n// Later...\r\narcadia.offWalletChange(callback);\r\n```\r\n\r\n### Payments\r\n\r\n#### `payment.payToPlay(amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult>`\r\n\r\nProcess a pay-to-play payment (one-time payment to access game).\r\n\r\n**Parameters:**\r\n- `amount` (number) - Payment amount (must be > 0)\r\n- `token` ('SOL' | 'USDC') - Token type\r\n\r\n**Returns:** `PaymentResult` object with complete payment details:\r\n- `success` (boolean) - Whether payment was successful\r\n- `txSignature` (string) - Blockchain transaction signature (proof of payment)\r\n- `amount` (number) - Amount paid by user\r\n- `token` ('SOL' | 'USDC') - Token type used\r\n- `timestamp` (string) - ISO timestamp when payment completed\r\n- `purchaseId` (string, optional) - Arcadia purchase ID for tracking\r\n- `platformFee` (number, optional) - Platform fee deducted\r\n- `developerAmount` (number, optional) - Amount received by developer (after fees)\r\n\r\n**Example:**\r\n```typescript\r\ntry {\r\n  const result = await arcadia.payment.payToPlay(0.5, 'SOL');\r\n  \r\n  // All payment details are included - no need to query blockchain\r\n  console.log('Payment successful!');\r\n  console.log('Transaction:', result.txSignature);\r\n  console.log('Amount paid:', result.amount, result.token);\r\n  console.log('Completed at:', result.timestamp);\r\n  console.log('Purchase ID:', result.purchaseId);\r\n  console.log('Platform fee:', result.platformFee);\r\n  console.log('Developer receives:', result.developerAmount);\r\n  \r\n  // Store in your database for reference\r\n  await savePurchase({\r\n    txSignature: result.txSignature,\r\n    amount: result.amount,\r\n    token: result.token,\r\n    timestamp: result.timestamp,\r\n    purchaseId: result.purchaseId,\r\n  });\r\n  \r\n  // Start game\r\n  startGame();\r\n} catch (error) {\r\n  console.error('Payment failed:', error.message);\r\n  showError('Payment failed. Please try again.');\r\n}\r\n```\r\n\r\n#### `payment.purchaseItem(itemId: string, amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult>`\r\n\r\nPurchase an in-game item.\r\n\r\n**Parameters:**\r\n- `itemId` (string) - Unique item identifier\r\n- `amount` (number) - Payment amount (must be > 0)\r\n- `token` ('SOL' | 'USDC') - Token type\r\n\r\n**Returns:** `PaymentResult` object with complete payment details (see `payToPlay` for full field list)\r\n\r\n**Example:**\r\n```typescript\r\ntry {\r\n  const result = await arcadia.payment.purchaseItem('sword-001', 1.0, 'SOL');\r\n  \r\n  // All payment details included - verify and process\r\n  if (result.success && result.amount === 1.0 && result.token === 'SOL') {\r\n    // Payment verified - add item to inventory\r\n    addItemToInventory('sword-001');\r\n    \r\n    // Log purchase for analytics\r\n    logPurchase({\r\n      itemId: 'sword-001',\r\n      txSignature: result.txSignature,\r\n      amount: result.amount,\r\n      timestamp: result.timestamp,\r\n      purchaseId: result.purchaseId,\r\n    });\r\n  }\r\n} catch (error) {\r\n  console.error('Purchase failed:', error.message);\r\n  showError('Purchase failed. Please try again.');\r\n}\r\n```\r\n\r\n### Utility Methods\r\n\r\n#### `isInIframe(): boolean`\r\n\r\nCheck if SDK is running in an iframe environment.\r\n\r\n**Returns:** true if in iframe, false otherwise\r\n\r\n#### `isInitialized(): boolean`\r\n\r\nCheck if SDK has been initialized.\r\n\r\n**Returns:** true if initialized, false otherwise\r\n\r\n#### `getConfig(): SDKConfig`\r\n\r\nGet current SDK configuration.\r\n\r\n**Returns:** SDK configuration object\r\n\r\n#### `destroy(): void`\r\n\r\nCleanup SDK resources. Call this when game is unloaded.\r\n\r\n## Error Handling\r\n\r\nThe SDK throws specific error types for different scenarios:\r\n\r\n```typescript\r\nimport {\r\n  ArcadiaSDKError,\r\n  WalletNotConnectedError,\r\n  PaymentFailedError,\r\n  TimeoutError,\r\n  InvalidConfigError,\r\n  NotInIframeError,\r\n  InvalidAmountError,\r\n  InvalidTokenError,\r\n} from '@arcadia/game-sdk';\r\n\r\ntry {\r\n  await arcadia.payment.payToPlay(0.5, 'SOL');\r\n} catch (error) {\r\n  if (error instanceof WalletNotConnectedError) {\r\n    showMessage('Please connect your wallet');\r\n  } else if (error instanceof PaymentFailedError) {\r\n    showError('Payment failed: ' + error.message);\r\n  } else if (error instanceof TimeoutError) {\r\n    showError('Request timed out. Please try again.');\r\n  } else {\r\n    showError('An error occurred: ' + error.message);\r\n  }\r\n}\r\n```\r\n\r\n## Account Linking\r\n\r\n**Important:** Use wallet address as your user identifier.\r\n\r\n```typescript\r\n// Get wallet address\r\nconst walletAddress = await arcadia.getWalletAddress();\r\n\r\n// Link all save data to wallet address\r\nawait gameDatabase.save({\r\n  walletAddress: walletAddress,\r\n  level: 5,\r\n  score: 1000,\r\n  inventory: ['item1', 'item2'],\r\n});\r\n\r\n// Load save data by wallet address\r\nconst saveData = await gameDatabase.loadByWallet(walletAddress);\r\n```\r\n\r\n## Complete Example\r\n\r\n```typescript\r\nimport { ArcadiaSDK, WalletNotConnectedError, PaymentFailedError } from '@arcadia/game-sdk';\r\n\r\n// Initialize SDK\r\nconst arcadia = new ArcadiaSDK({\r\n  gameId: 'my-game-id',\r\n});\r\n\r\nawait arcadia.init();\r\n\r\n// Get wallet address\r\nconst walletAddress = await arcadia.getWalletAddress();\r\n\r\nif (!walletAddress) {\r\n  showMessage('Please connect your wallet in Arcadia to play');\r\n  return;\r\n}\r\n\r\n// Load save data\r\nlet saveData = await loadSaveDataByWallet(walletAddress);\r\nif (!saveData) {\r\n  // First time player\r\n  saveData = createNewSave(walletAddress);\r\n}\r\n\r\n// Handle pay-to-play if required\r\nif (gameRequiresPayment && !saveData.hasPaid) {\r\n  try {\r\n    const result = await arcadia.payment.payToPlay(0.5, 'SOL');\r\n    saveData.hasPaid = true;\r\n    await saveGameData(walletAddress, saveData);\r\n    startGame();\r\n  } catch (error) {\r\n    if (error instanceof WalletNotConnectedError) {\r\n      showMessage('Please connect your wallet');\r\n    } else if (error instanceof PaymentFailedError) {\r\n      showError('Payment failed: ' + error.message);\r\n    }\r\n    return;\r\n  }\r\n} else {\r\n  startGame();\r\n}\r\n\r\n// Listen for wallet changes\r\narcadia.onWalletChange((connected, address) => {\r\n  if (!connected) {\r\n    pauseGame();\r\n    showMessage('Wallet disconnected. Please reconnect.');\r\n  }\r\n});\r\n\r\n// Handle in-game purchases\r\nasync function buyItem(itemId: string, price: number) {\r\n  try {\r\n    const result = await arcadia.payment.purchaseItem(itemId, price, 'SOL');\r\n    saveData.inventory.push(itemId);\r\n    await saveGameData(walletAddress, saveData);\r\n    showSuccess('Item purchased!');\r\n  } catch (error) {\r\n    showError('Purchase failed: ' + error.message);\r\n  }\r\n}\r\n```\r\n\r\n## Browser Compatibility\r\n\r\n- Modern browsers (Chrome, Firefox, Safari, Edge)\r\n- ES2020 support required\r\n- postMessage API support\r\n- No polyfills needed\r\n\r\n## TypeScript\r\n\r\nFull TypeScript support is included. Types are automatically available when using the SDK.\r\n\r\n```typescript\r\nimport { ArcadiaSDK, SDKConfig, PaymentResult } from '@arcadia/game-sdk';\r\n\r\nconst config: SDKConfig = {\r\n  gameId: 'my-game',\r\n};\r\n\r\nconst arcadia = new ArcadiaSDK(config);\r\nconst result: PaymentResult = await arcadia.payment.payToPlay(0.5, 'SOL');\r\n```\r\n\r\n## Security\r\n\r\n- Wallet address only (never private keys)\r\n- All transactions signed in parent window\r\n- Origin validation for postMessage (configurable)\r\n- Request timeout prevents hanging\r\n- No sensitive data in messages\r\n\r\n## Support\r\n\r\nFor issues, questions, or contributions, please visit our [GitHub repository](https://github.com/arcadia/game-sdk) or contact support@arcadia.com.\r\n\r\n## License\r\n\r\nMIT\r\n\r\n","readmeFilename":"README.md","_rev":"1-333dc3652529c94a8421f736969983ea"}