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

# Core SDK + required peer dependencies
npm install @explorins/pers-sdk @explorins/pers-shared ethers@^6.15.0

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

const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
  environment: "production",
  // API Project Key is used to identify the Tenant Context.
  // It does NOT authenticate the user or admin.
  apiProjectKey: "your-project-key"
});

// Login with external JWT (Firebase, Auth0, etc.)
// This wraps the /auth/token endpoint using SessionAuthRequestDTO
await sdk.auth.loginWithToken(firebaseJWT, "user");

// Alternative: Login with raw user data (guest/anonymous users)
await sdk.auth.loginWithRawData({
  externalId: "guest-123",
  email: "guest@example.com",
  firstName: "Guest"
});

// 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('ALL');

// 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" // Tenant Context ID
    });
  }

  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?: "production";  // Currently only production is available
  apiProjectKey: string; // Tenant Context Identifier (NOT for Auth)
  authStorage?: TokenStorage;  // Default: LocalStorage, recommend IndexedDB
  dpop?: { enabled?: boolean }; // Default: true (security feature)
  timeout?: number;
  retries?: 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, AuthenticationError } from "@explorins/pers-sdk/core";

try {
  const user = await sdk.auth.getCurrentUser();
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle 401 - redirect to login
  } else if (error instanceof PersApiError) {
    console.error("API Error:", error.message, error.status);
  }
}

import type { CampaignDTO, BusinessDTO, TokenDTO } from '@explorins/pers-shared';

const campaigns = await sdk.campaigns.getActiveCampaigns(); // CampaignDTO[]

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

// Get reward tokens configuration
const rewardTokens = await sdk.tokens.getRewardTokens();

// Query owned tokens for any wallet address
const result = await sdk.web3.getAccountOwnedTokensFromContract(
  walletAddress,
  rewardTokens[0]
);

console.log(`Wallet owns ${result.totalOwned} tokens`);
result.ownedTokens.forEach(token => {
  console.log(`- ${token.metadata?.name}: ${token.balance}`);
});

// Get blockchain explorer URL
const explorerUrl = await sdk.web3.getExplorerUrl(
  chainId,
  transactionHash,
  'tx'
);