@explorins/pers-sdk 1.0.0-alpha.1

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@explorins/pers-sdk",
+  "version": "1.0.0-alpha.1",
+  "description": "Platform-agnostic SDK for PERS (Phygital Experience Rewards System)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/core.d.ts",
+      "import": "./dist/core.esm.js",
+      "require": "./dist/core.js"
+    },
+    "./business": {
+      "types": "./dist/business/index.d.ts",
+      "import": "./dist/business.esm.js",
+      "require": "./dist/business.js"
+    }
+  },
+ "scripts": {
+    "build": "rollup -c",
+    "build:watch": "rollup -c --watch",
+    "clean": "rimraf dist",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/**/*.ts"
+  },
+  "dependencies": {
+    "@explorins/pers-shared": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "@types/jest": "^29.5.12",
+    "jest": "^29.7.0",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "rollup": "^4.50.0",
+    "rimraf": "^5.0.5"
+  },
+  "peerDependencies": {
+    "@explorins/pers-shared": "*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": ["pers", "business", "sdk", "platform-agnostic"],
+  "author": "Explorins",
+  "license": "MIT"
+}

package/rollup.config.js

@@ -0,0 +1,78 @@
+import typescript from '@rollup/plugin-typescript';
+
+export default [
+  // Core entry point
+  {
+    input: 'src/core/core.ts',
+    output: [
+      {
+        file: 'dist/core.js',
+        format: 'cjs',
+        sourcemap: true
+      },
+      {
+        file: 'dist/core.esm.js',
+        format: 'esm',
+        sourcemap: true
+      }
+    ],
+    plugins: [
+      typescript({
+        tsconfig: './tsconfig.json',
+        declaration: true,
+        declarationDir: './dist'
+      })
+    ],
+    external: ['rxjs', 'rxjs/operators']
+  },
+  
+  // Business domain entry point
+  {
+    input: 'src/business/index.ts',
+    output: [
+      {
+        file: 'dist/business.js',
+        format: 'cjs',
+        sourcemap: true
+      },
+      {
+        file: 'dist/business.esm.js',
+        format: 'esm',
+        sourcemap: true
+      }
+    ],
+    plugins: [
+      typescript({
+        tsconfig: './tsconfig.json',
+        declaration: true,
+        declarationDir: './dist'
+      })
+    ],
+    external: ['@explorins/pers-shared', 'rxjs', 'rxjs/operators']
+  },
+  
+  // Main entry point (everything)
+  {
+    input: 'src/index.ts',
+    output: [
+      {
+        file: 'dist/index.js',
+        format: 'cjs',
+        sourcemap: true
+      },
+      {
+        file: 'dist/index.esm.js',
+        format: 'esm',
+        sourcemap: true
+      }
+    ],
+    plugins: [
+      typescript({
+        tsconfig: './tsconfig.json',
+        declaration: true,
+        declarationDir: './dist'
+      })
+    ],
+    external: ['@explorins/pers-shared', 'rxjs', 'rxjs/operators']
+  }
+];

package/src/business/api/business-api.ts

