@galva-io/galva-admin-node 1.0.0-dev → 1.0.1-dev

package/README.md

@@ -1,6 +1,6 @@
 # Galva Admin Node SDK
 
-TypeScript SDK for integrating with Galva Admin API. This SDK provides a type-safe way to sync billing events and manage user data.
+Node.js SDK for syncing billing events and managing end users with Galva.
 
 ## Installation
 
@@ -8,211 +8,122 @@ TypeScript SDK for integrating with Galva Admin API. This SDK provides a type-sa
 npm install galva-admin-node
 ```
 
+**Peer dependencies** (install as needed):
+```bash
+npm install @paddle/paddle-node-sdk  # For Paddle
+npm install googleapis               # For Play Store
+```
+
 ## Quick Start
 
 ```typescript
-import galvaAdmin from 'galva-admin-node';
+import { Galva } from 'galva-admin-node';
 
-const galva = galvaAdmin({
-  apiKey: 'your-api-key-here',
-  baseUrl: 'https://api.galva.io', // optional
-  debug: true // optional, enables logging
-});
+const galva = new Galva({ apiKey: 'your-api-key' });
+// Or set GALVA_API_KEY environment variable
 ```
 
-## Usage Examples
+## Billing Events
 
-### Track a Purchase
+### With Pre-verified Payloads
 
-```typescript
-await galva.trackPurchase({
-  id: 'evt_123',
-  endUserId: 'user_456',
-  appIdentifier: 'com.example.app',
-  productIdentifier: 'premium_monthly',
-  planIdentifier: 'monthly',
-  platform: 'ios',
-  eventTimestamp: new Date().toISOString(),
-  purchasedAt: new Date().toISOString(),
-  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
-  isTrial: false
-});
-```
-
-### Track a Renewal
+Use when you've already decoded/verified payloads yourself.
 
 ```typescript
