PERS SDK Introduction

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

npm install @explorins/pers-sdk

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'
});

// Login with external JWT (Firebase, Auth0, etc.)
await sdk.auth.loginWithToken(firebaseJWT, 'user');

// Check authentication status
if (await sdk.auth.isAuthenticated()) {
  const user = await sdk.auth.getCurrentUser();
  console.log('Welcome,', user.name);
}

// Business operations
const businesses = await sdk.businesses.getActiveBusinesses();
const business = await sdk.businesses.getBusinessById('business-123');

// Campaign management
const campaigns = await sdk.campaigns.getActiveCampaigns();
const claim = await sdk.campaigns.claimCampaign({
  campaignId: 'campaign-123',
  businessId: 'business-456'  // Optional business context
});

// Token operations - get available tokens
const tokens = await sdk.tokens.getTokens();
const creditToken = await sdk.tokens.getActiveCreditToken();

// Transaction history
const transactions = await sdk.transactions.getUserTransactionHistory('user-456');

// File operations
const uploadUrl = await sdk.files.getSignedPutUrl('entity-123', 'profile-image', 'jpg');
const downloadUrl = await sdk.files.getSignedGetUrl('entity-123', 'profile-image');

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;
  }
}

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'
});

// React Hook example
export function usePersSDK() {
  return sdk;
}

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'
});

const userService = sdk.users.getUserService();
const campaignService = sdk.campaigns.getCampaignService();
const fileService = sdk.files.getFileService();

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

// Auto-created provider (recommended)
const sdk = new PersSDK(httpClient, {
  environment: 'production',
  apiProjectKey: 'your-key'
});

// Custom provider
const sdk = new PersSDK(httpClient, {
  environment: 'production',
  apiProjectKey: 'your-key',
  authProvider: customAuthProvider
});

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

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

// Full type inference
const campaigns = await sdk.campaigns.getActiveCampaigns(); // CampaignDTO[]
const business = await sdk.businesses.getBusinessById('123'); // BusinessDTO

// Generic support for custom types
const customData = await sdk.api().get<CustomType>('/custom-endpoint');

const apiClient = sdk.api();
const customData = await apiClient.get('/custom-endpoint');
await apiClient.post('/custom-endpoint', data);

import { HttpClient, RequestOptions } from '@explorins/pers-sdk/core';

class CustomHttpClient implements HttpClient {
  async get<T>(url: string, options?: RequestOptions): Promise<T> {
    // Your implementation
  }
  // ... other methods
}

const sdk = new PersSDK(new CustomHttpClient(), config);