@@ -0,0 +1,72 @@
+import { PersApiClient } from '../../core/pers-api-client';
+import { BusinessDTO, BusinessTypeDTO, BusinessUpdateRequestDTO } from '@explorins/pers-shared';
+
+/**
+ * Platform-Agnostic Business API Client
+ * 
+ * Focuses on non-admin business operations using the PERS backend.
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ */
+export class BusinessApi {
+  constructor(private apiClient: PersApiClient) {}
+
+  /**
+   * Get all active businesses (public endpoint)
+   */
+  async getActiveBusinesses(): Promise<BusinessDTO[]> {
+    return this.apiClient.get<BusinessDTO[]>('/business');
+  }
+
+  /**
+   * Get all business types (public endpoint)
+   */
+  async getAllBusinessTypes(): Promise<BusinessTypeDTO[]> {
+    return this.apiClient.get<BusinessTypeDTO[]>('/business/type');
+  }
+
+  /**
+   * Get business by ID
+   */
+  async getBusinessById(businessId: string): Promise<BusinessDTO> {
+    return this.apiClient.get<BusinessDTO>(`/business/${businessId}`);
+  }
+
+  /**
+   * Get business by account address
+   */
+  async getBusinessByAccount(accountAddress: string): Promise<BusinessDTO> {
+    return this.apiClient.get<BusinessDTO>(`/business/account/${accountAddress}`);
+  }
+
+  // ==========================================
+  // ADMIN OPERATIONS
+  // ==========================================
+
+  /**
+   * ADMIN: Get all businesses (active and inactive)
+   */
+  async getAllBusinesses(): Promise<BusinessDTO[]> {
+    return this.apiClient.get<BusinessDTO[]>('/business/admin');
+  }
+
+  /**
+   * ADMIN: Create business by display name
+   */
+  async createBusinessByDisplayName(displayName: string): Promise<BusinessDTO> {
+    return this.apiClient.post<BusinessDTO>('/business/admin/', { displayName });
+  }
+
+  /**
+   * ADMIN: Update business
+   */
+  async updateBusiness(id: string, businessData: BusinessUpdateRequestDTO): Promise<BusinessDTO> {
+    return this.apiClient.put<BusinessDTO>(`/business/admin/${id}`, businessData);
+  }
+
+  /**
+   * ADMIN: Toggle business active status
+   */
+  async toggleBusinessActive(id: string, isActive: boolean): Promise<BusinessDTO> {
+    return this.apiClient.put<BusinessDTO>(`/business/admin/activate/${id}`, { isActive });
+  }
+}

package/src/business/business/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
+}

package/src/business/index.ts

@@ -0,0 +1,52 @@
+/**
+ * @explorins/pers-sdk-business
+ * 
+ * Platform-agnostic Business Domain SDK for PERS ecosystem
+ * Focuses on non-admin business operations
+ */
+
+// API Layer
+export { BusinessApi } from './api/business-api';
+
+// Service Layer  
+export { BusinessService } from './services/business-service';
+
+// Models & Types
+export * from './models';
+
+// Factory function for creating business SDK instance
+import { PersApiClient } from '../core/pers-api-client';
+import { BusinessApi } from './api/business-api';
+import { BusinessService } from './services/business-service';
+
+/**
+ * Create a complete Business SDK instance
+ * 
+ * @param apiClient - Configured PERS API client
+ * @returns Business SDK with flattened structure for better DX
+ */
+export function createBusinessSDK(apiClient: PersApiClient) {
+  const businessApi = new BusinessApi(apiClient);
+  const businessService = new BusinessService(businessApi);
+  
+  return {
+    // Direct access to service methods (primary interface)
+    getActiveBusinesses: () => businessService.getActiveBusinesses(),
+    getAllBusinessTypes: () => businessService.getAllBusinessTypes(),
+    getBusinessById: (businessId: string) => businessService.getBusinessById(businessId),
+    getBusinessByAccount: (accountAddress: string) => businessService.getBusinessByAccount(accountAddress),
+    getBusinessesByType: (typeId: string) => businessService.getBusinessesByType(typeId),
+    
+    // Admin methods
+    getAllBusinesses: () => businessService.getAllBusinesses(),
+    createBusinessByDisplayName: (displayName: string) => businessService.createBusinessByDisplayName(displayName),
+    updateBusiness: (id: string, businessData: any) => businessService.updateBusiness(id, businessData),
+    toggleBusinessActive: (id: string, isActive: boolean) => businessService.toggleBusinessActive(id, isActive),
+    
+    // Advanced access for edge cases
+    api: businessApi,
+    service: businessService
+  };
+}
+
+export type BusinessSDK = ReturnType<typeof createBusinessSDK>;

package/src/business/models/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Business Domain Models
+ * 
+ * Re-exports from @explorins/pers-shared for consistency with backend
+ * and to provide a single import source for business-related types.
+ */
+
+// Core business entities
+export type { 
+  BusinessDTO,
+  BusinessTypeDTO,
+  BusinessUpdateRequestDTO 
+} from '@explorins/pers-shared';

