# PERS Developer Resources

Essential tools, libraries, and resources for PERS API integration.

## Official Libraries

### **@explorins/pers-shared**

The official TypeScript library providing type-safe contracts and DTOs for PERS API integration.

> **📦 Package Size vs Runtime Impact**: While the npm package is 1.2 MB (includes comprehensive TypeScript definitions), modern bundlers with tree-shaking typically include only 0.44-0.67 KB in your final bundle - that's 99.9%+ elimination!


#### **Installation**


```bash
npm install @explorins/pers-shared
```

#### **Library Information**

- **Package Name**: `@explorins/pers-shared`
- **Registry**: [npmjs.org](https://www.npmjs.com/package/@explorins/pers-shared)
- **License**: MIT
- **Maintainer**: eXplorins Development Team


#### **What's Included**

- **DTOs**: Complete type definitions for all API request/response objects
- **Interfaces**: TypeScript contracts for authentication, users, campaigns, transactions
- **Types & Enums**: Authentication types, error codes, transaction statuses
- **Value Objects**: Immutable data structures like `Address`, `StructuredError`
- **Error Classes**: Structured domain errors (`AuthenticationRequiredError`, `AuthorizationFailedError`, etc.)


#### **Usage Examples**

##### **Backend/Node.js Integration**


```typescript
import { 
  UserDTO, 
  TransactionStatus, 
  AuthenticationRequiredError,
  PasskeysAuthRequestDTO,
  UserAuthResponseDTO 
} 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);
  console.log(`Authenticated user: ${user.email}`);
} catch (error) {
  if (error instanceof AuthenticationRequiredError) {
    console.error('Authentication failed:', error.message);
    // Handle authentication error with proper error code
  }
}

// Type-safe response handling
async function authenticateUser(token: string): Promise<UserAuthResponseDTO> {
  const response = await fetch('/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ authToken: token })
  });
  
  return response.json() as Promise<UserAuthResponseDTO>;
}
```

##### **Frontend/Browser Integration**


```typescript
// Browser-optimized import for smaller bundle size
import { UserDTO, CampaignDTO, Address } from '@explorins/pers-shared/browser';

// Type-safe API client interface
interface PERSApiClient {
  authenticate(request: PasskeysAuthRequestDTO): Promise<UserAuthResponseDTO>;
  getBalance(userId: string): Promise<UserTokenBalancesDTO>;
  getCampaigns(): Promise<CampaignDTO[]>;
}

// React component example
import React from 'react';
import type { UserTokenBalancesDTO } from '@explorins/pers-shared/browser';

interface UserBalanceProps {
  user: UserTokenBalancesDTO;
}

const UserBalance: React.FC<UserBalanceProps> = ({ user }) => {
  return (
    <div>
      <h2>{user.email}</h2>
      <p>Wallet: {user.walletAddress?.getValue()}</p>
      {user.tokenBalances?.map(balance => (
        <div key={balance.tokenId}>
          {balance.tokenName}: {balance.balance}
        </div>
      ))}
    </div>
  );
};
```

##### **Vue.js Integration**


```typescript
// Vue 3 with Composition API
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import type { UserDTO, CampaignDTO } from '@explorins/pers-shared/browser';

const user = ref<UserDTO | null>(null);
const campaigns = ref<CampaignDTO[]>([]);

onMounted(async () => {
  // Type-safe API calls with full IntelliSense
  const userResponse = await fetch('/api/user/me');
  user.value = await userResponse.json() as UserDTO;
  
  const campaignsResponse = await fetch('/api/campaigns');
  campaigns.value = await campaignsResponse.json() as CampaignDTO[];
});
</script>
```

#### **Build Configurations**

- **CommonJS**: Backend compatibility with NestJS/Swagger support
- **ESM**: Frontend optimization with tree-shaking
- **TypeScript Declarations**: Full type support for IDEs and editors
- **Browser Entry Point**: Optimized for frontend frameworks (React, Vue, Angular)


#### **Key Features**

- **Exceptional Tree Shaking**: 99.9%+ code elimination - only 0.44 KB runtime from 1.2 MB package
- **Zero Dependencies**: Pure TypeScript contracts with no runtime dependencies
- **Dual Build System**: Supports both CommonJS (Node.js) and ESM (browsers)
- **Type Safety**: Comprehensive TypeScript definitions for all PERS APIs
- **Authentication Support**: All authentication DTOs and error classes included
- **Minimal Runtime**: Import only what you need - typical usage < 1 KB
- **Framework Agnostic**: Works with React, Vue, Angular, vanilla JS, and Node.js


## Development Tools

### **IDE Support**

#### **VS Code**

The library provides full IntelliSense support:

- **Auto-completion**: All PERS types and interfaces
- **Error Detection**: TypeScript validation for API contracts
- **Quick Info**: Hover documentation for all DTOs
- **Go to Definition**: Navigate to type definitions


#### **WebStorm/IntelliJ**

Full TypeScript integration:

- **Smart Code Completion**: Context-aware suggestions
- **Refactoring Support**: Rename and restructure with confidence
- **Error Highlighting**: Real-time validation
- **Import Organization**: Auto-import management


### **Build Tool Integration**

#### **Webpack**


```javascript
// webpack.config.js - Tree shaking configuration
module.exports = {
  optimization: {
    usedExports: true,
    sideEffects: false // @explorins/pers-shared is side-effect free
  }
};
```

#### **Vite**


```javascript
// vite.config.js - Optimized for PERS library
import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    include: ['@explorins/pers-shared']
  }
});
```

#### **Rollup**


```javascript
// rollup.config.js - Tree shaking optimization
export default {
  external: ['@explorins/pers-shared'],
  output: {
    format: 'es'
  }
};
```

## API Documentation

### **Interactive Documentation**

- **Swagger UI**: Available at `/swagger` when running PERS API server
- **OpenAPI Spec**: Complete API specification with examples
- **Postman Collection**: Ready-to-use API collection for testing


### **Code Examples Repository**

- **GitHub**: [PERS API Examples](https://github.com/eXplorins/pers-api-examples)
- **Integration Patterns**: Common use cases and implementations
- **Sample Applications**: Full working examples in different frameworks


## Community & Support

### **Official Channels**

- **Documentation**: [docs.pers.ninja](https://docs.pers.ninja)
- **API Status**: [status.pers.ninja](https://status.pers.ninja)
- **Developer Portal**: [developers.pers.ninja](https://developers.pers.ninja)


### **Getting Help**

- **Technical Support**: Contact integration team for API assistance
- **Bug Reports**: Submit issues through official channels
- **Feature Requests**: Propose enhancements via developer portal


## Getting Started with Development

### **Quick Setup**

1. **Install the Library**

```bash
npm install @explorins/pers-shared
```
2. **Set Up TypeScript**

```json
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}
```
3. **Configure Your IDE**
  - Enable TypeScript language service
  - Install PERS-specific extensions (if available)
  - Set up auto-import preferences
4. **Start Building**

```typescript
import { UserDTO } from '@explorins/pers-shared';

// Your PERS integration starts here!
```


### **Next Steps**

- Review the [Authentication Guide](/4.authentication-guide) for API access setup
- Explore the [Platform Overview](/2.platform-overview) for architectural understanding
- Check the interactive API documentation for endpoint details
- Join the developer community for best practices and support


## Migration from Previous API Versions

### **V2 Performance Improvements**

PERS API V2 delivers substantial performance enhancements across all operations:

- **Faster Response Times**: Up to 3x improvement in API response speeds
- **Enhanced Scalability**: Optimized infrastructure handles higher concurrent loads
- **Reduced Latency**: Streamlined request processing with improved efficiency
- **Better Resource Usage**: Optimized memory and processing patterns


### **Breaking Changes in V2**

PERS API V2 introduces significant improvements but requires migration from previous versions:

#### **URL Structure Changes (Major Breaking Change)**

- **Plural Resource Names**: All endpoints now use plural naming conventions
  - `/campaign` → `/campaigns`
  - `/user` → `/users`
  - `/token` → `/tokens`
  - `/balance` → `/balances`
  - `/redemption` → `/redemptions`
- **RESTful Paths**: Role-agnostic URLs with decorator-based authorization
- **Nested Resources**: Improved resource relationships (e.g., `/campaign-claims`, `/campaign-triggers`)


#### **Enhanced API Patterns**

- **Unified Authentication**: Streamlined `/auth/token` endpoint for multiple flows
- **Structured Errors**: Enhanced error responses with correlation IDs and security filtering
- **Consistent DTOs**: Standardized data transfer objects across all endpoints


#### **Migration Steps**

1. **Update Library**: Install latest `@explorins/pers-shared` for new types
2. **Update URLs**: Change all endpoint URLs to use plural resource names
3. **Review Authentication**: Verify authentication patterns work with new endpoints
4. **Error Handling**: Update error handling for new structured error format
5. **Testing**: Validate integration in sandbox environment before production


#### **Performance Benefits**

Migrating to V2 provides immediate performance benefits with no additional configuration required. Applications typically see faster response times and improved reliability upon migration.

#### **Backward Compatibility**

Legacy endpoints remain functional during transition period. Contact support for migration timeline and assistance.

For detailed migration assistance, contact our integration team.