# User Service API

> REST API documentation for the Aphrodite User Service.

**Base URL:** `https://api.aphrodite.example.com/api/v1` **Port:** 3000
**Authentication:** JWT Bearer Token (unless noted)

---

## Table of Contents

1. [Authentication](#authentication)
2. [User Profile](#user-profile)
3. [Creator Profile](#creator-profile)
4. [Settings](#settings)
5. [Social Features](#social-features)
6. [Fan Clubs](#fan-clubs)
7. [Subscriptions](#subscriptions)

---

## Authentication

### Register User

Create a new user account.

```http
POST /register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecureP@ssw0rd!",
  "username": "johndoe",
  "displayName": "John Doe",
  "dateOfBirth": "1990-05-15",
  "acceptedTerms": true,
  "acceptedPrivacy": true
}
```

**Response (201 Created):**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "username": "johndoe",
      "displayName": "John Doe",
      "verified": false,
      "createdAt": "2026-01-18T12:00:00.000Z"
    },
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
    "expiresIn": 900
  }
}
```

**Validation Rules:**

| Field           | Rules                                           |
| --------------- | ----------------------------------------------- |
| `email`         | Valid email format, unique                      |
| `password`      | Min 8 chars, 1 uppercase, 1 lowercase, 1 number |
| `username`      | 3-30 chars, alphanumeric + underscore, unique   |
| `displayName`   | 2-50 chars                                      |
| `dateOfBirth`   | Must be 18+ years old                           |
| `acceptedTerms` | Must be `true`                                  |

**Error Responses:**

| Code | Error             | Description                    |
| ---- | ----------------- | ------------------------------ |
| 400  | `INVALID_EMAIL`   | Invalid email format           |
| 400  | `WEAK_PASSWORD`   | Password doesn't meet criteria |
| 400  | `UNDERAGE`        | User is under 18               |
| 409  | `EMAIL_EXISTS`    | Email already registered       |
| 409  | `USERNAME_EXISTS` | Username already taken         |

---

### Login

Authenticate with email and password.

```http
POST /login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecureP@ssw0rd!"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "username": "johndoe",
      "displayName": "John Doe",
      "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_abc123.jpg",
      "verified": true,
      "isCreator": false,
      "createdAt": "2026-01-18T12:00:00.000Z"
    },
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
    "expiresIn": 900,
    "requiresTwoFactor": false
  }
}
```

**Two-Factor Authentication Required:**

```json
{
  "success": true,
  "data": {
    "requiresTwoFactor": true,
    "twoFactorToken": "2fa_temp_token_xyz",
    "methods": ["totp", "sms"]
  }
}
```

---

### Verify Two-Factor

Complete login with 2FA code.

```http
POST /login/verify-2fa
Content-Type: application/json

{
  "twoFactorToken": "2fa_temp_token_xyz",
  "code": "123456",
  "method": "totp"
}
```

**Response (200 OK):** Same as login response.

---

### Refresh Token

Obtain new access token using refresh token.

```http
POST /refresh-token
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIs..."
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
    "expiresIn": 900
  }
}
```

---

### Logout

Invalidate current session.

```http
POST /logout
Authorization: Bearer <access_token>
```

**Response (204 No Content)**

---

### Password Reset Request

Request password reset email.

```http
POST /password/reset-request
Content-Type: application/json

{
  "email": "user@example.com"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "If an account exists, a reset email has been sent."
  }
}
```

---

### Password Reset

Reset password with token from email.

```http
POST /password/reset
Content-Type: application/json

{
  "token": "reset_token_from_email",
  "newPassword": "NewSecureP@ssw0rd!"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "Password successfully reset."
  }
}
```

---

## User Profile

### Get Current User Profile

```http
GET /profile
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "username": "johndoe",
    "displayName": "John Doe",
    "bio": "Streaming enthusiast",
    "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_abc123.jpg",
    "bannerUrl": "https://cdn.aphrodite.example.com/banners/usr_abc123.jpg",
    "verified": true,
    "isCreator": false,
    "stats": {
      "following": 42,
      "followers": 0
    },
    "preferences": {
      "language": "en",
      "timezone": "America/New_York",
      "currency": "USD"
    },
    "createdAt": "2026-01-18T12:00:00.000Z",
    "updatedAt": "2026-01-18T14:30:00.000Z"
  }
}
```

---

### Update User Profile

```http
PUT /profile
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "displayName": "John D.",
  "bio": "Updated bio text",
  "preferences": {
    "language": "es",
    "timezone": "Europe/Madrid"
  }
}
```

**Response (200 OK):** Updated profile object.

---

### Update Avatar

```http
POST /profile/avatar
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

