@explorins/pers-sdk 2.0.7 → 2.0.10

package/README.md

@@ -107,84 +107,106 @@ npm install @explorins/pers-shared ethers@^6.15.0
 
 ### Direct Dependencies
 
-| Package | Purpose |
-|---------|---------|
-| `@explorins/web3-ts` | Internal Web3 chain utilities |
+The SDK has **zero** direct runtime dependencies. All peer dependencies are optional:
+
+| Package | Type | Purpose |
+|---------|------|---------|
+| `@explorins/pers-shared` | Peer (required) | Shared types, interfaces, and DTOs |
+| `@explorins/web3-ts` | Peer (optional) | Web3/blockchain utilities (only needed for `sdk.web3.*` methods) |
+| `ethers` | Peer (optional) | Blockchain operations (only needed for `sdk.web3.*` methods) |
 
 ---
 
 ## Installation
 
 ```bash
-# Core SDK
+# Core SDK (lightweight - ~200KB)
 npm install @explorins/pers-sdk
 
-# Required peer dependencies
-npm install @explorins/pers-shared ethers@^6.15.0
+# Required peer dependency
+npm install @explorins/pers-shared
+
+# Optional: Only if using Web3/blockchain features (sdk.web3.*)
+npm install @explorins/web3-ts ethers@^6.15.0
 
 # Optional: For Angular applications only
 npm install rxjs
 ```
 
+**Package Size:**
+- Installed: ~1.9 MB (node_modules - both ESM/CJS + types + maps)
+- Your bundle: ~450 KB (bundler includes only ESM or CJS, not both)
+- With Web3: +1.5 MB (optional peer dependencies)
+- For smaller bundles: Import from `@explorins/pers-sdk/campaign` etc.
+
 ---
 
 ## Quick Start
 
-### Minimum Viable Example
+### Browser / React / Vue
 
 ```typescript
-import { PersSDK } from '@explorins/pers-sdk';
+import { createPersSDK } from '@explorins/pers-sdk';
 import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
 
-// 1. Initialize SDK (required: adapter + project key)
-const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
-  apiProjectKey: 'your-project-key'  // Get from PERS dashboard
+// Initialize SDK
+const sdk = createPersSDK(new BrowserFetchClientAdapter(), {
+  apiProjectKey: 'your-project-key'
 });
 
-// 2. Authenticate with external JWT (Firebase, Auth0, Cognito, etc.)
-const externalJWT = await yourAuthProvider.getIdToken();  // Your JWT
+// Authenticate with external JWT (Firebase, Auth0, Cognito, etc.)
+const externalJWT = await yourAuthProvider.getIdToken();
 const authResult = await sdk.auth.loginWithToken(externalJWT, 'user');
-console.log('Authenticated user:', authResult.user.id);
 
-// 3. Use SDK managers
+// Use SDK managers
 const campaigns = await sdk.campaigns.getActiveCampaigns();
-const tokens = await sdk.tokens.getTokens();
 ```
 
-### Complete Example
+### Node.js (Convenience Function)
 
 ```typescript
-import { PersSDK } from '@explorins/pers-sdk';
-import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+import { createNodeSDK } from '@explorins/pers-sdk/node';
 
-// Initialize SDK with browser fetch adapter
-const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
-  environment: 'production',
-  apiProjectKey: 'your-project-key'
+// One-liner setup with static JWT
+const sdk = createNodeSDK({
+  jwt: 'your-system-jwt',
+  projectKey: 'your-project-key',
+  environment: 'production'
 });
 
-// Authentication - login with external JWT (Firebase, Auth0, etc.)
-const authResult = await sdk.auth.loginWithToken(firebaseJWT, 'user');
-const user = await sdk.auth.getCurrentUser();
+// Ready to use - no additional auth needed
+const campaigns = await sdk.campaigns.getCampaigns();
+const userClaims = await sdk.campaigns.getCampaignClaims({ userId: 'user-123' });
+```
 
