spaps-types/README.md

Shared TypeScript types for SPAPS ecosystem

# spaps-types

Shared TypeScript type definitions for the Sweet Potato Authentication & Payment Service (SPAPS) ecosystem.

## Overview

This package provides a single source of truth for all TypeScript types used across the SPAPS server and SDK. It ensures type consistency and prevents drift between different parts of the system.

## Installation

```bash
npm install spaps-types
```

## Usage

```typescript
import type {
  User,
  UserProfile,
  ApiResponse,
  TokenPair,
  CheckoutSession,
  Product,
  Price
} from 'spaps-types';

// Use the types in your code
const user: User = {
  id: '123',
  email: 'user@example.com',
  role: 'user'
};

const response: ApiResponse<User> = {
  success: true,
  data: user
};
```

## Available Types

### Core Domain Models
- `Application` - Client application configuration
- `User` - Basic user information
- `UserProfile` - Extended user profile
- `UserWallet` - Multi-wallet associations

### Authentication & Session
- `TokenPayload` - JWT token payload
- `RefreshTokenPayload` - Refresh token payload  
- `TokenPair` - Access/refresh token pair
- `AuthResponse` - Authentication response
- `SessionData` - Session information

### Payments & Subscriptions
- `Product` - Stripe product
- `Price` - Stripe price
- `CheckoutSession` - Stripe checkout session
- `Subscription` - Active subscription
- `UsageBalance` - Usage-based balance

### API Types
- `ApiResponse<T>` - Standard API response wrapper
- `ApiKeyValidationResult` - API key validation result
- `TokenValidationResult` - Token validation result

### Admin Types
- `AdminUser` - Admin user information
- `AdminAction` - Audit log entry
- `SecurityAlert` - Security alert
- `AdminRole` - Admin role types
- `AdminPermission` - Permission types

### Request/Response DTOs
- `CreateProductRequest` - Create product payload
- `UpdateProductRequest` - Update product payload
- `CreatePriceRequest` - Create price payload
- `ProductSyncResult` - Product sync result

## Type Guards

The package includes runtime type guards for validation:

```typescript
import { isAdminRole, isValidPermission } from 'spaps-types';

if (isAdminRole(user.role)) {
  // User is an admin
}

if (isValidPermission(permission)) {
  // Permission is valid
}
```

## Development

```bash
# Build the types
npm run build

# Run type tests
npm run test:types

# Type check
npm run typecheck
```

## License

MIT