-await galva.trackRenewal({
-  id: 'evt_124',
-  endUserId: 'user_456',
-  appIdentifier: 'com.example.app',
-  productIdentifier: 'premium_monthly',
-  planIdentifier: 'monthly',
-  platform: 'ios',
-  eventTimestamp: new Date().toISOString(),
-  purchasedAt: new Date().toISOString(),
-  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString()
+// App Store
+await galva.billingEvent.appstore('user-123', {
+  signedPayload: '...',
+  bundleId: 'com.example.app',
+  appAppleId: 123456789,
 });
-```
 
-### Track a Cancellation
+// Play Store (decoded notification)
+await galva.billingEvent.playstore('user-123', decodedNotification);
 
-```typescript
-await galva.trackCancellation({
-  id: 'evt_125',
-  endUserId: 'user_456',
-  appIdentifier: 'com.example.app',
-  productIdentifier: 'premium_monthly',
-  planIdentifier: 'monthly',
-  platform: 'ios',
-  eventTimestamp: new Date().toISOString(),
-  cancelReason: 'too_expensive',
-  expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
-});
+// Paddle (verified event)
+await galva.billingEvent.paddle('user-123', verifiedEvent);
 ```
 
-### Identify a User
+### With Credentials (Auto-verification)
+
+Use `withCredentials()` to let the SDK handle decoding and verification.
 
 ```typescript
-await galva.identify({
-  userId: 'user_456',
-  email: 'user@example.com',
-  name: 'John Doe',
-  attributes: {
-    plan: 'premium',
-    signupDate: '2024-01-01',
-    referralSource: 'organic'
-  }
+const galvaWithCreds = galva.withCredentials({
+  appstore: {
+    bundleId: 'com.example.app',
+    appAppleId: 123456789,
+  },
+  playstore: {
+    email: 'service-account@project.iam.gserviceaccount.com',
+    key: '-----BEGIN PRIVATE KEY-----\n...',
+  },
+  paddle: {
+    apiKey: 'pdl_...',
+    secretKey: 'whsec_...',
+  },
 });
-```
 
-### Sync Multiple Events (Batch)
+// App Store (signed payload only)
+await galvaWithCreds.billingEvent.appstore('user-123', signedPayload);
 
-```typescript
-const events = [
-  {
-    id: 'evt_126',
-    type: 'initial-purchase' as const,
-    endUserId: 'user_789',
-    appIdentifier: 'com.example.app',
-    productIdentifier: 'premium_yearly',
-    planIdentifier: 'yearly',
-    platform: 'android' as const,
-    eventTimestamp: new Date().toISOString(),
-    purchasedAt: new Date().toISOString(),
-    expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString()
-  },
-  // ... more events
-];
+// Play Store (base64 from Pub/Sub - auto-decodes and fetches subscription)
+await galvaWithCreds.billingEvent.playstore('user-123', base64Payload);
 
-await galva.syncEvents(events);
+// Paddle (raw body + signature - auto-verifies)
+await galvaWithCreds.billingEvent.paddle('user-123', rawBody, signature);
 ```
 
-### Queue Events for Batch Processing
+## End User Management
 
 ```typescript
-// Queue events (they'll be automatically batched)
-galva.queueEvent({
-  id: 'evt_127',
-  type: 'renewal',
-  endUserId: 'user_123',
-  appIdentifier: 'com.example.app',
-  productIdentifier: 'premium_monthly',
-  planIdentifier: 'monthly',
-  platform: 'stripe',
-  eventTimestamp: new Date().toISOString(),
-  purchasedAt: new Date().toISOString()
-}, {
-  maxBatchSize: 50,    // Flush after 50 events
-  flushInterval: 10000 // Flush every 10 seconds
+import { EndUserDefaultTraitName } from 'galva-admin-node';
+
+// Identify with traits
+await galva.endUser.identify('user-123', {
+  traits: {
+    [EndUserDefaultTraitName.EMAIL]: 'user@example.com',
+    [EndUserDefaultTraitName.FULL_NAME]: 'John Doe',
+    customTrait: 'value',
+  },
 });
 
-// Manually flush queued events
-await galva.flush();
+// Update default profile info
+await galva.endUser.updateDefaultInfo('user-123', {
+  email: 'user@example.com',
+  fullName: 'John Doe',
+  country: 'US',
+});
 ```
 
-## API Reference
-
-### Configuration
+## Configuration
 
 ```typescript
-interface GalvaConfig {
-  apiKey: string;       // Required: Your API key
-  baseUrl?: string;     // Optional: API base URL (default: https://api.galva.io)
-  timeout?: number;     // Optional: Request timeout in ms (default: 30000)
-  debug?: boolean;      // Optional: Enable debug logging (default: false)
+interface GalvaOptions {
+  apiKey?: string;                          // Falls back to GALVA_API_KEY env
+  environment?: 'production' | 'development'; // Falls back to NODE_ENV
+  timeout?: number;                         // Request timeout in ms (default: 10000)
 }
 ```
 
-### Methods
-
-#### Event Tracking
-
-- `trackPurchase(event)` - Track an initial purchase event
-- `trackRenewal(event)` - Track a subscription renewal
-- `trackCancellation(event)` - Track a subscription cancellation
-- `trackBillingIssue(event)` - Track a billing issue
-- `trackExpiration(event)` - Track a subscription expiration
-- `trackUpgrade(event)` - Track a plan upgrade
-- `trackRefund(event)` - Track a refund
-
-#### Generic Event Methods
-
-- `syncEvent(event)` - Sync a single billing event
-- `syncEvents(events)` - Batch sync multiple events
-- `queueEvent(event, options?)` - Queue an event for batch processing
-- `flush()` - Manually flush the event queue
-
-#### User Management
-
-- `identify(userData)` - Identify a user and sync their attributes
-- `getUserStatus(userId)` - Get a user's subscription status
-
-#### Utility
-
-- `healthCheck()` - Check API health status
-
-### Event Types
-
-The SDK supports the following billing event types:
-
-- `initial-purchase` - New subscription or trial
-- `renewal` - Subscription renewal
-- `cancellation` - Subscription cancellation
-- `billing-issue` - Payment failure or issue
-- `expiration` - Subscription expiration
-- `upgraded` - Plan upgrade
-- `refund` - Refund processed
-- `resubscribe` - User resubscribed
-- `transfer` - Subscription transferred between users
-- `grace_period_start` - Grace period started
-
-### Error Handling
+## Error Handling
 
 ```typescript
 import { GalvaError } from 'galva-admin-node';
 
 try {
-  await galva.trackPurchase(eventData);
+  await galva.billingEvent.appstore('user-123', payload);
 } catch (error) {
   if (error instanceof GalvaError) {
-    console.error('Galva API Error:', {
-      code: error.code,
-      message: error.message,
-      statusCode: error.statusCode,
-      details: error.details
-    });
-  } else {
-    console.error('Unexpected error:', error);
+    console.error(error.code, error.message);
   }
 }
 ```
 
 ## Requirements
 
-- Node.js 18.0 or higher (for native fetch support)
-- TypeScript 5.0 or higher (for development)
+- Node.js >= 18.0
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@galva-io/galva-admin-node",
-  "version": "1.0.0-dev",
+  "version": "1.0.1-dev",
   "description": "Node.js SDK for Galva Admin API",
   "type": "module",
   "main": "./dist/index.cjs",