# @iota-big3/sdk-types

TypeScript type definitions and runtime utilities for the IOTA Big3 SDK ecosystem.

## Installation

```bash
npm install @iota-big3/sdk-types
```

## Features

### Type Definitions

- **Common Types**: Express, Redis, Auth, Caching interfaces
- **Error Classes**: Comprehensive error hierarchy with proper inheritance
- **Compliance Types**: FERPA, HIPAA, GDPR validation types
- **Utility Types**: Advanced TypeScript utility types

### Runtime Utilities (New!)

- **Type Guards**: Runtime type checking for compile-time types
- **Factory Functions**: Create properly typed objects
- **Validators**: Validate configuration and compliance

## Usage

### Type Guards

```typescript
import { isAuthUser, isApiError, isValidJsonValue } from "@iota-big3/sdk-types";

// Check if an object is a valid AuthUser
const user = await getUser();
if (isAuthUser(user)) {
  console.log(user.id); // TypeScript knows this is safe
}

// Validate JSON values
const data = JSON.parse(response);
if (isValidJsonValue(data)) {
  // Safe to use as JsonValue
}
```

### Factory Functions

```typescript
import {
  createApiResponse,
  createAuthUser,
  createComplianceViolation,
} from "@iota-big3/sdk-types";

// Create a typed API response
const response = createApiResponse({
  data: { id: "123", name: "Test" },
  // meta is auto-generated with timestamp, version, requestId
});

// Create an AuthUser
const user = createAuthUser({
  id: "user-123",
  email: "user@example.com",
  roles: ["admin"],
});

// Create a compliance violation
const violation = createComplianceViolation({
  rule: "FERPA_CONSENT",
  severity: "high",
  message: "Missing parental consent for student data access",
});
```

### Validators

```typescript
import {
  validateSDKConfig,
  validateEnvironment,
  validateComplianceFramework,
} from "@iota-big3/sdk-types";

// Validate SDK configuration
const configResult = validateSDKConfig(config);
if (!configResult.valid) {
  console.error("Invalid config:", configResult.errors);
}

// Validate environment
if (validateEnvironment(process.env.NODE_ENV)) {
  // TypeScript knows this is 'development' | 'staging' | 'production'
}

// Validate compliance framework
if (validateComplianceFramework("FERPA")) {
  // Valid framework
}
```

## Integration with Other SDKs

While sdk-types doesn't require infrastructure services, it provides the type contracts that enable integration between other SDKs:

```typescript
// Other SDKs use these types for consistency
import { AuthUser, ApiResponse, DomainEvent } from "@iota-big3/sdk-types";

export class MySDK {
  async getUser(id: string): Promise<ApiResponse<AuthUser>> {
    // Implementation
  }

  emit(event: DomainEvent): void {
    // Implementation
  }
}
```

## Documentation

See [https://docs.iota-big3.com](https://docs.iota-big3.com) for full documentation.

## License

MIT