@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.

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

Usage

`bash
npm install @explorins/pers-shared
`

$3


`typescript
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);
}
}
`

$3


`typescript
// 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 = ({ user }) => (

{user.email}

Wallet: {user.walletAddress?.getValue()}

);
`

🔧 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:

`typescript
// 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