npm package: @onestopgrowth/iqdid-contracts
Description: API contracts and types shared between IQDID frontend and backend
Author: IQDID Team
Latest version: 1.0.1

# @iqdid/contracts

**API contracts and types shared between IQDID frontend and backend**

## Purpose

This package contains the **contract boundary** between IQDIDFrontEnd and IQDIDbackend repositories. It includes ONLY:

- ✅ API request/response DTOs
- ✅ XState event names and state IDs
- ✅ Agent result envelopes
- ✅ Error codes and problem details
- ✅ Validation schemas

It does NOT include:
- ❌ Database schemas (Drizzle ORM)
- ❌ Backend utilities
- ❌ Cryptographic primitives
- ❌ Frontend components
- ❌ Implementation details

## Installation

```bash
# In IQDIDbackend
npm install file:../@iqdid-contracts

# In IQDIDFrontEnd
npm install file:../@iqdid-contracts
```

## Usage

### Frontend (safeParse pattern)

```typescript
import { 
  NonceRequest, 
  NonceRequestSchema,
  VERIFICATION_EVENTS,
  ErrorCode 
} from '@iqdid/contracts';

// Validate user input
const result = NonceRequestSchema.safeParse(data);
if (!result.success) {
  toast({ 
    title: "Invalid input", 
    description: result.error.message 
  });
  return;
}

// Use validated data
const request: NonceRequest = result.data;
```

### Backend (parse pattern)

```typescript
import { 
  NonceRequest,
  NonceRequestSchema,
  CONTRACT_VERSION 
} from '@iqdid/contracts';

// Validate and throw on invalid
app.post('/api/auth/nonce', (req, res) => {
  const validated = NonceRequestSchema.parse(req.body); // Throws if invalid
  // ... process valid request
});

// Expose contract version
app.get('/api/meta/contracts', (req, res) => {
  res.json({ version: CONTRACT_VERSION });
});
```

### XState Events

```typescript
import { VERIFICATION_EVENTS } from '@iqdid/contracts';

// Emit cross-boundary events only
send({ type: VERIFICATION_EVENTS.SUBMIT_VOICE });

// ❌ Do NOT emit these from internal machine logic
```

## Contract Version

Current version: **1.0.0**

Backend should expose at `/api/meta/contracts` for compatibility checking.

## Development

```bash
# Build
npm run build

# Watch mode
npm run watch

# Clean
npm run clean
```

## Important Rules

### 1. These are STABLE contracts
- Event names must NOT be renamed without coordination
- State IDs must remain stable
- DTOs must maintain backward compatibility

### 2. Frontend uses safeParse
- Frontend must use `.safeParse()` and handle errors gracefully
- Never use `.parse()` in frontend (it throws)

### 3. Backend uses parse
- Backend must use `.parse()` and reject invalid deterministically
- Validation errors should return proper HTTP status codes

### 4. Evidence references only
- Agent results include `evidenceRef` fields
- These store CIDs, hashes, or internal references
- Never store raw PII or biometric data in contracts

## Package Structure

```
@iqdid/contracts/
├── src/
│   ├── api/              # API DTOs
│   ├── xstate/           # XState identifiers
│   ├── agents/           # Agent envelopes
│   ├── errors/           # Error codes
│   ├── validation/       # Zod schemas
│   └── meta/             # Contract version
└── dist/                 # Compiled output
```

## Versioning

This package follows semantic versioning:
- **MAJOR**: Breaking changes to contracts
- **MINOR**: New contracts added (backward compatible)
- **PATCH**: Documentation or non-functional changes

## License

MIT