npm - @arcadiasol/game-sdk - Versions diffs - 1.0.0 → 1.1.0 - Mend

@arcadiasol/game-sdk 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md +63 -382
package/dist/esm/api-client.d.ts +54 -0
package/dist/esm/api-client.d.ts.map +1 -0
package/dist/esm/index.d.ts +1 -0
package/dist/esm/index.d.ts.map +1 -1
package/dist/esm/index.js +410 -98
package/dist/esm/index.js.map +1 -1
package/dist/esm/payment.d.ts +12 -3
package/dist/esm/payment.d.ts.map +1 -1
package/dist/esm/sdk.d.ts +2 -1
package/dist/esm/sdk.d.ts.map +1 -1
package/dist/esm/types.d.ts +16 -6
package/dist/esm/types.d.ts.map +1 -1
package/dist/esm/wallet.d.ts +4 -2
package/dist/esm/wallet.d.ts.map +1 -1
package/dist/umd/arcadia-game-sdk.js +410 -97
package/dist/umd/arcadia-game-sdk.js.map +1 -1
package/dist/umd/arcadia-game-sdk.min.js +1 -1
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,458 +1,139 @@
 # Arcadia Game SDK
-SDK 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.
+SDK for integrating Arcadia wallet and payment features into Web3 games.
 ## Features
-- **Wallet Address Linking** - Get wallet address to use as user identifier
-- **Payment Processing** - Pay-to-play and in-game purchases via Solana/USDC
-- **Wallet Status** - Monitor wallet connection status
-- **Iframe Support** - Works seamlessly in iframe environments
-- **Zero Dependencies** - Minimal bundle size
-- **TypeScript Support** - Full type definitions included
+- ✅ **Wallet Integration** - Get wallet address, check connection status
+- ✅ **Payment Processing** - Pay-to-play and in-game purchases
+- ✅ **Iframe Support** - Works seamlessly in Arcadia iframes
+- ✅ **Non-Iframe Support** - Works with direct API calls for native apps
+- ✅ **Stats Tracking** - Track playtime and online status (non-iframe mode)
 ## Installation
 ### NPM
 ```bash
-npm install @arcadia/game-sdk
+npm install @arcadiasol/game-sdk
 ```
 ### CDN
 ```html
-<!-- Development -->
-<script src="https://cdn.arcadia.com/sdk/v1/arcadia-game-sdk.js"></script>
-<!-- Production (Minified) -->
-<script src="https://cdn.arcadia.com/sdk/v1/arcadia-game-sdk.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@arcadiasol/game-sdk@latest/dist/umd/arcadia-game-sdk.js"></script>
 ```
 ## Quick Start
-### NPM Usage
+### Iframe Mode (Web Games)
 ```typescript
-import { ArcadiaSDK } from '@arcadia/game-sdk';
+import ArcadiaSDK from '@arcadiasol/game-sdk';
-// Initialize SDK
 const arcadia = new ArcadiaSDK({
   gameId: 'your-game-id',
 });
 await arcadia.init();
-// Get wallet address (use as user ID)
+// Get wallet address
 const walletAddress = await arcadia.getWalletAddress();
-if (!walletAddress) {
-  console.log('Please connect your wallet in Arcadia');
-  return;
-}
-// Link save data to wallet address
-const saveData = await loadSaveDataByWallet(walletAddress);
 // Pay to play
-const result = await arcadia.payment.payToPlay(0.5, 'SOL');
-console.log('Payment successful:', result.txSignature);
-```
-### CDN Usage
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <script src="https://cdn.arcadia.com/sdk/v1/arcadia-game-sdk.min.js"></script>
-</head>
-<body>
-  <script>
-    // Initialize SDK
-    const arcadia = new ArcadiaGameSDK({
-      gameId: 'your-game-id',
-    });
-    arcadia.init().then(async () => {
-      // Get wallet address
-      const walletAddress = await arcadia.getWalletAddress();
-      if (!walletAddress) {
-        alert('Please connect your wallet in Arcadia');
-        return;
-      }
-      // Use wallet address as user ID
-      console.log('User wallet:', walletAddress);
-    });
-  </script>
-</body>
-</html>
+const result = await arcadia.payment.payToPlay(0.1, 'SOL');
 ```
-## API Reference
-### Initialization
-#### `new ArcadiaSDK(config: SDKConfig)`
-Create a new SDK instance.
+### Non-Iframe Mode (Native Apps / External Games)
-**Parameters:**
-- `config.gameId` (string, required) - Your unique game identifier
-- `config.parentOrigin` (string, optional) - Parent window origin for security (default: '*')
-- `config.timeout` (number, optional) - Request timeout in milliseconds (default: 30000)
-**Example:**
 ```typescript
