# Partners

This document describes the partner sharing functionality.

## Partner Overview

Partners allow two-way photo sharing between users:
- Share your library with another user
- View photos from users who share with you
- Optionally include partner photos in your timeline

## Partner Types

### Shared With (Inbound)
Users who share their photos with you.
- You can view their photos
- Cannot modify their photos
- Can include in your timeline

### Shared By (Outbound)
Users you share your photos with.
- They can view your photos
- Cannot modify your photos
- You control the sharing

## Partner API

### Get Partners Sharing With You
```
GET /partners?direction=shared-with

Response:
[
  {
    "id": "user-uuid",
    "email": "partner@example.com",
    "name": "Jane Doe",
    "profileImagePath": "/path/to/image",
    "inTimeline": true
  }
]
```

### Get Partners You Share With
```
GET /partners?direction=shared-by

Response:
[
  {
    "id": "user-uuid",
    "email": "friend@example.com",
    "name": "John Smith",
    "profileImagePath": "/path/to/image",
    "inTimeline": false
  }
]
```

### Add Partner (Share Your Library)
```
POST /partners/{userId}

Response: Partner user object
```

### Remove Partner
```
DELETE /partners/{userId}
```

### Update Partner Settings
```
PUT /partners/{userId}

Body:
{
  "inTimeline": true
}
```

## Partner Screen

### Layout
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Partners                                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Sharing with you                                           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 👤 Jane Doe                                          │   │
│  │    partner@example.com                               │   │
│  │    Include in timeline: [Toggle: ON]            [>]  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 👤 Bob Wilson                                        │   │
│  │    bob@example.com                                   │   │
│  │    Include in timeline: [Toggle: OFF]           [>]  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  You're sharing with                                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 👤 John Smith                                        │   │
│  │    friend@example.com                       [Remove] │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  [+ Add Partner]                                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## Adding a Partner

### User Selection Screen
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Select Partner                                          │
├─────────────────────────────────────────────────────────────┤
│  [Search users...]                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Available Users                                            │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 👤 Alice Johnson                                     │   │
│  │    alice@example.com                                 │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 👤 Charlie Brown                                     │   │
│  │    charlie@example.com                               │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Available Users API
```
GET /users

Returns users on the same server who can be added as partners
```

## Partner Detail View

View a partner's photos:

```
┌─────────────────────────────────────────────────────────────┐
│  ←  Jane Doe's Photos                                       │
├─────────────────────────────────────────────────────────────┤
│  December 2024                                              │
│  ┌─────┬─────┬─────┬─────┐                                 │
│  │     │     │     │     │                                 │
│  │ 📷  │ 📷  │ 🎥  │ 📷  │                                 │
│  │     │     │     │     │                                 │
│  ├─────┼─────┼─────┼─────┤                                 │
│  │     │     │     │     │                                 │
│  │ 📷  │ 📷  │ 📷  │ 🎥  │                                 │
│  │     │     │     │     │                                 │
│  └─────┴─────┴─────┴─────┘                                 │
│  ...                                                        │
└─────────────────────────────────────────────────────────────┘
```

### Getting Partner's Assets
Partner assets are fetched during normal sync and filtered by user ID.

## Timeline Integration

### Include in Timeline
When `inTimeline: true`:
- Partner's photos appear in your main timeline
- Mixed chronologically with your photos
- Small avatar indicator shows owner

### Multi-User Timeline
```
Timeline Provider:
  - If single user: Show only your assets
  - If multiple users (partners with inTimeline):
    - Fetch assets for all users
    - Merge and sort chronologically
    - Add user indicator to each asset
```

### Asset Owner Indicator
```
┌─────┐
│ 📷  │
│  👤 │  ← Small avatar showing partner
└─────┘
```

## Partner Sync

### How Partner Assets Sync
1. Fetch partner list on login
2. For each partner with `inTimeline: true`:
   - Fetch their assets via sync API
   - Store in local database with owner ID
3. Timeline queries include partner assets

### Sync Endpoint
```
GET /sync/full-sync?userId={partnerId}

Or included in normal sync with partner IDs
```

## Privacy Considerations

### What Partners Can See
- Your uploaded photos and videos
- Metadata (location, date, etc.)
- Albums you've shared

### What Partners Cannot Do
- Delete your photos
- Edit your photos
- See your favorites/archive
- Access your locked folder

## Removing a Partner

### Stop Sharing Your Library
1. Go to Partners screen
2. Find user in "You're sharing with"
3. Tap Remove
4. Confirm removal

### Behavior After Removal
- Partner can no longer see your photos
- Their local cache may still have thumbnails
- No data is deleted from your server

## Partner vs Album Sharing

| Feature | Partner Sharing | Album Sharing |
|---------|-----------------|---------------|
| Scope | Entire library | Specific album |
| New photos | Automatically included | Must add manually |
| Timeline integration | Optional | No |
| Bidirectional | Yes (if both share) | No |
| Granular control | No | Yes (roles) |

---

[Previous: Sharing](./sharing.md) | [Next: Activities](./activities.md)