package/src/business/services/business-service.ts

@@ -0,0 +1,88 @@
+import { BusinessApi } from '../api/business-api';
+import { 
+  BusinessDTO, 
+  BusinessTypeDTO,
+  BusinessUpdateRequestDTO
+} from '../models';
+
+/**
+ * Platform-Agnostic Business Service
+ * 
+ * Contains business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * 
+ * Focuses only on actual backend capabilities.
+ */
+export class BusinessService {
+  constructor(private businessApi: BusinessApi) {}
+
+  /**
+   * Get all active businesses
+   */
+  async getActiveBusinesses(): Promise<BusinessDTO[]> {
+    return this.businessApi.getActiveBusinesses();
+  }
+
+  /**
+   * Get all business types
+   */
+  async getAllBusinessTypes(): Promise<BusinessTypeDTO[]> {
+    return this.businessApi.getAllBusinessTypes();
+  }
+
+  /**
+   * Get business by ID
+   */
+  async getBusinessById(businessId: string): Promise<BusinessDTO> {
+    return this.businessApi.getBusinessById(businessId);
+  }
+
+  /**
+   * Get business by account address
+   */
+  async getBusinessByAccount(accountAddress: string): Promise<BusinessDTO> {
+    return this.businessApi.getBusinessByAccount(accountAddress);
+  }
+
+  /**
+   * Get businesses by type (client-side filtering)
+   */
+  async getBusinessesByType(typeId: string): Promise<BusinessDTO[]> {
+    const businesses = await this.getActiveBusinesses();
+    return businesses.filter(business => 
+      business.businessType && business.businessType.id === parseInt(typeId)
+    );
+  }
+
+  // ==========================================
+  // ADMIN OPERATIONS
+  // ==========================================
+
+  /**
+   * ADMIN: Get all businesses (active and inactive)
+   */
+  async getAllBusinesses(): Promise<BusinessDTO[]> {
+    return this.businessApi.getAllBusinesses();
+  }
+
+  /**
+   * ADMIN: Create business by display name
+   */
+  async createBusinessByDisplayName(displayName: string): Promise<BusinessDTO> {
+    return this.businessApi.createBusinessByDisplayName(displayName);
+  }
+
+  /**
+   * ADMIN: Update business
+   */
+  async updateBusiness(id: string, businessData: BusinessUpdateRequestDTO): Promise<BusinessDTO> {
+    return this.businessApi.updateBusiness(id, businessData);
+  }
+
+  /**
+   * ADMIN: Toggle business active status
+   */
+  async toggleBusinessActive(id: string, isActive: boolean): Promise<BusinessDTO> {
+    return this.businessApi.toggleBusinessActive(id, isActive);
+  }
+}

package/src/core/abstractions/core-interfaces.ts

@@ -0,0 +1,56 @@
+/**
+ * Core SDK interfaces based on actual PERS Tourism Loyalty App patterns
+ * These interfaces reflect the real DDD architecture with Lazy Facade pattern
+ */
+
+// Core HTTP abstractions matching the app's ApiService patterns
+export interface CoreHttpClient {
+  get<T>(url: string, options?: any): Observable<T>;
+  post<T>(url: string, body: any, options?: any): Observable<T>;
+  put<T>(url: string, body: any, options?: any): Observable<T>;
+  delete<T>(url: string, options?: any): Observable<T>;
+}
+
+// Base facade interface reflecting the app's LazyClass pattern
+export interface CoreFacade {
+  [key: string]: any;
+}
+
+// Environment configuration interface based on LoyaltyEnvironment
+export interface CoreEnvironment {
+  production: boolean;
+  version: string;
+  apiVersion: string
+  apiRoot: string;
+  apiProjectKey?: string;
+}
+
+// State management interface reflecting the app's Signal-based patterns
+export interface CoreStateManager<T> {
+  state$: Observable<T>;
+  updateState(partialState: Partial<T>): void;
+  resetState(): void;
+}
+
+// Event system interface for cross-platform communication
+export interface CoreEventEmitter<T = any> {
+  emit(eventName: string, data?: T): void;
+  on(eventName: string, callback: (data?: T) => void): void;
+  off(eventName: string, callback?: (data?: T) => void): void;
+}
+
+// Service factory interface for platform-specific implementations
+export interface CoreServiceFactory {
+  createHttpClient(): CoreHttpClient;
+  createStateManager<T>(initialState: T): CoreStateManager<T>;
+  createEventEmitter<T>(): CoreEventEmitter<T>;
+}
+
+// Observable type for platform-agnostic reactive programming
+export interface Observable<T> {
+  subscribe(observer: {
+    next?: (value: T) => void;
+    error?: (error: any) => void;
+    complete?: () => void;
+  }): { unsubscribe(): void };
+}

