# FRE-4524 - Create spamshield.routes.ts with spam classification endpoints

## Parent Issue
FRE-4507 - Implement Redis rate limiting middleware

## Goal ID
2c5a8678-b505-4e9c-8ec4-c41faa9626ff

## Description
Create a new `spamshield.routes.ts` file that exposes spam classification API endpoints with rate limit middleware integration.

### Required Endpoints

#### POST /api/v1/spam/classify/sms
Classify an SMS message as spam or not spam.

**Request Body:**
```typescript
{
  phoneNumber: string;      // E.164 format
  message: string;
  userId: string;
  tier: 'BASIC' | 'PLUS' | 'PREMIUM';
}
```

**Response:**
```typescript
{
  isSpam: boolean;
  score: number;
  features: string[];
  rateLimit: {
    remaining: number;
    resetAt: Date;
    limit: number;
  };
}
```

**Rate Limit:** Applied via spam-rate-limit.middleware.ts

#### POST /api/v1/spam/classify/call
Classify a call based on metadata and context.

**Request Body:**
```typescript
{
  phoneNumber: string;      // E.164 format
  callMetadata: {
    duration?: number;
    timeOfDay?: string;
    frequency?: number;
  };
  userId: string;
  tier: 'BASIC' | 'PLUS' | 'PREMIUM';
}
```

**Response:**
```typescript
{
  decision: 'BLOCK' | 'FLAG' | 'ALLOW';
  confidence: number;
  reasons: string[];
  rateLimit: {
    remaining: number;
    resetAt: Date;
    limit: number;
  };
}
```

**Rate Limit:** Applied via spam-rate-limit.middleware.ts

#### GET /api/v1/spam/rate-limit/status
Get current rate limit status for a user.

**Query Parameters:**
- `userId`: string (required)
- `tier`: 'BASIC' | 'PLUS' | 'PREMIUM' (required)

**Response:**
```typescript
{
  userId: string;
  tier: string;
  currentLimits: {
    perMinute: {
      used: number;
      limit: number;
      remaining: number;
      resetAt: Date;
    };
    perDay: {
      used: number;
      limit: number;
      remaining: number;
      resetAt: Date;
    };
  };
}
```

## Acceptance Criteria
- [ ] Create `services/spamshield/src/routes/spamshield.routes.ts`
- [ ] Implement POST /api/v1/spam/classify/sms endpoint
- [ ] Implement POST /api/v1/spam/classify/call endpoint
- [ ] Implement GET /api/v1/spam/rate-limit/status endpoint
- [ ] Integrate spam-rate-limit.middleware.ts for classification endpoints
- [ ] Return rate limit metadata in responses
- [ ] Handle 429 responses when limits exceeded
- [ ] Proper TypeScript typing for request/response objects
- [ ] Export route registrar function

## File to Create
`services/spamshield/src/routes/spamshield.routes.ts`

## Dependencies
- FRE-4522 (spamshield.config.ts with rate limit structure)
- FRE-4523 (spam-rate-limit.middleware.ts)
- `@shieldai/types` (for type definitions)

## Priority
MEDIUM (Depends on middleware implementation)

## Status
todo

## Assigned To
d20f6f1c-1f24-4405-a122-2f93e0d6c94a (Founding Engineer)

## Notes
Routes should follow the existing pattern in `packages/api/src/routes/` for consistency. The spamshield service routes will be registered in the API gateway.