@explorins/pers-shared

Public Contracts Library

Pure data contracts for frontends, third-party integrations, and API consumers.

Bundle Size

• Browser Bundle: 0.44 KB (0.30 KB gzipped)
• Full Bundle: 0.67 KB (0.38 KB gzipped)
• CommonJS: 1.53 KB (0.72 KB gzipped)
• Package Size: 1.2 MB (includes all TypeScript definitions)
• Runtime Impact: < 1 KB with tree shaking

Contents

• DTOs - Complete API data transfer objects with validation
• Interfaces - TypeScript contracts for authentication, users, campaigns, transactions
• Types & Enums - Authentication types, error codes, transaction statuses
• Value Objects - Immutable data structures (Address, StructuredError)
• Error Classes - Structured domain errors (AuthenticationRequiredError, etc.)
• Domain Vocabulary - Domains for SDK events, ErrorDomains for error classification

Critical Build Configuration

SWAGGER COMPATIBILITY ISSUE: This library requires "moduleResolution": "node16" in tsconfig.json to prevent circular dependency errors with NestJS Swagger. Using "node" caused 3 days of debugging for Swagger generation failures.

{
  "compilerOptions": {
    "moduleResolution": "node16", // CRITICAL: Required for Swagger compatibility
    "target": "ES2022",
    "module": "CommonJS"
  }
}

Usage

npm install @explorins/pers-shared

Backend/Node.js

import { 
  UserDTO, 
  TransactionStatus, 
  AuthenticationRequiredError,
  PasskeysAuthRequestDTO 
} from '@explorins/pers-shared';

// Type-safe API requests
const authRequest: PasskeysAuthRequestDTO = {
  authToken: "external_provider_jwt_token"
};

// Structured error handling
try {
  const user = await authenticate(authRequest);
} catch (error) {
  if (error instanceof AuthenticationRequiredError) {
    console.error('Authentication failed:', error.code);
  }
}

Frontend/Browser (Ultra-Light)

// Browser-optimized import - Tree-shaken to 0.44 KB!
import { UserDTO, CampaignDTO, Address } from '@explorins/pers-shared/browser';

// React example with full type safety
interface UserBalanceProps {
  user: UserTokenBalancesDTO;
}

const UserBalance: React.FC<UserBalanceProps> = ({ user }) => (
  <div>
    <h2>{user.email}</h2>
    <p>Wallet: {user.walletAddress?.getValue()}</p>
  </div>
);

🔧 Build System & Performance

• Dual Builds: CommonJS (Node.js) + ESM (browsers) with automatic selection
• Exceptional Tree Shaking: 99.9%+ elimination (1.2 MB package → 0.44 KB runtime)
• Zero Runtime: Pure type definitions with no execution overhead
• Framework Agnostic: React, Vue, Angular, vanilla JS, Node.js

�️ Domain Vocabulary

Unified domain names for SDK event categorization and error classification:

// SDK success events - business domains only
import { Domains, Domain } from '@explorins/pers-shared';

onSuccess(event: { domain: Domain }) {
  if (event.domain === Domains.TRANSACTION) { ... }
}

// SDK error handler - includes technical categories
import { ErrorDomains, ErrorDomain } from '@explorins/pers-shared';

onError(error: { domain: ErrorDomain }) {
  if (error.domain === ErrorDomains.VALIDATION) { ... }
}

�🎯 Key Benefits

• Type Safety: Catch API integration errors at compile time
• Developer Experience: Full IntelliSense and auto-completion
• Performance: Exceptional tree-shaking (1.2 MB → 0.44 KB runtime)
• Reliability: Contracts match exact PERS API specifications