package/src/core/abstractions/http-client.ts

@@ -0,0 +1,23 @@
+/**
+ * Platform-agnostic HTTP client interface
+ * To be implemented by platform-specific adapters (Angular, React Native, etc.)
+ */
+
+export interface HttpClient {
+  get<T>(url: string, options?: RequestOptions): Promise<T>;
+  post<T>(url: string, body: any, options?: RequestOptions): Promise<T>;
+  put<T>(url: string, body: any, options?: RequestOptions): Promise<T>;
+  delete<T>(url: string, options?: RequestOptions): Promise<T>;
+}
+
+export interface RequestOptions {
+  headers?: Record<string, string>;
+  params?: Record<string, string>;
+  timeout?: number;
+}
+
+export interface HttpResponse<T> {
+  data: T;
+  status: number;
+  headers: Record<string, string>;
+}

package/src/core/auth/auth-provider.interface.ts

@@ -0,0 +1,16 @@
+export interface AuthProvider {
+  getToken(): Promise<string | null>;
+  getProjectKey(): Promise<string | null>;
+  authType: 'admin' | 'user' | 'firebase';
+  onTokenExpired?: () => Promise<void>;
+}
+
+export interface RequestOptions {
+  headers?: Record<string, string>;
+}
+
+// Export simple auth config for dev-friendly usage
+export * from './simple-auth-config.interface';
+
+// Export auth provider factory and helpers
+export * from './create-auth-provider';

package/src/core/auth/create-auth-provider.ts