+import ArcadiaSDK from '@arcadiasol/game-sdk';
 const arcadia = new ArcadiaSDK({
-  gameId: 'my-awesome-game',
-  parentOrigin: 'https://arcadia.com', // Optional: restrict to specific origin
-  timeout: 30000, // Optional: 30 second timeout
+  gameId: 'your-game-id',
+  apiBaseURL: 'https://arcadia.com', // Required for non-iframe
+  authToken: 'your-auth-token', // Optional: if you have auth token
+  walletAddress: 'your-wallet-address', // Optional: if you know wallet address
 });
-```
-#### `init(): Promise<void>`
-Initialize SDK and request initialization data from parent window. Call this after creating the SDK instance.
-**Example:**
-```typescript
 await arcadia.init();
-```
-### Wallet Address
-#### `getWalletAddress(): Promise<string | null>`
-Get the connected wallet address. Use this as your user identifier and link all save data to it.
-**Returns:** Wallet address (string) or null if not connected
-**Example:**
-```typescript
+// Get wallet address
 const walletAddress = await arcadia.getWalletAddress();
-if (!walletAddress) {
-  // Wallet not connected
-  showMessage('Please connect your wallet');
-  return;
-}
-// Use wallet address as user ID
-const userId = walletAddress;
-const saveData = await loadSaveDataByWallet(walletAddress);
-```
-#### `isWalletConnected(): Promise<boolean>`
-Check if wallet is currently connected.
-**Returns:** true if connected, false otherwise
-**Example:**
-```typescript
-const connected = await arcadia.isWalletConnected();
-if (!connected) {
-  showMessage('Please connect your wallet');
-}
-```
-#### `onWalletChange(callback: (connected: boolean, address: string | null) => void): void`
-Listen for wallet connection changes.
-**Example:**
-```typescript
-arcadia.onWalletChange((connected, address) => {
-  if (!connected) {
-    // Wallet disconnected - pause game
-    pauseGame();
-    showMessage('Wallet disconnected. Please reconnect.');
-  } else {
-    // Wallet reconnected - resume game
-    resumeGame();
-  }
-});
-```
-#### `offWalletChange(callback: Function): void`
-Remove a wallet change listener.
-**Example:**
-```typescript
-const callback = (connected, address) => { /* ... */ };
-arcadia.onWalletChange(callback);
-// Later...
-arcadia.offWalletChange(callback);
-```
-### Payments
-#### `payment.payToPlay(amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult>`
-Process a pay-to-play payment (one-time payment to access game).
-**Parameters:**
-- `amount` (number) - Payment amount (must be > 0)
-- `token` ('SOL' | 'USDC') - Token type
-**Returns:** `PaymentResult` object with complete payment details:
-- `success` (boolean) - Whether payment was successful
-- `txSignature` (string) - Blockchain transaction signature (proof of payment)
-- `amount` (number) - Amount paid by user
-- `token` ('SOL' | 'USDC') - Token type used
-- `timestamp` (string) - ISO timestamp when payment completed
-- `purchaseId` (string, optional) - Arcadia purchase ID for tracking
-- `platformFee` (number, optional) - Platform fee deducted
-- `developerAmount` (number, optional) - Amount received by developer (after fees)
-**Example:**
-```typescript
-try {
-  const result = await arcadia.payment.payToPlay(0.5, 'SOL');
-  // All payment details are included - no need to query blockchain
-  console.log('Payment successful!');
-  console.log('Transaction:', result.txSignature);
-  console.log('Amount paid:', result.amount, result.token);
-  console.log('Completed at:', result.timestamp);
-  console.log('Purchase ID:', result.purchaseId);
-  console.log('Platform fee:', result.platformFee);
-  console.log('Developer receives:', result.developerAmount);
-  // Store in your database for reference
-  await savePurchase({
-    txSignature: result.txSignature,
-    amount: result.amount,
-    token: result.token,
-    timestamp: result.timestamp,
-    purchaseId: result.purchaseId,
-  });
-  // Start game
-  startGame();
-} catch (error) {
-  console.error('Payment failed:', error.message);
-  showError('Payment failed. Please try again.');
-}
-```
-#### `payment.purchaseItem(itemId: string, amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult>`
-Purchase an in-game item.
+// Track playtime
+await arcadia.stats.updatePlaytime(1.5, 'playing');
-**Parameters:**
-- `itemId` (string) - Unique item identifier
-- `amount` (number) - Payment amount (must be > 0)
-- `token` ('SOL' | 'USDC') - Token type
+// Update online status
+await arcadia.stats.updateOnlineStatus(true);
-**Returns:** `PaymentResult` object with complete payment details (see `payToPlay` for full field list)
-**Example:**
-```typescript
-try {
-  const result = await arcadia.payment.purchaseItem('sword-001', 1.0, 'SOL');
-  // All payment details included - verify and process
-  if (result.success && result.amount === 1.0 && result.token === 'SOL') {
-    // Payment verified - add item to inventory
-    addItemToInventory('sword-001');
-    // Log purchase for analytics
-    logPurchase({
-      itemId: 'sword-001',
-      txSignature: result.txSignature,
-      amount: result.amount,
-      timestamp: result.timestamp,
-      purchaseId: result.purchaseId,
-    });
-  }
-} catch (error) {
-  console.error('Purchase failed:', error.message);
-  showError('Purchase failed. Please try again.');
-}
+// Pay to play (requires transaction signature)
+// Note: You must sign the transaction yourself in non-iframe mode
+const txSignature = await signTransaction(...); // Your signing logic
+const result = await arcadia.payment.payToPlay(0.1, 'SOL', txSignature);
 ```
-### Utility Methods
-#### `isInIframe(): boolean`
-Check if SDK is running in an iframe environment.
-**Returns:** true if in iframe, false otherwise
-#### `isInitialized(): boolean`
-Check if SDK has been initialized.
-**Returns:** true if initialized, false otherwise
-#### `getConfig(): SDKConfig`
-Get current SDK configuration.
-**Returns:** SDK configuration object
-#### `destroy(): void`
-Cleanup SDK resources. Call this when game is unloaded.
-## Error Handling
+## API Reference
-The SDK throws specific error types for different scenarios:
+### Constructor
 ```typescript
-import {
-  ArcadiaSDKError,
-  WalletNotConnectedError,
-  PaymentFailedError,
-  TimeoutError,
-  InvalidConfigError,
-  NotInIframeError,
-  InvalidAmountError,
-  InvalidTokenError,
-} from '@arcadia/game-sdk';
-try {
-  await arcadia.payment.payToPlay(0.5, 'SOL');
-} catch (error) {
-  if (error instanceof WalletNotConnectedError) {
-    showMessage('Please connect your wallet');
-  } else if (error instanceof PaymentFailedError) {
-    showError('Payment failed: ' + error.message);
-  } else if (error instanceof TimeoutError) {
-    showError('Request timed out. Please try again.');
-  } else {
-    showError('An error occurred: ' + error.message);
-  }
-}
+new ArcadiaSDK(config: SDKConfig)
 ```
-## Account Linking
+**Config Options:**
+- `gameId` (string, required) - Your game identifier
+- `parentOrigin` (string, optional) - Parent window origin for iframe security
+- `timeout` (number, optional) - Request timeout in milliseconds (default: 30000)
+- `apiBaseURL` (string, optional) - Base URL for API calls (required for non-iframe)
+- `authToken` (string, optional) - Pre-authenticated token (non-iframe mode)
+- `walletAddress` (string, optional) - Wallet address (non-iframe mode)
-**Important:** Use wallet address as your user identifier.
-```typescript
-// Get wallet address
-const walletAddress = await arcadia.getWalletAddress();
+### Methods
-// Link all save data to wallet address
-await gameDatabase.save({
-  walletAddress: walletAddress,
-  level: 5,
-  score: 1000,
-  inventory: ['item1', 'item2'],
-});
+#### `init(): Promise<void>`
-// Load save data by wallet address
-const saveData = await gameDatabase.loadByWallet(walletAddress);
-```
+Initialize SDK. Must be called after creating SDK instance.
-## Complete Example
+#### `getWalletAddress(): Promise<string | null>`
-```typescript
-import { ArcadiaSDK, WalletNotConnectedError, PaymentFailedError } from '@arcadia/game-sdk';
+Get connected wallet address. Returns `null` if not connected.
-// Initialize SDK
-const arcadia = new ArcadiaSDK({
-  gameId: 'my-game-id',
-});
+#### `isWalletConnected(): Promise<boolean>`
-await arcadia.init();
+Check if wallet is connected.
-// Get wallet address
-const walletAddress = await arcadia.getWalletAddress();
+#### `onWalletChange(callback: Function): void`
-if (!walletAddress) {
-  showMessage('Please connect your wallet in Arcadia to play');
-  return;
-}
-// Load save data
-let saveData = await loadSaveDataByWallet(walletAddress);
-if (!saveData) {
-  // First time player
-  saveData = createNewSave(walletAddress);
-}
-// Handle pay-to-play if required
-if (gameRequiresPayment && !saveData.hasPaid) {
-  try {
-    const result = await arcadia.payment.payToPlay(0.5, 'SOL');
-    saveData.hasPaid = true;
-    await saveGameData(walletAddress, saveData);
-    startGame();
-  } catch (error) {
-    if (error instanceof WalletNotConnectedError) {
-      showMessage('Please connect your wallet');
-    } else if (error instanceof PaymentFailedError) {
-      showError('Payment failed: ' + error.message);
-    }
-    return;
-  }
-} else {
-  startGame();
-}
-// Listen for wallet changes
-arcadia.onWalletChange((connected, address) => {
-  if (!connected) {
-    pauseGame();
-    showMessage('Wallet disconnected. Please reconnect.');
-  }
-});
+Listen for wallet connection changes.
-// Handle in-game purchases
-async function buyItem(itemId: string, price: number) {
-  try {
-    const result = await arcadia.payment.purchaseItem(itemId, price, 'SOL');
-    saveData.inventory.push(itemId);
-    await saveGameData(walletAddress, saveData);
-    showSuccess('Item purchased!');
-  } catch (error) {
-    showError('Purchase failed: ' + error.message);
-  }
-}
-```
+#### `payment.payToPlay(amount, token, txSignature?)`
-## Browser Compatibility
+Pay to play. `txSignature` required for non-iframe mode.
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- ES2020 support required
-- postMessage API support
-- No polyfills needed
+#### `payment.purchaseItem(itemId, amount, token, txSignature?)`
-## TypeScript
+Purchase in-game item. `txSignature` required for non-iframe mode.
-Full TypeScript support is included. Types are automatically available when using the SDK.
+#### `stats.updatePlaytime(hours, status?)`
-```typescript
-import { ArcadiaSDK, SDKConfig, PaymentResult } from '@arcadia/game-sdk';
+Update playtime (non-iframe mode only).
-const config: SDKConfig = {
-  gameId: 'my-game',
-};
+#### `stats.updateOnlineStatus(isOnline)`
-const arcadia = new ArcadiaSDK(config);
-const result: PaymentResult = await arcadia.payment.payToPlay(0.5, 'SOL');
-```
+Update online status (non-iframe mode only).
-## Security
+## Environment Detection
-- Wallet address only (never private keys)
-- All transactions signed in parent window
-- Origin validation for postMessage (configurable)
-- Request timeout prevents hanging
-- No sensitive data in messages
+The SDK automatically detects if it's running in an iframe:
-## Support
+- **Iframe Mode**: Uses `postMessage` for communication
+- **Non-Iframe Mode**: Uses REST API calls (requires `apiBaseURL`)
-For issues, questions, or contributions, please visit our [GitHub repository](https://github.com/arcadia/game-sdk) or contact support@arcadia.com.
+## Examples
-## License
+See `/examples` directory for complete examples.
-MIT
+## Documentation
+Full documentation: https://docs.arcadia.com/sdk

package/dist/esm/api-client.d.ts ADDED Viewed

@@ -0,0 +1,54 @@
+import { PaymentRequest, PaymentResponse, WalletAddressResponse } from './types';
+/**
+ * API Client for non-iframe environments
+ * Handles direct REST API calls when SDK is not running in iframe
+ */
+export declare class APIClient {
+    private baseURL;
+    private authToken;
+    private walletAddress;
+    constructor(baseURL?: string);
+    /**
+     * Detect Arcadia base URL from environment or use default
+     */
+    private detectBaseURL;
+    /**
+     * Set authentication token (from wallet authentication)
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Set wallet address (for wallet-based auth)
+     */
+    setWalletAddress(address: string): void;
+    /**
+     * Authenticate with wallet
+     * Returns auth token for subsequent API calls
+     */
+    authenticateWithWallet(walletAddress: string, signature: string, message: string): Promise<{
+        token: string;
+        user: any;
+        profile: any;
+    }>;
+    /**
+     * Get wallet address (for non-iframe)
+     * Requires authentication
+     */
+    getWalletAddress(): Promise<WalletAddressResponse>;
+    /**
+     * Send payment request via API
+     */
+    sendPaymentRequest(gameId: string, request: PaymentRequest): Promise<PaymentResponse>;
+    /**
+     * Update playtime/stats
+     */
+    updatePlaytime(gameId: string, playtimeHours: number, status?: 'playing' | 'owned' | 'completed'): Promise<void>;
+    /**
+     * Update online status
+     */
+    updateOnlineStatus(isOnline: boolean, gameId?: string): Promise<void>;
+    /**
+     * Generic request method
+     */
+    private request;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/esm/api-client.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAEjF;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,aAAa,CAAuB;gBAEhC,OAAO,CAAC,EAAE,MAAM;IAK5B;;OAEG;IACH,OAAO,CAAC,aAAa;IAmBrB;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIvC;;;OAGG;IACG,sBAAsB,CAC1B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,GAAG,CAAA;KAAE,CAAC;IAmBtD;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAuCxD;;OAEG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC;IAgB3B;;OAEG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,WAAW,GACzC,OAAO,CAAC,IAAI,CAAC;IAWhB;;OAEG;IACG,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3E;;OAEG;YACW,OAAO;CAgCtB"}

package/dist/esm/index.d.ts CHANGED Viewed

@@ -5,6 +5,7 @@
  * Works in iframe environments by communicating with parent window via postMessage.
  */
 export { ArcadiaSDK } from './sdk';
+export { APIClient } from './api-client';
 export type { SDKConfig, PaymentResult, WalletInfo, MessageType, PaymentRequest, PaymentResponse, InitData, WalletAddressResponse, } from './types';
 export { ArcadiaSDKError, WalletNotConnectedError, PaymentFailedError, TimeoutError, InvalidConfigError, NotInIframeError, InvalidAmountError, InvalidTokenError, } from './errors';
 import { ArcadiaSDK } from './sdk';

package/dist/esm/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGnC,YAAY,EACV,SAAS,EACT,aAAa,EACb,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,QAAQ,EACR,qBAAqB,GACtB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,eAAe,UAAU,CAAC"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,YAAY,EACV,SAAS,EACT,aAAa,EACb,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,QAAQ,EACR,qBAAqB,GACtB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,eAAe,UAAU,CAAC"}