social-app/docs/protocols/inbox-messages.md

# Inbox Messages Protocol

> **NOTE**: This document is the single source of truth. All implementations must follow this specification.

## Overview

Inbox messages are notifications sent to users for various events like friend requests and calendar invites.

## Version

- **Current**: `1.0`
- **Status**: Active

---

## Message Types

```typescript
type InboxMessageType = 'friend_request' | 'calendar' | 'system' | 'group';
```

```typescript
type InboxMessageStatus = 'pending' | 'accepted' | 'rejected' | 'dismissed';
```

---

## Content Schema

### Calendar Invite Content

```typescript
interface CalendarInviteContent {
  type: 'invite';
  permission: number;  // 1=view, 4=edit, 8=invite
  action: 'pending';
}
```

### Calendar Update Content

```typescript
interface CalendarUpdateContent {
  type: 'update';
  title: string;
  action: 'updated';
}
```

### Calendar Delete Content

```typescript
interface CalendarDeleteContent {
  type: 'delete';
  title: string;
  action: 'deleted';
}
```

### Friendship Request Content

```typescript
interface FriendshipContent {
  type: 'request';
  message?: string;  // Optional friend request message
}
```

---

## Union Type

```typescript
type InboxMessageContent = 
  | CalendarInviteContent 
  | CalendarUpdateContent 
  | CalendarDeleteContent 
  | FriendshipContent;
```

---

## Database Field

| Field | Type | Description |
|-------|------|-------------|
| content | jsonb | Structured content based on message_type |

---

## JSON Examples

### Friend Request

```json
{
  "type": "request",
  "message": "Hi, let's be friends!"
}
```

### Calendar Invite

```json
{
  "type": "invite",
  "permission": 4,
  "action": "pending"
}
```

### Calendar Update

```json
{
  "type": "update",
  "title": "Team Meeting",
  "action": "updated"
}
```

### Calendar Delete

```json
{
  "type": "delete",
  "title": "Team Meeting",
  "action": "deleted"
}
```