@@ -0,0 +1,136 @@
+import { AuthProvider } from './auth-provider.interface';
+import { SimpleAuthConfig } from './simple-auth-config.interface';
+
+/**
+ * Creates a platform-agnostic AuthProvider from simple configuration
+ * 
+ * This factory function is completely platform-agnostic and can be used
+ * across Angular, React, Vue, Node.js, or any other JavaScript environment.
+ * 
+ * Features:
+ * - Token caching with refresh support
+ * - Automatic token refresh on expiration
+ * - Configurable token providers
+ * - Platform-independent (no localStorage assumptions)
+ * 
+ * @param config - Simple auth configuration
+ * @returns AuthProvider implementation
+ */
+export function createAuthProvider(config: SimpleAuthConfig): AuthProvider {
+  // Store current token for refresh scenarios and caching
+  let currentToken: string | null = config.token || null;
+  let isRefreshing = false; // Prevent concurrent refresh attempts
+  let refreshPromise: Promise<void> | null = null;
+
+  return {
+    authType: config.authType || 'user',
+    
+    async getToken(): Promise<string | null> {
+      // If currently refreshing, wait for it to complete
+      if (isRefreshing && refreshPromise) {
+        await refreshPromise;
+        return currentToken;
+      }
+
+      // Use cached current token (updated after refresh)
+      if (currentToken) {
+        return currentToken;
+      }
+      
+      // Custom token provider function (always fresh)
+      if (config.tokenProvider) {
+        const token = await config.tokenProvider();
+        currentToken = token; // Cache for future calls
+        return token;
+      }
+      
+      // No token available
+      return null;
+    },
+    
+    async getProjectKey(): Promise<string | null> {
+      return config.projectKey || null;
+    },
+    
+    async onTokenExpired(): Promise<void> {
+      // Prevent concurrent refresh attempts
+      if (isRefreshing) {
+        if (refreshPromise) {
+          await refreshPromise;
+        }
+        return;
+      }
+
+      // No refresh logic provided
+      if (!config.onTokenExpired) {
+        console.warn('Token expired but no refresh logic provided');
+        currentToken = null; // Clear expired token
+        return;
+      }
+
+      // Start refresh process
+      isRefreshing = true;
+      refreshPromise = (async () => {
+        try {
+          // Execute refresh logic (should update token source)
+          await config.onTokenExpired!();
+          
+          // After refresh, get the new token
+          if (config.tokenProvider) {
+            const newToken = await config.tokenProvider();
+            if (newToken && newToken !== currentToken) {
+              currentToken = newToken;
+              
+              // Notify about successful token refresh
+              if (config.onTokenRefreshed) {
+                config.onTokenRefreshed(newToken);
+              }
+            } else {
+              console.warn('Token refresh completed but no new token received');
+              currentToken = null;
+            }
+          } else {
+            // For static token configs, clear the token since we can't refresh
+            console.warn('Token expired for static token config - clearing token');
+            currentToken = null;
+          }
+        } catch (error) {
+          console.error('Token refresh failed:', error);
+          currentToken = null; // Clear token on refresh failure
+          throw error; // Re-throw to let SDK handle the error
+        } finally {
+          isRefreshing = false;
+          refreshPromise = null;
+        }
+      })();
+
+      await refreshPromise;
+    }
+  };
+}
+
+/**
+ * Platform-specific localStorage token provider for browsers
+ * This is a convenience function for browser environments
+ */
+export function createBrowserTokenProvider(tokenKey: string = 'userJwt'): () => Promise<string | null> {
+  return async () => {
+    if (typeof localStorage !== 'undefined') {
+      return localStorage.getItem(tokenKey);
+    }
+    return null;
+  };
+}
+
+/**
+ * Platform-specific environment variable token provider for Node.js
+ * This is a convenience function for Node.js environments
+ */
+export function createNodeTokenProvider(envVar: string = 'JWT_TOKEN'): () => Promise<string | null> {
+  return async () => {
+    if (typeof process !== 'undefined' && process.env) {
+      return process.env[envVar] || null;
+    }
+    return null;
+  };
+}

package/src/core/auth/simple-auth-config.interface.ts

@@ -0,0 +1,15 @@
+/**
+ * Simple Auth Configuration Interface - Dev-Friendly Alternative
+ * 
+ * Instead of implementing AuthProvider, developers can use this simple config
+ * which will be automatically converted to a full AuthProvider implementation.
+ */
+export interface SimpleAuthConfig {
+  authType?: 'admin' | 'user' | 'firebase';
+  token?: string;
+  tokenProvider?: () => Promise<string | null>;
+  projectKey?: string;
+  onTokenExpired?: () => Promise<void>;
+  // Advanced: for reactive token updates after refresh
+  onTokenRefreshed?: (newToken: string) => void;
+}

package/src/core/core.ts

@@ -0,0 +1,30 @@
+/**
+ * @explorins/pers-sdk/core - Core SDK Entry Point
+ * 
+ * Platform-agnostic PERS API client and core functionality
+ */
+
+// Core PERS API client
+export * from './pers-api-client';
+
+// Configuration interfaces
+export * from './pers-config';
+
+// Authentication interfaces  
+export { 
+  AuthProvider, 
+  SimpleAuthConfig,
+  createAuthProvider,
+  createBrowserTokenProvider,
+  createNodeTokenProvider
+} from './auth/auth-provider.interface';
+export type { RequestOptions as AuthRequestOptions } from './auth/auth-provider.interface';
+
+// Platform abstractions
+export * from './abstractions/http-client';
+
+// Main SDK class
+export * from '../pers-sdk';
+
+// Version
+export const PERS_SDK_VERSION = '1.0.0-alpha.1';

package/src/core/pers-api-client.ts

