@explorins/pers-sdk

Platform-agnostic TypeScript SDK for PERS (Phygital Experience Rewards System) - Modern Manager-Service architecture providing clean, consistent APIs for tourism loyalty applications.

Overview

PERS is a comprehensive tourism loyalty platform bridging physical and digital experiences through loyalty programs, campaign management, payments, blockchain integration, business management, and analytics.

Installation

npm install @explorins/pers-sdk

Quick Start

import { PersSDK } from '@explorins/pers-sdk';
import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';

const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
  environment: 'production',
  apiProjectKey: 'your-project-key'
});

// Authentication
const user = await sdk.auth.getCurrentUser();

// Business operations
const businesses = await sdk.businesses.getActiveBusinesses();

// Campaign management
const campaigns = await sdk.campaigns.getActiveCampaigns();
const campaignClaim = await sdk.campaigns.claimCampaign({ campaignId: 'campaign-123', userId: 'user-456' });

// Token operations
const tokens = await sdk.tokens.getTokens();
const balances = await sdk.tokens.getBalances(userId);

Platform Integration

Angular

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { PersSDK } from '@explorins/pers-sdk';
import { AngularHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';

@Injectable({ providedIn: 'root' })
export class PersSDKService {
  private sdk: PersSDK;

  constructor(httpClient: HttpClient) {
    this.sdk = new PersSDK(new AngularHttpClientAdapter(httpClient), {
      environment: 'production',
      apiProjectKey: 'your-project-key'
    });
  }

  getSDK(): PersSDK {
    return this.sdk;
  }
}

React/Browser

import { PersSDK } from '@explorins/pers-sdk';
import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';

const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
  environment: 'production',
  apiProjectKey: 'your-project-key'
});

Node.js

import { PersSDK } from '@explorins/pers-sdk';
import { NodeHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';

const sdk = new PersSDK(new NodeHttpClientAdapter(), {
  environment: 'production',
  apiProjectKey: 'your-project-key'
});

Architecture

The SDK uses a clean Manager-Service pattern:

// Manager Layer (Primary Interface)
sdk.auth           // Authentication & sessions
sdk.users          // User profiles & management
sdk.tokens         // Token operations & balances
sdk.businesses     // Business operations
sdk.campaigns      // Marketing campaigns
sdk.redemptions    // Reward redemptions
sdk.transactions   // Transaction history
sdk.payments       // Payment processing
sdk.analytics      // Reporting & insights
sdk.tenants        // Multi-tenant configuration
sdk.donations      // Charitable giving
sdk.files          // File operations
sdk.web3           // Blockchain operations

// Service Layer (Advanced Access)
sdk.users.getUserService()     // Direct service access
sdk.campaigns.getCampaignService()

Core Features

Authentication

• External JWT integration (Firebase, Auth0, etc.)
• Native token validation and refresh
• User and admin authentication flows

Business Management

• Business registration and profiles
• Business type management
• Public business discovery

Campaign System

• Marketing campaign management
• User campaign claims and participation
• Advanced campaign triggers and automation

Token Economy

• Token balance management
• Token transfers and transactions
• Multiple token type support

Reward Redemptions

• Redemption offer management
• User redemption tracking
• Multiple redemption types

Payment Processing

• Payment intent creation
• Purchase token management
• Transaction history

Configuration

interface PersConfig {
  environment?: 'development' | 'staging' | 'production';
  apiVersion?: 'v2';
  apiProjectKey: string;
  timeout?: number;
  retries?: number;
  authProvider?: PersAuthProvider;
}

Error Handling

import { PersApiError } from '@explorins/pers-sdk/core';

try {
  const user = await sdk.auth.getCurrentUser();
} catch (error) {
  if (error instanceof PersApiError) {
    console.error('PERS API Error:', error.message, error.statusCode);
  }
}

Bundle Size

• Core SDK: ~85 KB (minified)
• Tree-shaking friendly
• Zero external authentication dependencies
• Native browser API implementation

Documentation

For comprehensive documentation, examples, and advanced usage:

https://docs.pers.ninja/1.intro

For detailed API reference:

https://docs.pers.ninja/sdk (Interactive API Documentation)

Related Packages

• @explorins/pers-sdk-react-native - React Native integration
• @explorins/pers-shared - Shared types and utilities

License

MIT License