@caspay/sdk 1.0.3 → 1.1.0

package/README.md

@@ -5,7 +5,17 @@ Official JavaScript/TypeScript SDK for CasPay - Accept crypto payments with Casp
 [![npm version](https://img.shields.io/npm/v/@caspay/sdk)](https://www.npmjs.com/package/@caspay/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## 🚀 Installation
+## 🚀 Features
+
+- **Two Integration Modes:**
+  - **Full Management**: CasPay handles wallet connection, transfer & recording
+  - **Tracking Only**: Merchant handles payment, CasPay tracks analytics
+- **Casper Wallet Integration**: Seamless wallet connection and payments
+- **Subscription Management**: Recurring payments with automatic tracking
+- **TypeScript Support**: Full type definitions included
+- **Framework Agnostic**: Works with React, Next.js, Vue, Vanilla JS, PHP
+
+## 📦 Installation
 
 ### NPM / Yarn (React, Next.js, Node.js)
 
@@ -15,97 +25,217 @@ npm install @caspay/sdk
 yarn add @caspay/sdk
 ```
 
-### CDN (WordPress, HTML)
+### CDN (PHP, HTML)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@caspay/sdk@1.0.2/dist/caspay.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@caspay/sdk@1.1.0/dist/caspay.min.js"></script>
 ```
 
-## 📖 Quick Start
+> **Note**: Users only need to install **Casper Wallet browser extension**. No additional dependencies required.
+
+## 📚 Quick Start
+
+### Mode 1: Full Management (CasPay Handles Everything)
 
-### React / Next.js
+CasPay SDK manages wallet connection, blockchain transfer, and payment recording.
+
+#### React / Next.js
 
 ```typescript
 import CasPay from '@caspay/sdk';
 
 const caspay = new CasPay({
   apiKey: 'cp_live_...',
-  merchantId: 'MERCH_...'
+  merchantId: 'MERCH_...',
+  walletAddress: '01ab...', // Your wallet to receive payments
+  network: 'testnet'
 });
 
-// Create a payment
-const payment = await caspay.payments.create({
-  senderAddress: '0x123...',
+// One-time payment
+const result = await caspay.payments.makePayment({
   productId: 'prod_abc123',
-  amount: 100,
-  currency: 'USD'
+  amount: 10.5, // CSPR
 });
 
-console.log('Payment successful:', payment);
+// Subscription payment
+const subResult = await caspay.payments.makePayment({
+  subscriptionPlanId: 'plan_xyz789',
+  amount: 29.99
+});
 ```
 
-### WordPress / HTML
+#### PHP / Vanilla JS
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@caspay/sdk@1.0.2/dist/caspay.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@caspay/sdk@1.1.0/dist/caspay.min.js"></script>
 
-<button id="payBtn">Pay Now</button>
+<button id="payBtn">Pay 10 CSPR</button>
 
 <script>
   const caspay = new CasPay({
     apiKey: 'cp_live_...',
-    merchantId: 'MERCH_...'
+    merchantId: 'MERCH_...',
+    walletAddress: '01ab...',
+    network: 'testnet'
   });
 
   document.getElementById('payBtn').onclick = async () => {
-    const payment = await caspay.payments.create({
-      senderAddress: '0x123...',
+    const result = await caspay.payments.makePayment({
       productId: 'prod_abc',
-      amount: 50
+      amount: 10
     });
-    
-    alert('Payment successful!');
   };
 </script>
 ```
 
+### Mode 2: Tracking Only (Merchant Handles Payment)
+
+Merchant integrates Casper Wallet separately, makes the payment, then records it with CasPay for analytics.
+
+```typescript
+// After merchant processes the payment with their own wallet integration:
+
+const result = await caspay.payments.recordPayment({
+  senderAddress: '0145ab...', // Customer's wallet address
+  transactionHash: 'abc123...', // Casper blockchain tx hash
+  productId: 'prod_abc123',
+  amount: 10.5,
+  currency: 'CSPR'
+});
+
+
+// For subscriptions:
+const subResult = await caspay.payments.recordSubscription({
+  senderAddress: '0145ab...',
+  transactionHash: 'xyz789...',
+  subscriptionPlanId: 'plan_monthly',
+  amount: 29.99,
+  currency: 'CSPR'
+});
+```
+
 ## 🔧 Configuration
 
 ### Constructor Options
 
 ```typescript
 const caspay = new CasPay({
-  apiKey: string;        // Required: Your CasPay API key
-  merchantId: string;    // Required: Your merchant ID
+  apiKey: string;         // Required: Your CasPay API key
+  merchantId: string;     // Required: Your merchant ID
+  walletAddress: string;  // Required: Merchant wallet to receive payments
+  network?: 'mainnet' | 'testnet';  // Optional: Default is testnet
+  baseUrl?: string;       // Optional: API base URL (for development)
 });
 ```
 
-**Note:** API endpoint is fixed to `https://caspay.link/api` for all requests.
-
 ### Get API Keys
 
 1. Sign up at [caspay.link](https://caspay.link)
-2. Navigate to Settings → API Keys
+2. Create and go the merchant page → API Keys
 3. Generate a new API key
 
 ## 📚 API Reference
 
+### Wallet
+
+#### `caspay.wallet.connect()`
+
+Connect to Casper Wallet extension.
+
+```typescript
+const address = await caspay.wallet.connect();
+console.log('Connected:', address);
+```
+
+#### `caspay.wallet.disconnect()`
+
+Disconnect from wallet.
+
+```typescript
+await caspay.wallet.disconnect();
+```
+
+#### `caspay.wallet.getAddress()`
+
+Get current connected wallet address.
+
+```typescript
+const address = await caspay.wallet.getAddress();
+console.log('Address:', address);
+```
+
+#### `caspay.wallet.getInfo()`
+
+Get cached wallet connection info (synchronous).
+
+```typescript
+const info = caspay.wallet.getInfo();
+console.log('Connected:', info.isConnected);
+console.log('Address:', info.address);
+```
+
+#### `caspay.wallet.getState()`
+
+Get complete wallet state (asynchronous).
+
+```typescript
+const state = await caspay.wallet.getState();
+console.log('Connected:', state.connected);
+console.log('Address:', state.address);
+console.log('Locked:', state.locked);
+```
+
 ### Payments
 
-#### `caspay.payments.create(params)`
+#### `caspay.payments.makePayment(params)` - Full Management
 
-Create a new payment record.
+Make a payment with full wallet & transfer management.
+
+**Parameters:**
+
+```typescript
+{
+  productId?: string;              // Product ID (for one-time payments)
+  subscriptionPlanId?: string;     // Subscription plan ID (for recurring)
+  amount: number;                  // Payment amount in CSPR
+  currency?: string;               // Currency code (default: CSPR)
+}
+```
+
+**Returns:**
+
+```typescript
+{
+  success: boolean;
+  transactionHash: string;
+  payment?: PaymentResponse;       // If successfully recorded
+  error?: string;                  // If payment failed
+}
+```
+
+**Example:**
+
+```typescript
+const result = await caspay.payments.makePayment({
+  productId: 'prod_abc123',
+  amount: 10.5
+});
+```
+
+#### `caspay.payments.recordPayment(params)` - Tracking Only
+
+Record a payment that was already processed by merchant.
 
 **Parameters:**
 
 ```typescript
 {
   senderAddress: string;           // Sender's Casper wallet address
+  transactionHash?: string;        // Casper transaction hash (optional)
   productId?: string;              // Product ID (for one-time payments)
   subscriptionPlanId?: string;     // Subscription plan ID (for recurring)
   amount: number;                  // Payment amount
   currency?: string;               // Currency code (default: USD)
-  transactionHash?: string;        // Optional: Casper transaction hash
 }
 ```
 
@@ -134,18 +264,78 @@ Create a new payment record.
 **Example:**
 
 ```typescript
-// One-time payment
-const payment = await caspay.payments.create({
-  senderAddress: '0x123...',
+const result = await caspay.payments.recordPayment({
+  senderAddress: '0145ab...',
+  transactionHash: 'abc123...',
   productId: 'prod_abc123',
-  amount: 100
+  amount: 10.5,
+  currency: 'CSPR'
 });
+```
 
-// Subscription payment
-const subscription = await caspay.payments.create({
-  senderAddress: '0x123...',
-  subscriptionPlanId: 'plan_xyz789',
-  amount: 29.99
+#### `caspay.payments.recordSubscription(params)` - Tracking Only
+
+Record a subscription payment (alias for recordPayment with subscriptionPlanId).
+
+```typescript
+const result = await caspay.payments.recordSubscription({
+  senderAddress: '0145ab...',
+  transactionHash: 'xyz789...',
+  subscriptionPlanId: 'plan_monthly',
+  amount: 29.99,
+  currency: 'CSPR'
+});
+```
+
+### Subscriptions
+
+#### `caspay.subscriptions.checkStatus(params)`
+
+Check subscription status for a subscriber.
+
+**Parameters:**
+
+```typescript
+{
+  subscriberAddress: string;  // Subscriber's wallet address
+  planId?: string;            // Optional: Filter by specific plan
+}
+```
+
+**Returns:**
+
+```typescript
+{
+  success: boolean;
+  active: boolean;
+  subscriptions?: Array<{
+    id: string;
+    plan_id: string;
+    subscriber_address: string;
+    status: string;
+    current_period_start: string;
+    current_period_end: string;
+    created_at: string;
+  }>;
+  message?: string;
+}
+```
+
+**Example:**
+
+```typescript
+// Check all subscriptions for a subscriber
+const status = await caspay.subscriptions.checkStatus({
+  subscriberAddress: '0145ab...'
+});
+
+console.log('Active:', status.active);
+console.log('Subscriptions:', status.subscriptions);
+
+// Check specific plan
+const planStatus = await caspay.subscriptions.checkStatus({
+  subscriberAddress: '0145ab...',
+  planId: 'plan_monthly'
 });
 ```
 
@@ -155,7 +345,7 @@ All SDK methods throw structured errors:
 
 ```typescript
 try {
-  const payment = await caspay.payments.create({...});
+  const payment = await caspay.payments.makePayment({...});
 } catch (error) {
   console.error('Error:', error.error);   // Error message
   console.error('Code:', error.code);     // Error code
@@ -167,9 +357,29 @@ try {
 
 - `INVALID_PARAMS` - Missing or invalid parameters
 - `INVALID_API_KEY` - Invalid API key
-- `RATE_LIMIT_EXCEEDED` - Too many requests
-- `VERIFICATION_FAILED` - Transaction verification failed
+- `WALLET_NOT_FOUND` - Casper Wallet extension not installed
+- `WALLET_LOCKED` - Wallet is locked
+- `CONNECTION_REJECTED` - User rejected wallet connection
+- `TRANSFER_REJECTED` - User rejected transaction
 - `NETWORK_ERROR` - Network connection error
+- `VERIFICATION_FAILED` - Transaction verification failed
+
+### Wallet Errors
+
+```typescript
+try {
+  await caspay.wallet.connect();
+} catch (error) {
+  if (error.code === 'WALLET_NOT_FOUND') {
+    // Prompt user to install Casper Wallet
+    window.open(error.installUrl, '_blank');
+  } else if (error.code === 'WALLET_LOCKED') {
+    alert('Please unlock your Casper Wallet');
+  } else if (error.code === 'CONNECTION_REJECTED') {
+    alert('Connection rejected by user');
+  }
+}
+```
 
 ## 🌐 Environment Support
 
@@ -177,36 +387,48 @@ try {
 |-------------|--------------|--------|
 | React/Next.js | `npm install @caspay/sdk` | `import CasPay from '@caspay/sdk'` |
 | Node.js | `npm install @caspay/sdk` | `const CasPay = require('@caspay/sdk')` |
-| WordPress | CDN script tag | `window.CasPay` |
-| HTML | CDN script tag | `window.CasPay` |
-
-## 🔒 Security
+| PHP/Vanilla JS | CDN script tag | `window.CasPay` |
 
-- **Never expose your API key** in client-side code in production
-- Use environment variables for sensitive data
-- API keys should be stored server-side
-- Use test keys (`cp_test_...`) for development
 
 ## 📦 TypeScript Support
 
 Full TypeScript support with type definitions included:
 
 ```typescript
-import CasPay, { PaymentCreateParams, PaymentResponse } from '@caspay/sdk';
-
-const params: PaymentCreateParams = {
-  senderAddress: '0x123...',
+import CasPay, { 
+  MakePaymentParams, 
+  MakePaymentResult,
+  PaymentCreateParams,
+  PaymentResponse,
+  SubscriptionCheckParams,
+  SubscriptionCheckResponse,
+  WalletState
+} from '@caspay/sdk';
+
+const params: MakePaymentParams = {
   productId: 'prod_abc',
-  amount: 100
+  amount: 10.5
 };
 
-const payment: PaymentResponse = await caspay.payments.create(params);
+const result: MakePaymentResult = await caspay.payments.makePayment(params);
 ```
 
+## 🎯 Integration Modes Comparison
+
+| Feature | Full Management | Tracking Only |
+|---------|----------------|---------------|
+| Wallet Integration | ✅ CasPay SDK | ❌ Merchant implements |
+| Blockchain Transfer | ✅ CasPay SDK | ❌ Merchant handles |
+| Payment Recording | ✅ Automatic | ✅ Manual via SDK |
+| Analytics Dashboard | ✅ Yes | ✅ Yes |
+| Subscription Tracking | ✅ Yes | ✅ Yes |
+| **Best For** | Simple integration | Custom wallet UX |
+
 ## 🔗 Links
 
 - **Documentation:** [docs.caspay.link](https://docs.caspay.link)
 - **Dashboard:** [caspay.link](https://caspay.link)
+- **Demo:** [demo.caspay.link](https://caspay.link/demo.html)
 - **NPM:** [@caspay/sdk](https://www.npmjs.com/package/@caspay/sdk)
 - **GitHub:** [dmrdvn/caspay-sdk](https://github.com/dmrdvn/caspay-sdk)
 

package/dist/browser.d.ts

@@ -1,17 +1,2 @@
-/**
- * Browser bundle entry point
- * Exposes CasPay SDK to window.CasPay for script tag usage
- *
- * @example
- * ```html
- * <script src="https://cdn.jsdelivr.net/npm/@caspay/sdk/dist/caspay.min.js"></script>
- * <script>
- *   const caspay = new CasPay({
- *     apiKey: 'cp_live_...',
- *     merchantId: 'MERCH_...'
- *   });
- * </script>
- * ```
- */
 import CasPay from './index';
 export default CasPay;