@@ -0,0 +1,151 @@
+/**
+ * PERS API Client - Core platform-agnostic client for PERS backend
+ */
+
+import { HttpClient, RequestOptions } from './abstractions/http-client';
+import { PersConfig, buildApiRoot } from './pers-config';
+
+export class PersApiClient {
+  private readonly apiRoot: string;
+
+  constructor(
+    private httpClient: HttpClient,
+    private config: PersConfig
+  ) {
+    // Build API root from environment and version
+    this.apiRoot = buildApiRoot(config.environment, config.apiVersion);
+  }
+
+  /**
+   * Get request headers including auth token and project key
+   */
+  private async getHeaders(): Promise<Record<string, string>> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+
+    // Add authentication token
+    if (this.config.authProvider) {
+      const token = await this.config.authProvider.getToken();
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
+    }
+
+    // Add project key
+    if (this.config.authProvider) {
+      const projectKey = await this.config.authProvider.getProjectKey();
+      if (projectKey) {
+        headers['x-project-key'] = projectKey;
+      }
+    } else {
+      // Fallback to config project key if no auth provider
+      headers['x-project-key'] = this.config.apiProjectKey;
+    }
+
+    return headers;
+  }
+
+  /**
+   * Make a request with proper headers, auth, and error handling
+   */
+  private async request<T>(
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+    endpoint: string,
+    body?: any,
+    options?: { retryCount?: number }
+  ): Promise<T> {
+    const { retryCount = 0 } = options || {};
+    const url = `${this.apiRoot}${endpoint}`;
+    
+    const requestOptions: RequestOptions = {
+      headers: await this.getHeaders(),
+      timeout: this.config.timeout || 30000,
+    };
+
+    try {
+      switch (method) {
+        case 'GET':
+          return await this.httpClient.get<T>(url, requestOptions);
+        case 'POST':
+          return await this.httpClient.post<T>(url, body, requestOptions);
+        case 'PUT':
+          return await this.httpClient.put<T>(url, body, requestOptions);
+        case 'DELETE':
+          return await this.httpClient.delete<T>(url, requestOptions);
+        default:
+          throw new Error(`Unsupported HTTP method: ${method}`);
+      }
+    } catch (error: any) {
+      // Handle 401 errors with automatic token refresh
+      if (error.status === 401 && retryCount === 0 && this.config.authProvider?.onTokenExpired) {
+        try {
+          await this.config.authProvider.onTokenExpired();
+          // Retry once with refreshed token
+          return this.request<T>(method, endpoint, body, { ...options, retryCount: 1 });
+        } catch (refreshError) {
+          throw new PersApiError(
+            `Authentication refresh failed: ${refreshError}`, 
+            endpoint, 
+            method, 
+            401
+          );
+        }
+      }
+
+      throw new PersApiError(
+        `PERS API request failed: ${error.message || error}`, 
+        endpoint, 
+        method, 
+        error.status
+      );
+    }
+  }
+
+  /**
+   * Generic GET request
+   */
+  async get<T>(endpoint: string): Promise<T> {
+    return this.request<T>('GET', endpoint);
+  }
+
+  /**
+   * Generic POST request
+   */
+  async post<T>(endpoint: string, body?: any): Promise<T> {
+    return this.request<T>('POST', endpoint, body);
+  }
+
+  /**
+   * Generic PUT request
+   */
+  async put<T>(endpoint: string, body?: any): Promise<T> {
+    return this.request<T>('PUT', endpoint, body);
+  }
+
+  /**
+   * Generic DELETE request
+   */
+  async delete<T>(endpoint: string): Promise<T> {
+    return this.request<T>('DELETE', endpoint);
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): PersConfig {
+    return this.config;
+  }
+}
+
+export class PersApiError extends Error {
+  constructor(
+    message: string,
+    public endpoint: string,
+    public method: string,
+    public statusCode?: number
+  ) {
+    super(message);
+    this.name = 'PersApiError';
+  }
+}

package/src/core/pers-config.ts