-// Business operations
-const businesses = await sdk.businesses.getActiveBusinesses();
-const business = await sdk.businesses.getBusinessById('business-123');
+### Complete Example (Node.js Server-Side)
 
-// Campaign management
-const campaigns = await sdk.campaigns.getActiveCampaigns();
-const claim = await sdk.campaigns.claimCampaign({ 
+```typescript
+import { createNodeSDK } from '@explorins/pers-sdk/node';
+
+// Initialize with static JWT (tenant/business system token)
+const sdk = createNodeSDK({
+  jwt: process.env.PERS_JWT_TOKEN,
+  projectKey: process.env.PERS_PROJECT_KEY,
+  environment: 'production'
+});
+
+// Campaign operations (admin/system access)
+const campaigns = await sdk.campaigns.getCampaigns();
+const campaign = await sdk.campaigns.getCampaignById('campaign-123');
+
+// Claim campaign for a user (system operation)
+const claim = await sdk.campaigns.claimCampaign({
   campaignId: 'campaign-123',
-  businessId: 'business-456'
+  userIdentifier: 'external-user-id'
 });
 
-// Token operations
-const tokens = await sdk.tokens.getTokens();
-const creditToken = await sdk.tokens.getActiveCreditToken();
-const rewardTokens = await sdk.tokens.getRewardTokens();
+// Get user's claim history
+const userId = claim.user?.id;
+const userClaims = await sdk.campaigns.getCampaignClaims({ userId });
 
-// User claims history
-const userClaims = await sdk.campaigns.getUserClaims();
+// Business operations
+const businesses = await sdk.businesses.getActiveBusinesses();
 ```
 
 ---
@@ -196,10 +218,10 @@ const userClaims = await sdk.campaigns.getUserClaims();
 **No additional dependencies required.**
 
 ```typescript
-import { PersSDK } from '@explorins/pers-sdk';
+import { createPersSDK } from '@explorins/pers-sdk';
 import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
 
-const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
+const sdk = createPersSDK(new BrowserFetchClientAdapter(), {
   environment: 'production',
   apiProjectKey: 'your-project-key'
 });
@@ -256,19 +278,23 @@ export class PersSDKService {
 
 ### Node.js
 
-**No additional dependencies required.**
+**No additional dependencies required.** Use the dedicated Node.js entry point:
 
 ```typescript
-import { PersSDK } from '@explorins/pers-sdk';
-import { NodeHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+import { createNodeSDK } from '@explorins/pers-sdk/node';
 
-const sdk = new PersSDK(new NodeHttpClientAdapter(), {
-  environment: 'production',
-  apiProjectKey: 'your-project-key'
+// Convenience function for Node.js - auto-configures adapter
+const sdk = createNodeSDK({
+  jwt: 'your-jwt-token',
+  projectKey: 'your-project-key',
+  environment: 'production'
 });
 
-// Server-side operations
-const businesses = await sdk.businesses.getActiveBusinesses();
+// Ready to use
+const campaigns = await sdk.campaigns.getActiveCampaigns();
+const userClaims = await sdk.campaigns.getCampaignClaims({ 
+  userId: 'user-123' 
+});
 ```
 
 ### React Native
@@ -853,11 +879,11 @@ const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
 For better security and performance, use IndexedDB instead of LocalStorage:
 
 ```typescript
-import { PersSDK } from '@explorins/pers-sdk';
+import { createPersSDK } from '@explorins/pers-sdk';
 import { IndexedDBTokenStorage } from '@explorins/pers-sdk/core';
 import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
 
-const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
+const sdk = createPersSDK(new BrowserFetchClientAdapter(), {
   environment: 'production',
   apiProjectKey: 'your-key',
   authStorage: new IndexedDBTokenStorage()  // Secure, async storage
@@ -952,10 +978,18 @@ const retryable = ErrorUtils.isRetryable(error); // Check if retryable
 
 ## Bundle Size
 
-- **Core SDK**: ~85 KB (minified)
-- **Tree-shaking**: Fully supported - import only what you need
-- **Zero runtime dependencies**: No RxJS, no heavy libraries in core
-- **Native APIs**: Uses browser-native `fetch`, `crypto`, `IndexedDB`
+- **Installed to node_modules**: ~1.9 MB unpacked (includes both ESM + CJS builds, TypeScript definitions, source maps)
+- **What your bundler actually includes**:
+  - ESM build: ~450 KB (Vite, Rollup, modern Webpack)
+  - CJS build: ~470 KB (legacy Node.js/Webpack)
+  - Your bundler only includes ONE of these, not both
+- **TypeScript definitions**: ~510 KB (used by IDE/compiler, not bundled into your app)
+- **Source maps**: ~440 KB (used for debugging, typically excluded from production)
+- **With Web3 Features**: +1.5 MB additional when installing optional `@explorins/web3-ts` + `ethers` peer dependencies
+- **Tree-shaking**: The main `PersSDK` class includes all managers. For smaller bundles, import from domain-specific entry points (e.g., `@explorins/pers-sdk/campaign`)
+- **Zero bundled dependencies**: All dependencies are peer dependencies
+
+**Bottom line:** Your production bundle gets ~450 KB from this SDK (ESM), not 1.9 MB. The larger size is what's stored in `node_modules`, which includes both module formats, type definitions, and development tools.
 
 ---
 
@@ -1023,16 +1057,17 @@ import type {
 ### Usage Example
 
 ```typescript
-import { PersSDK } from '@explorins/pers-sdk';
+import { createPersSDK } from '@explorins/pers-sdk';
 import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
 import type { CampaignDTO, CampaignClaimRequestDTO } from '@explorins/pers-shared';
 
-const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
+const sdk = createPersSDK(new BrowserFetchClientAdapter(), {
   apiProjectKey: 'your-key'
 });
 
 // Type-safe campaign operations
-const campaigns: CampaignDTO[] = await sdk.campaigns.getActiveCampaigns();
+const response = await sdk.campaigns.getActiveCampaigns();
+const campaigns: CampaignDTO[] = response.data;
 
 const claimRequest: CampaignClaimRequestDTO = {
   campaignId: campaigns[0].id,

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk",
-  "version": "2.0.7",
+  "version": "2.0.10",
   "description": "Platform-agnostic SDK for PERS (Phygital Experience Rewards System) - Core business logic and API integration",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -127,9 +127,7 @@
     "publish-version": "npm run clean && npm run build && npm version patch && npm publish",
     "publish-with-docs": "npm run clean && npm run build && npm run docs && npm version patch && npm publish"
   },
-  "dependencies": {
-    "@explorins/web3-ts": "^0.3.77"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@explorins/pers-shared": "^2.1.72",
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -148,9 +146,17 @@
   },
   "peerDependencies": {
     "@explorins/pers-shared": "*",
+    "@explorins/web3-ts": "^0.3.77",
     "ethers": "^6.15.0"
   },
-  "peerDependenciesMeta": {},
+  "peerDependenciesMeta": {
+    "@explorins/web3-ts": {
+      "optional": true
+    },
+    "ethers": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk",
-  "version": "2.0.7",
+  "version": "2.0.10",
   "description": "Platform-agnostic SDK for PERS (Phygital Experience Rewards System) - Core business logic and API integration",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -127,9 +127,7 @@
     "publish-version": "npm run clean && npm run build && npm version patch && npm publish",
     "publish-with-docs": "npm run clean && npm run build && npm run docs && npm version patch && npm publish"
   },
-  "dependencies": {
-    "@explorins/web3-ts": "^0.3.77"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@explorins/pers-shared": "^2.1.72",
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -148,9 +146,17 @@
   },
   "peerDependencies": {
     "@explorins/pers-shared": "*",
+    "@explorins/web3-ts": "^0.3.77",
     "ethers": "^6.15.0"
   },
-  "peerDependenciesMeta": {},
+  "peerDependenciesMeta": {
+    "@explorins/web3-ts": {
+      "optional": true
+    },
+    "ethers": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"