avatar: <binary image data>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_abc123_v2.jpg"
  }
}
```

**Constraints:**

- Max file size: 5MB
- Allowed formats: JPEG, PNG, WebP
- Minimum dimensions: 200x200
- Maximum dimensions: 2000x2000

---

### Get User by Username

```http
GET /users/:username
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "id": "usr_xyz789",
    "username": "janedoe",
    "displayName": "Jane Doe",
    "bio": "Content creator",
    "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_xyz789.jpg",
    "verified": true,
    "isCreator": true,
    "isLive": true,
    "stats": {
      "followers": 15000
    },
    "relationship": {
      "isFollowing": true,
      "isSubscribed": false,
      "subscriptionTier": null
    }
  }
}
```

---

## Creator Profile

### Get Creator Profile

```http
GET /creator
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "id": "crt_abc123",
    "userId": "usr_abc123",
    "displayName": "Jane Doe",
    "bio": "Professional content creator",
    "category": "entertainment",
    "tags": ["gaming", "music"],
    "schedule": {
      "timezone": "America/Los_Angeles",
      "slots": [
        { "day": "monday", "startTime": "20:00", "endTime": "23:00" },
        { "day": "friday", "startTime": "21:00", "endTime": "01:00" }
      ]
    },
    "tipping": {
      "enabled": true,
      "minimumTip": 1,
      "goals": [
        { "id": "goal_1", "name": "New Camera", "target": 500, "current": 234 }
      ]
    },
    "devices": [
      { "id": "dev_1", "type": "lovense", "name": "Lush 3", "connected": true }
    ],
    "socials": {
      "twitter": "@janedoe",
      "instagram": "@janedoe"
    },
    "stats": {
      "followers": 15000,
      "subscribers": 234,
      "totalStreams": 150,
      "totalHours": 450
    },
    "verificationStatus": "verified",
    "payoutEnabled": true
  }
}
```

---

### Update Creator Profile

```http
PUT /creator
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "bio": "Updated creator bio",
  "category": "entertainment",
  "tags": ["gaming", "music", "chat"],
  "schedule": {
    "timezone": "America/Los_Angeles",
    "slots": [
      { "day": "monday", "startTime": "20:00", "endTime": "23:00" }
    ]
  },
  "tipping": {
    "enabled": true,
    "minimumTip": 5
  },
  "socials": {
    "twitter": "@janedoe"
  }
}
```

**Response (200 OK):** Updated creator profile object.

---

### Become a Creator

Apply to become a creator (requires identity verification).

```http
POST /creator/apply
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "legalName": "Jane Marie Doe",
  "dateOfBirth": "1995-03-20",
  "country": "US",
  "idType": "passport",
  "acceptedCreatorTerms": true
}
```

**Response (202 Accepted):**

```json
{
  "success": true,
  "data": {
    "applicationId": "app_xyz123",
    "status": "pending_verification",
    "nextStep": "upload_documents",
    "uploadUrl": "https://api.aphrodite.example.com/creator/verify/upload"
  }
}
```

---

## Settings

### Get User Settings

```http
GET /settings
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "notifications": {
      "email": {
        "marketing": false,
        "newFollower": true,
        "streamReminders": true,
        "tips": true,
        "messages": true
      },
      "push": {
        "newFollower": true,
        "streamReminders": true,
        "tips": true,
        "messages": true
      },
      "inApp": {
        "newFollower": true,
        "streamReminders": true,
        "tips": true,
        "messages": true
      }
    },
    "privacy": {
      "showOnlineStatus": true,
      "allowDirectMessages": "followers",
      "showActivity": true,
      "profileVisibility": "public"
    },
    "security": {
      "twoFactorEnabled": true,
      "twoFactorMethod": "totp",
      "loginNotifications": true,
      "trustedDevices": [
        {
          "id": "dev_1",
          "name": "Chrome on MacOS",
          "lastUsed": "2026-01-18T12:00:00.000Z"
        }
      ]
    },
    "streaming": {
      "autoRecord": true,
      "defaultQuality": "1080p",
      "lowLatencyMode": true
    },
    "payment": {
      "defaultCurrency": "USD",
      "autoRecharge": false,
      "autoRechargeAmount": 50
    }
  }
}
```

---

### Update Settings

```http
PUT /settings
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "notifications": {
    "email": {
      "marketing": true
    }
  },
  "privacy": {
    "showOnlineStatus": false
  }
}
```

**Response (200 OK):** Updated settings object.

---

### Enable Two-Factor Authentication

```http
POST /settings/2fa/enable
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "method": "totp"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCodeUrl": "otpauth://totp/Aphrodite:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Aphrodite",
    "qrCodeImage": "data:image/png;base64,..."
  }
}
```

---

### Confirm Two-Factor Authentication

```http
POST /settings/2fa/confirm
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "code": "123456"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "enabled": true,
    "backupCodes": ["abcd-1234", "efgh-5678", "ijkl-9012"]
  }
}
```

---

## Social Features

### Follow User

```http
POST /follow
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "userId": "usr_xyz789"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "following": true,
    "followedAt": "2026-01-18T12:00:00.000Z"
  }
}
```

---

### Unfollow User

```http
DELETE /follow/:userId
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "following": false
  }
}
```

---

### Get Following List

```http
GET /following?cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": [
    {
      "user": {
        "id": "usr_xyz789",
        "username": "janedoe",
        "displayName": "Jane Doe",
        "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_xyz789.jpg",
        "isLive": true
      },
      "followedAt": "2026-01-18T12:00:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "next_cursor",
    "hasMore": true,
    "total": 42
  }
}
```

---

### Get Followers List

```http
GET /followers?cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
```

**Response (200 OK):** Same structure as following list.

---

## Fan Clubs

### Get Creator's Fan Club

```http
GET /fan-club/:creatorId
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "id": "fc_abc123",
    "creatorId": "usr_xyz789",
    "name": "Jane's VIP Club",
    "description": "Exclusive content and perks for subscribers",
    "tiers": [
      {
        "id": "tier_1",
        "name": "Bronze",
        "price": 9.99,
        "currency": "USD",
        "billingPeriod": "monthly",
        "benefits": ["Ad-free viewing", "Custom badge", "Exclusive emotes"]
      },
      {
        "id": "tier_2",
        "name": "Gold",
        "price": 24.99,
        "currency": "USD",
        "billingPeriod": "monthly",
        "benefits": [
          "All Bronze benefits",
          "Priority chat",
          "Monthly exclusive content",
          "Discord access"
        ]
      }
    ],
    "memberCount": 234,
    "userSubscription": null
  }
}
```

---

### Subscribe to Fan Club

```http
POST /fan-club/:creatorId/subscribe
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "tierId": "tier_1",
  "paymentMethodId": "pm_abc123"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "subscriptionId": "sub_xyz789",
    "tierId": "tier_1",
    "tierName": "Bronze",
    "status": "active",
    "currentPeriodStart": "2026-01-18T00:00:00.000Z",
    "currentPeriodEnd": "2026-02-18T00:00:00.000Z",
    "cancelAtPeriodEnd": false
  }
}
```

---

### Manage Fan Club (Creator)

```http
POST /fan-club
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "Jane's VIP Club",
  "description": "Exclusive content and perks",
  "tiers": [
    {
      "name": "Bronze",
      "price": 9.99,
      "currency": "USD",
      "billingPeriod": "monthly",
      "benefits": ["Ad-free viewing", "Custom badge"]
    }
  ]
}
```

**Response (201 Created):** Created fan club object.

---

## Subscriptions

### Get User Subscriptions

```http
GET /subscriptions
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": [
    {
      "id": "sub_xyz789",
      "creator": {
        "id": "usr_xyz789",
        "username": "janedoe",
        "displayName": "Jane Doe",
        "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_xyz789.jpg"
      },
      "tier": {
        "id": "tier_1",
        "name": "Bronze",
        "price": 9.99
      },
      "status": "active",
      "currentPeriodEnd": "2026-02-18T00:00:00.000Z",
      "cancelAtPeriodEnd": false
    }
  ]
}
```

---

### Cancel Subscription

```http
POST /subscriptions/:subscriptionId/cancel
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "cancelImmediately": false,
  "reason": "Too expensive"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "subscriptionId": "sub_xyz789",
    "status": "active",
    "cancelAtPeriodEnd": true,
    "currentPeriodEnd": "2026-02-18T00:00:00.000Z"
  }
}
```

---

## Data Types

### User Object

```typescript
interface User {
  id: string;
  email: string;
  username: string;
  displayName: string;
  bio?: string;
  avatarUrl?: string;
  bannerUrl?: string;
  verified: boolean;
  isCreator: boolean;
  createdAt: string;
  updatedAt: string;
}
```

### Creator Object

```typescript
interface Creator {
  id: string;
  userId: string;
  displayName: string;
  bio?: string;
  category: string;
  tags: string[];
  schedule?: Schedule;
  tipping: TippingConfig;
  devices: Device[];
  socials: Record<string, string>;
  stats: CreatorStats;
  verificationStatus: 'pending' | 'verified' | 'rejected';
  payoutEnabled: boolean;
}
```

### Subscription Object

```typescript
interface Subscription {
  id: string;
  creatorId: string;
  userId: string;
  tierId: string;
  status: 'active' | 'canceled' | 'past_due' | 'paused';
  currentPeriodStart: string;
  currentPeriodEnd: string;
  cancelAtPeriodEnd: boolean;
  createdAt: string;
}
```

---

## Document History

| Date       | Version | Changes                       |
| ---------- | ------- | ----------------------------- |
| 2026-01-18 | 1.0.0   | Initial User Service API docs |
