# コミュニティ API リファレンス

TaskWorks API のコミュニティ関連エンドポイントの詳細ドキュメントです。

## 認証方式

### ApiKey 認証（推奨）
```
Authorization: ApiKey <token>
```
- 設定 > APIキー管理 から生成
- トークンは一度しか表示されないため安全に保管
- ほとんどのエンドポイントで使用可能

### Bearer トークン認証
```
Authorization: Bearer <token>
```
- サービス間通信で使用
- 一部のエンドポイントで必須（例: /api/v1/blocks/windows）

### Cookie 認証
- 標準のセッションベース認証
- Webクライアントで使用
- Cookie専用エンドポイントで必須

## 共通レスポンス形式

すべての成功レスポンスは以下の構造に従います：
```json
{
  "data": <response_data>,
  "error": null
}
```

すべてのエラーレスポンスは以下の構造に従います：
```json
{
  "error": "<error_type>",
  "message": "<human_readable_message>",
  "code": "<optional_error_code>",
  "context": <optional_additional_context>
}
```

## HTTP ステータスコード

- 200: 成功
- 201: 作成完了
- 400: 不正なリクエスト（検証エラー）
- 401: 未認証（認証が必要）
- 403: 禁止（権限なし）
- 404: 未検出
- 409: 衝突（リソースの競合）
- 500: サーバー内部エラー

## ページネーション

一部のエンドポイントはカーソルベースのページネーションをサポート：
- cursor: 次ページの開始位置
- limit: 返す項目数（1-100、デフォルトはエンドポイントにより異なる）

レスポンス形式：
```json
{
  "data": {
    "items": [...],
    "nextCursor": "string | null",
    "hasMore": boolean
  },
  "error": null
}
```

## API エンドポイント

### コミュニティ（Communities）

#### GET /api/v1/communities

全コミュニティ一覧を取得します（公開）。

**認証:** なし（公開）

**レスポンス スキーマ:**
```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "icon_url": "string | null",
      "background_url": "string | null",
      "url": "string | null",
      "member_count": number | null,
      "help_count": number | null,
      "registration_status": "string | null",
      "language": "string | null",
      "category": "string | null",
      "created_at": "string | null",
      "updated_at": "string | null"
    }
  ],
  "error": null
}
```

---

#### GET /api/v1/communities?communityId=:id

特定のコミュニティ詳細と投稿を取得します（公開）。

**認証:** なし（公開）

**クエリパラメータ:**
- communityId: string（必須）- コミュニティID

**レスポンス スキーマ:**
```json
{
  "data": {
    "community": Object,
    "posts": Array<CommunityPost>
  },
  "error": null
}
```

---

#### POST /api/v1/communities

新しいコミュニティを作成します。

**認証:** Cookie のみ

**リクエストボディ:**
```json
{
  "name": "string (required)",
  "description": "string",
  "icon_url": "string | null",
  "background_url": "string | null",
  "category": "string | null",
  "language": "string | null"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "createdAt": "string"
  },
  "error": null
}
```

---

#### DELETE /api/v1/communities/:id

コミュニティを削除します。

**認証:** Cookie + 管理者権限

**パスパラメータ:**
- id: string（必須）- コミュニティID

**レスポンス スキーマ:**
```json
{
  "data": {
    "success": true
  },
  "error": null
}
```

**エラーケース:**
- 403: 禁止（管理者権限が必要）

---

#### GET /api/v1/communities/me/avatar

ユーザーのコミュニティプロフィールを取得します。

**認証:** Cookie のみ

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "userId": "string",
    "name": "string",
    "handle": "string",
    "avatarUrl": "string | null",
    "bio": "string | null"
  },
  "error": null
}
```

---

#### PUT /api/v1/communities/me/avatar

ユーザーのコミュニティプロフィールを更新します。

**認証:** Cookie のみ

**リクエストボディ:**
```json
{
  "name": "string",
  "handle": "string",
  "avatarUrl": "string | null",
  "bio": "string | null"
}
```

**レスポンス スキーマ:** GET /api/v1/communities/me/avatar と同じ

---

#### POST /api/v1/communities/:id/join

コミュニティに参加します。

**認証:** Cookie のみ

**パスパラメータ:**
- id: string（必須）- コミュニティID

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "communityId": "string",
    "userId": "string",
    "joinedAt": "string"
  },
  "error": null
}
```

---

#### DELETE /api/v1/communities/:id/join

コミュニティを脱退します。

**認証:** Cookie のみ

**パスパラメータ:**
- id: string（必須）- コミュニティID

**レスポンス スキーマ:**
```json
{
  "data": {
    "success": true
  },
  "error": null
}
```

---

#### POST /api/v1/communities/:id/follow

コミュニティ内のユーザーをフォローします。