@@ -0,0 +1,38 @@
+/**
+ * PERS SDK Configuration interfaces
+ */
+
+import { AuthProvider } from './auth/auth-provider.interface';
+
+export type PersEnvironment = 'development' | 'staging' | 'production';
+export type PersApiVersion = 'v1' | 'v1.8' | 'v1.9' | 'v2';
+
+export interface PersConfig {
+  environment: PersEnvironment;
+  apiProjectKey: string;
+  apiVersion?: PersApiVersion;
+  timeout?: number;
+  retries?: number;
+  authProvider?: AuthProvider;
+  // Internal - constructed automatically
+  readonly apiRoot?: string;
+}
+
+export interface PersAuthConfig {
+  type: 'firebase' | 'jwt' | 'none';
+  tokenProvider?: () => Promise<string | null>;
+}
+
+/**
+ * Internal function to construct API root from environment
+ */
+
+export function buildApiRoot(environment: PersEnvironment, version: PersApiVersion = 'v2'): string {
+  const baseUrls = {
+    development: 'https://explorins-loyalty.ngrok.io',
+    staging: `https://dev.api.pers.ninja/${version}`, 
+    production: `https://dev.api.pers.ninja/${version}`
+  };
+  
+  return `${baseUrls[environment]}`;
+}

package/src/core.ts

@@ -0,0 +1,30 @@
+/**
+ * @explorins/pers-sdk/core - Core SDK Entry Point
+ * 
+ * Platform-agnostic PERS API client and core functionality
+ */
+
+// Core PERS API client
+export * from './core/pers-api-client';
+
+// Configuration interfaces
+export * from './core/pers-config';
+
+// Authentication interfaces  
+export { 
+  AuthProvider, 
+  SimpleAuthConfig,
+  createAuthProvider,
+  createBrowserTokenProvider,
+  createNodeTokenProvider
+} from './core/auth/auth-provider.interface';
+export type { RequestOptions as AuthRequestOptions } from './core/auth/auth-provider.interface';
+
+// Platform abstractions
+export * from './core/abstractions/http-client';
+
+// Main SDK class
+export * from './pers-sdk';
+
+// Version
+export const PERS_SDK_VERSION = '1.0.0-alpha.1';

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @explorins/pers-sdk - Main Entry Point
+ * 
+ * Platform-agnostic PERS SDK - Core and Business domains only
+ */
+
+// Re-export everything from core
+export * from './core/core';
+
+// Re-export everything from business domain
+export * from './business';
+
+// NOTE: Angular integration available in separate package '@explorins/pers-sdk-angular'
+// Future domains will be added here
+// export * from './campaign';
+// export * from './challenge';

package/src/pers-sdk.ts

@@ -0,0 +1,45 @@
+/**
+ * PERS SDK - Minimal platform-agnostic client with built-in authentication
+ * Authentication is now handled at the SDK core level for better scalability
+ */
+
+import { HttpClient } from './core/abstractions/http-client';
+import { PersConfig } from './core/pers-config';
+import { PersApiClient } from './core/pers-api-client';
+
+/**
+ * Minimal PERS SDK - API client with authentication built-in
+ * Platform adapters provide auth providers and HTTP clients
+ */
+export class PersSDK {
+  private apiClient: PersApiClient;
+
+  constructor(httpClient: HttpClient, config: PersConfig) {
+    this.apiClient = new PersApiClient(httpClient, config);
+  }
+
+  /**
+   * Get the API client for direct PERS API calls
+   * This is the main interface - keep it simple!
+   */
+  api(): PersApiClient {
+    return this.apiClient;
+  }
+
+  /**
+   * Quick config check
+   */
+  isProduction(): boolean {
+    return this.apiClient.getConfig().environment === 'production';
+  }
+}
+
+/**
+ * Simple factory function
+ */
+export function createPersSDK(
+  httpClient: HttpClient,
+  config: PersConfig
+): PersSDK {
+  return new PersSDK(httpClient, config);
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext", 
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": ".",
+    "paths": {
+      "@explorins/pers-shared": ["../../framework/entities"]
+    }
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ]
+}