# ガチャ API リファレンス

TaskWorks API のガチャ関連エンドポイントの詳細ドキュメントです。すべてのエンドポイントはユーザー固有のデータのみを返します（RLS保護）。

## 認証方式

### 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 エンドポイント

### ガチャ（Gacha）

#### POST /api/v1/gacha/draw

ガチャを引きます（単独・10連）。

**認証:** ApiKey / Bearer / Cookie

**リクエストボディ:**
```json
{
  "gacha": {
    "id": "string (required)",
    "name": "string (required)",
    "cost": {
      "single": number (required, non-negative),
      "ten": number (required, non-negative)
    }
  },
  "drawType": "single" | "ten"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "result": {
      "id": "string",
      "gachaId": "string",
      "gachaName": "string",
      "drawType": "single" | "ten",
      "cards": [
        {
          "image": "string",
          "rarity": "normal" | "rare" | "ultra" | null,
          "clip": "stage" | "supporter" | "trainer" | null
        }
      ],
      "featuredIndex": number,
      "cost": number,
      "recordedAt": "string"
    },
    "catCanBalance": number,
    "catCanDelta": number,
    "ledgerId": "string"
  },
  "error": null
}
```

---

#### GET /api/v1/gacha/draw

最新のガチャ結果と残高を取得します。

**認証:** ApiKey / Bearer / Cookie

**レスポンス スキーマ:**
```json
{
  "data": {
    "result": Object | null,
    "catCanBalance": number
  },
  "error": null
}
```

---

#### GET /api/v1/gacha/inventory

所有アイテム一覧を取得します。

**認証:** ApiKey / Bearer / Cookie

**クエリパラメータ:**
- limit: number（オプション）

**レスポンス スキーマ:**
```json
{
  "data": {
    "cards": [
      {
        "image": "string",
        "rarity": "normal" | "rare" | "ultra" | null,
        "clip": "stage" | "supporter" | "trainer" | null,
        "count": number,
        "latestRecordedAt": "string",
        "latestGachaName": "string",
        "accentFrom": "string | null"
      }
    ],
    "totalUnique": number,
    "totalCount": number
  },
  "error": null
}
```

---

#### GET /api/v1/gacha/history

ガチャ履歴を取得します（ページネーション）。

**認証:** ApiKey / Bearer / Cookie

**クエリパラメータ:**
- limit: number（オプション）
- cursor: string（オプション）

**レスポンス スキーマ:**
```json
{
  "data": {
    "items": [
      {
        "id": "string",
        "gachaId": "string",
        "gachaName": "string",
        "drawType": "single" | "ten",
        "cards": Array<Object>,
        "featuredIndex": number,
        "cost": number,
        "recordedAt": "string"
      }
    ],
    "nextCursor": "string | null",
    "hasMore": boolean
  },
  "error": null
}
```