**認証:** Cookie のみ

**パスパラメータ:**
- id: string（必須）- コミュニティID

**リクエストボディ:**
```json
{
  "followingId": "string (required)"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "communityId": "string",
    "followerId": "string",
    "followingId": "string",
    "createdAt": "string"
  },
  "error": null
}
```

---

#### DELETE /api/v1/communities/:id/follow

コミュニティ内のユーザーのフォローを解除します。

**認証:** Cookie のみ

**パスパラメータ:**
- id: string（必須）- コミュニティID

**リクエストボディ:**
```json
{
  "followingId": "string (required)"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "success": true
  },
  "error": null
}
```

---

#### POST /api/v1/communities/:id/posts

新しい投稿を作成します。

**認証:** Cookie のみ

**パスパラメータ:**
- id: string（必須）- コミュニティID

**リクエストボディ:**
```json
{
  "content": "string (required)",
  "replyTo": "string | null",
  "images": Array<Object> | null
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "post": {
      "id": "string",
      "author": {
        "id": "string",
        "name": "string",
        "handle": "string",
        "avatarUrl": "string | null"
      },
      "content": "string",
      "createdAt": "string",
      "updatedAt": "string | null",
      "likesCount": number,
      "repliesCount": number,
      "repostsCount": number,
      "isLiked": boolean,
      "isReposted": boolean,
      "communityId": "string",
      "images": Array<Object> | null,
      "replyTo": "string | null"
    }
  },
  "error": null
}
```

---

#### GET /api/v1/communities/:id/posts/:postId

特定の投稿と返信を取得します（公開）。

**認証:** なし（公開）

**パスパラメータ:**
- id: string（必須）- コミュニティID
- postId: string（必須）- 投稿ID

**レスポンス スキーマ:**
```json
{
  "data": {
    "post": CommunityPost,
    "replies": Array<CommunityPost>
  },
  "error": null
}
```

---

#### DELETE /api/v1/communities/:id/posts/:postId

投稿を削除します。

**認証:** Cookie + 所有者/管理者権限

**パスパラメータ:**
- id: string（必須）- コミュニティID
- postId: string（必須）- 投稿ID

**レスポンス スキーマ:**
```json
{
  "data": {
    "success": true
  },
  "error": null
}
```

**エラーケース:**
- 403: 禁止（投稿の所有者または管理者である必要があります）

---

#### POST /api/v1/communities/:id/posts/:postId/reactions

いいね/リポストリアクションを追加します。

**認証:** Cookie のみ

**パスパラメータ:**
- id: string（必須）- コミュニティID
- postId: string（必須）- 投稿ID

**リクエストボディ:**
```json
{
  "reactionType": "like" | "repost (required)"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "postId": "string",
    "userId": "string",
    "reactionType": "like" | "repost",
    "createdAt": "string"
  },
  "error": null
}
```

---

#### DELETE /api/v1/communities/:id/posts/:postId/reactions

いいね/リポストリアクションを削除します。

**認証:** Cookie のみ

**パスパラメータ:**
- id: string（必須）- コミュニティID
- postId: string（必須）- 投稿ID

**リクエストボディ:**
```json
{
  "reactionType": "like" | "repost (required)"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "success": true
  },
  "error": null
}
```

---

#### GET /api/v1/communities/:id/reports

コミュニティ通報一覧を取得します（管理者限定）。

**認証:** Cookie + 管理者権限

**パスパラメータ:**
- id: string（必須）- コミュニティID

**レスポンス スキーマ:**
```json
{
  "data": [
    {
      "id": "string",
      "communityId": "string",
      "postId": "string",
      "reportedBy": "string",
      "reason": "string",
      "status": "pending" | "resolved" | "dismissed",
      "createdAt": "string",
      "updatedAt": "string | null"
    }
  ],
  "error": null
}
```

---

#### POST /api/v1/communities/:id/reports

投稿を通報します。

**認証:** Cookie のみ

**パスパラメータ:**
- id: string（必須）- コミュニティID

**リクエストボディ:**
```json
{
  "postId": "string (required)",
  "reason": "string (required)"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "communityId": "string",
    "postId": "string",
    "reportedBy": "string",
    "reason": "string",
    "status": "pending",
    "createdAt": "string"
  },
  "error": null
}
```

---

#### PATCH /api/v1/communities/:id/reports/:reportId

通報ステータスを更新します（管理者限定）。

**認証:** Cookie + 管理者権限

**パスパラメータ:**
- id: string（必須）- コミュニティID
- reportId: string（必須）- 通報ID

**リクエストボディ:**
```json
{
  "status": "resolved" | "dismissed (required)"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "id": "string",
    "status": "resolved" | "dismissed",
    "updatedAt": "string"
  },
  "error": null
}
```