### Start Microsoft OAuth Flow

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Initiates the Microsoft OAuth 2.0 authentication process for linking Minecraft accounts. This GET request redirects the user to Microsoft's login page and sets a state cookie for security.

```bash
# Start Microsoft OAuth flow
curl -X GET "https://your-domain.com/api/auth/microsoft/start?returnTo=/dashboard" \
  -H "Accept: application/json" \
  -c cookies.txt
```

```http
# Response: 302 Redirect to Microsoft login
# Set-Cookie: aetweaks_oauth=<signed_oauth_state>
```

```http
# After Microsoft callback, user is redirected to /dashboard with session cookies
# Set-Cookie: aetweaks_session=<signed_session_token>
# Set-Cookie: aetweaks_csrf=<csrf_token>
```

--------------------------------

### Authentication Responses

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Example JSON responses for successful authentication and unauthorized access attempts.

```json
{
  "authenticated": true,
  "user": {
    "userId": "user-uuid",
    "username": "PlayerName",
    "avatarUrl": "https://minotar.net/avatar/PlayerName/32",
    "provider": "microsoft",
    "role": "user",
    "isAdmin": false
  }
}
```

```json
{ "authenticated": false }
```

--------------------------------

### GET /api/admin/sources

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Retrieves a list of pending server sources for administrative review. Requires admin or management role.

```APIDOC
## GET /api/admin/sources

### Description
Retrieves a list of pending server sources for administrative review. Requires admin or management role.

### Method
GET

### Endpoint
/api/admin/sources

### Response
#### Success Response (200)
- **sources** (array) - List of pending server sources
- **minimumBlocks** (number) - Minimum block threshold

#### Response Example
{
  "sources": [
    {
      "id": "source-uuid",
      "displayName": "New Server",
      "worldKey": "play.newserver.net",
      "kind": "multiplayer",
      "sourceScope": "public_server",
      "totalBlocks": 50000,
      "playerCount": 25,
      "submittedByUsername": "Submitter",
      "submittedAt": "2024-04-07T10:00:00Z",
      "approvalStatus": "pending"
    }
  ],
  "minimumBlocks": 0
}
```

--------------------------------

### GET /api/me

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Returns the currently authenticated user's profile information including admin status and provider details.

```APIDOC
## GET /api/me

### Description
Returns the currently authenticated user's profile information including admin status and provider details.

### Method
GET

### Endpoint
`/api/me`

### Parameters
#### Headers
- **Cookie** (string) - Required - Session token for authentication. Example: `aetweaks_session=<session_token>`

### Request Example
```bash
# Get current user
curl -X GET "https://your-domain.com/api/me" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"
```

### Response
#### Success Response (200)
- **id** (string) - User's unique identifier.
- **email** (string) - User's email address.
- **username** (string) - User's username.
- **is_admin** (boolean) - Indicates if the user has administrator privileges.
- **provider** (string) - The authentication provider used (e.g., 'microsoft').
- **created_at** (string) - Timestamp when the user account was created (ISO 8601 format).
- **updated_at** (string) - Timestamp when the user account was last updated (ISO 8601 format).

#### Response Example
```json
{
  "id": "user-uuid-123",
  "email": "user@example.com",
  "username": "PlayerName",
  "is_admin": false,
  "provider": "microsoft",
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-04-08T12:00:00Z"
}
```
```

--------------------------------

### Example JSON Payload for AeTweaks Sync API

Source: https://github.com/darealshekel/aewt-sync-pro/blob/main/SYNC_API.md

This JSON payload structure is used when sending data to the AeTweaks Sync API. It includes details about the client, Minecraft session, world information, project progress, and synced statistics.

```json
{
  "client_id": "aet_3bb3e98b-2552-4f26-9d96-a54d9f5697b3",
  "minecraft_uuid": "00000000-0000-0000-0000-000000000001",
  "username": "Shekel",
  "mod_version": "1.0.0",
  "minecraft_version": "1.21.4",
  "world": {
    "key": "play.aeternum.net",
    "display_name": "play.aeternum.net",
    "kind": "multiplayer",
    "host": "play.aeternum.net"
  },
  "session": {
    "session_key": "sess_1712583195000",
    "started_at": "2026-04-08T12:00:00Z",
    "ended_at": "2026-04-08T13:03:00Z",
    "active_seconds": 3780,
    "total_blocks": 2340,
    "average_bph": 2228,
    "peak_bph": 6800,
    "best_streak_seconds": 840,
    "top_block": "minecraft:stone",
    "status": "ended",
    "block_breakdown": [
      { "block_id": "minecraft:stone", "count": 1880 },
      { "block_id": "minecraft:diorite", "count": 220 }
    ],
    "rate_points": []
  },
  "projects": [
    {
      "project_key": "main-project",
      "name": "Main Project",
      "progress": 4820,
      "goal": 7200,
      "is_active": true
    }
  ],
  "daily_goal": {
    "goal_date": "2026-04-08",
    "target": 1000,
    "progress": 830,
    "completed": false
  },
  "synced_stats": {
    "blocks_per_hour": 2228,
    "estimated_finish_seconds": 4980,
    "current_project_name": "Main Project",
    "current_project_progress": 4820,
    "current_project_goal": 7200,
    "daily_progress": 830,
    "daily_target": 1000
  }
}
```

--------------------------------

### Get Current User Profile

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Retrieves the profile information for the currently authenticated user. This endpoint requires the user's session token in the 'Cookie' header.

```bash
# Get current user
curl -X GET "https://your-domain.com/api/me" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"
```

--------------------------------

### GET /api/dashboard

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Retrieves a complete snapshot of a user's AeTweaks data, including player statistics, active projects, session history, daily goals, world data, and leaderboard standing. Requires a valid session cookie.

```APIDOC
## GET /api/dashboard

### Description
Returns the complete snapshot of a user's AeTweaks data including player stats, projects, sessions, daily goals, worlds, and leaderboard position.

### Method
GET

### Endpoint
/api/dashboard

### Response
#### Success Response (200)
- **meta** (object) - Metadata about the request source and status.
- **viewer** (object) - Information about the authenticated user.
- **player** (object) - Detailed Minecraft player statistics.
- **projects** (array) - List of active mining projects.
- **sessions** (array) - List of recent mining sessions.
- **dailyGoal** (object) - Current progress towards daily mining goals.
- **worlds** (array) - Statistics per Minecraft world.
- **leaderboard** (object) - Current leaderboard position.
- **settings** (object) - User configuration settings.

#### Response Example
{
  "meta": {
    "source": "live",
    "title": "Account linked and secured",
    "description": "Showing only PlayerName's AeTweaks data from the linked Minecraft account."
  },
  "viewer": {
    "userId": "user-uuid",
    "username": "PlayerName"
  },
  "player": {
    "id": "player-uuid",
    "username": "PlayerName",
    "totalSyncedBlocks": 125000
  }
}
```

--------------------------------

### GET /api/leaderboard

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Retrieves the public leaderboard with paginated player rankings. Supports filtering by view type, search queries, and minimum block thresholds.

```APIDOC
## GET /api/leaderboard

### Description
Returns the public leaderboard with paginated player rankings, filterable by view, search query, and minimum blocks.

### Method
GET

### Endpoint
/api/leaderboard

### Parameters
#### Query Parameters
- **view** (string) - Optional - The leaderboard view type (e.g., global).
- **page** (integer) - Optional - The page number for pagination.
- **pageSize** (integer) - Optional - Number of items per page.
- **query** (string) - Optional - Search string for player names.
- **minBlocks** (integer) - Optional - Filter by minimum total blocks mined.

### Request Example
curl -X GET "https://your-domain.com/api/leaderboard?view=global&page=1&pageSize=50&query=&minBlocks=0"
```

--------------------------------

### Profile Settings API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Manages user profile preferences including privacy settings, leaderboard opt-in, and HUD configuration. Supports GET for reading and PATCH for updating settings with CSRF protection.

```APIDOC
## GET /api/profile

### Description
Retrieves the current profile settings for the authenticated user.

### Method
GET

### Endpoint
/api/profile

### Request Example
```bash
curl -X GET "https://your-domain.com/api/profile" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"
```

### Response
#### Success Response (200 OK)
- **user** (object) - User profile information.
  - **userId** (string) - The unique identifier for the user.
  - **username** (string) - The username of the player.
  - **avatarUrl** (string) - The URL to the user's avatar.
  - **provider** (string) - The authentication provider.

#### Response Example
```json
{
  "user": {
    "userId": "user-uuid",
    "username": "PlayerName",
    "avatarUrl": "https://minotar.net/avatar/PlayerName/32",
    "provider": "microsoft"
  }
}
```
```

```APIDOC
## PATCH /api/profile

### Description
Updates the profile settings for the authenticated user.

### Method
PATCH

### Endpoint
/api/profile

### Parameters
#### Request Body
- **publicProfile** (boolean) - Optional - Whether the user's profile should be public.
- **leaderboardOptIn** (boolean) - Optional - Whether the user opts into the leaderboard.
- **sessionSharing** (boolean) - Optional - Whether session data can be shared.
- **hudEnabled** (boolean) - Optional - Whether the Heads-Up Display is enabled.
- **hudAlignment** (string) - Optional - The alignment of the HUD (e.g., "top-left").
- **hudScale** (number) - Optional - The scale of the HUD.

### Request Example
```bash
curl -X PATCH "https://your-domain.com/api/profile" \
  -H "Content-Type: application/json" \
  -H "Cookie: aetweaks_session=<session_token>" \
  -H "X-CSRF-Token: <csrf_token>" \
  -d '{
    "publicProfile": false,
    "leaderboardOptIn": true,
    "sessionSharing": false,
    "hudEnabled": true,
    "hudAlignment": "top-left",
    "hudScale": 1.0
  }'
```

### Response
#### Success Response (200 OK)
- **ok** (boolean) - Indicates if the update was successful.

#### Response Example
```json
{ "ok": true }
```
```

--------------------------------

### Configure Environment Variables

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Required environment variables for Supabase, Microsoft OAuth, and security keys.

```bash
# .env file configuration

# Supabase Configuration (required for data storage)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Microsoft OAuth (required for authentication)
MICROSOFT_CLIENT_ID=your-azure-app-client-id
MICROSOFT_CLIENT_SECRET=your-azure-app-client-secret
MICROSOFT_TENANT_ID=consumers

# Security Keys (required for session and encryption)
SESSION_SIGNING_SECRET=random-32-byte-base64-string
AE_HASH_SECRET=random-32-byte-base64-string
AE_IP_HASH_SECRET=random-32-byte-base64-string
AE_ENCRYPTION_KEYS_JSON={"key1":"base64-encoded-256-bit-key"}
AE_PRIMARY_ENCRYPTION_KEY_ID=key1

# Application URL (required for OAuth callbacks)
APP_BASE_URL=https://your-domain.com

# Optional: Demo mode default player
VITE_DEFAULT_PLAYER_USERNAME=DemoPlayer
```

--------------------------------

### POST /functions/v1/aetweaks-sync

Source: https://github.com/darealshekel/aewt-sync-pro/blob/main/SYNC_API.md

Synchronizes mod session data, project progress, and daily goals to the server.

```APIDOC
## POST /functions/v1/aetweaks-sync

### Description
Sends mod session data, project progress, and daily goal statistics to the server. The server processes this data with privacy measures such as hashing client IDs and encrypting Minecraft UUIDs.

### Method
POST

### Endpoint
https://<your-project-ref>.supabase.co/functions/v1/aetweaks-sync

### Parameters
#### Request Headers
- **x-sync-secret** (string) - Optional - Shared secret required if AE_SYNC_SHARED_SECRET is configured on the edge function.

#### Request Body
- **client_id** (string) - Required - Unique client identifier (hashed server-side).
- **minecraft_uuid** (string) - Required - Minecraft user UUID (encrypted server-side).
- **username** (string) - Required - Minecraft username.
- **mod_version** (string) - Required - Version of the AeTweaks mod.
- **minecraft_version** (string) - Required - Version of Minecraft.
- **world** (object) - Required - World metadata (host is discarded).
- **session** (object) - Required - Detailed session statistics.
- **projects** (array) - Required - List of active projects and progress.
- **daily_goal** (object) - Required - Daily goal tracking data.
- **synced_stats** (object) - Required - Summary of synced statistics.

### Request Example
{
  "client_id": "aet_3bb3e98b-2552-4f26-9d96-a54d9f5697b3",
  "minecraft_uuid": "00000000-0000-0000-0000-000000000001",
  "username": "Shekel",
  "mod_version": "1.0.0",
  "minecraft_version": "1.21.4",
  "world": {
    "key": "play.aeternum.net",
    "display_name": "play.aeternum.net",
    "kind": "multiplayer",
    "host": "play.aeternum.net"
  },
  "session": {
    "session_key": "sess_1712583195000",
    "started_at": "2026-04-08T12:00:00Z",
    "ended_at": "2026-04-08T13:03:00Z",
    "active_seconds": 3780,
    "total_blocks": 2340,
    "average_bph": 2228,
    "peak_bph": 6800,
    "best_streak_seconds": 840,
    "top_block": "minecraft:stone",
    "status": "ended",
    "block_breakdown": [
      { "block_id": "minecraft:stone", "count": 1880 },
      { "block_id": "minecraft:diorite", "count": 220 }
    ],
    "rate_points": []
  },
  "projects": [
    {
      "project_key": "main-project",
      "name": "Main Project",
      "progress": 4820,
      "goal": 7200,
      "is_active": true
    }
  ],
  "daily_goal": {
    "goal_date": "2026-04-08",
    "target": 1000,
    "progress": 830,
    "completed": false
  },
  "synced_stats": {
    "blocks_per_hour": 2228,
    "estimated_finish_seconds": 4980,
    "current_project_name": "Main Project",
    "current_project_progress": 4820,
    "current_project_goal": 7200,
    "daily_progress": 830,
    "daily_target": 1000
  }
}
```

--------------------------------

### Manage Server Source Approvals via Admin API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Administrative endpoints for retrieving pending sources and approving or rejecting them. Requires admin or management role authentication via session cookies.

```bash
# Get pending sources (admin only)
curl -X GET "https://your-domain.com/api/admin/sources" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<admin_session_token>"

# Response (200 OK)
{
  "sources": [
    {
      "id": "source-uuid",
      "displayName": "New Server",
      "worldKey": "play.newserver.net",
      "kind": "multiplayer",
      "sourceScope": "public_server",
      "totalBlocks": 50000,
      "playerCount": 25,
      "submittedByUsername": "Submitter",
      "submittedAt": "2024-04-07T10:00:00Z",
      "firstSeenAt": "2024-04-05T08:00:00Z",
      "lastSeenAt": "2024-04-08T14:30:00Z",
      "approvalStatus": "pending",
      "eligibleForPublic": false,
      "scanEvidence": {
        "scoreboardTitle": "Mining Stats",
        "sampleSidebarLines": ["Digs: 1,234", "Total: 50,000"],
        "detectedStatFields": ["player_digs", "total_digs"],
        "confidence": 95,
        "iconUrl": null,
        "rawScanEvidence": null
      }
    }
  ],
  "minimumBlocks": 0
}

# Approve or reject source (admin only)
curl -X POST "https://your-domain.com/api/admin/sources" \
  -H "Content-Type: application/json" \
  -H "Cookie: aetweaks_session=<admin_session_token>" \
  -H "X-CSRF-Token: <csrf_token>" \
  -d '{
    "sourceId": "source-uuid",
    "action": "approved"
  }'

# Response (200 OK)
{ "ok": true, "sources": [...], "minimumBlocks": 0 }
```

--------------------------------

### Retrieve User Dashboard Snapshot

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Fetches a complete snapshot of user data including stats, projects, and sessions. Requires a valid session cookie for authentication.

```bash
# Get user dashboard snapshot
curl -X GET "https://your-domain.com/api/dashboard" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"
```

--------------------------------

### Retrieve Public Leaderboard

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Fetches paginated player rankings with support for filtering by view, search queries, and minimum block counts.

```bash
# Get global leaderboard with pagination
curl -X GET "https://your-domain.com/api/leaderboard?view=global&page=1&pageSize=50&query=&minBlocks=0" \
  -H "Accept: application/json"
```

--------------------------------

### Active Projects API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Fetches a list of active projects associated with the authenticated user.

```bash
# Get active projects
curl -X GET "https://your-domain.com/api/projects/active" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"

# Response (200 OK)
{
  "projects": [
    {
      "id": "project-uuid",
      "key": "main-project",
      "name": "Main Project",
      "progress": 4820,
      "goal": 7200,
      "percent": 67,
      "isActive": true,
      "lastSyncedAt": "2024-04-08T14:30:00Z",
      "status": "active"
    }
  ]
}
```

--------------------------------

### Player Stats API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Provides a summary of player statistics, including daily goals and mining performance metrics.

```bash
# Get player stats summary
curl -X GET "https://your-domain.com/api/stats" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"

# Response (200 OK)
{
  "player": {
    "id": "player-uuid",
    "username": "PlayerName",
    "firstSeenAt": "2024-01-15T10:00:00Z",
    "lastSeenAt": "2024-04-08T14:30:00Z",
    "lastModVersion": "1.0.0",
    "lastMinecraftVersion": "1.21.4",
    "lastServerName": "play.aeternum.net",
    "totalSyncedBlocks": 125000,
    "aeternumTotalDigs": 98500,
    "totalSessions": 45,
    "totalPlaySeconds": 180000,
    "trustLevel": "linked"
  },
  "dailyGoal": {
    "goalDate": "2024-04-08",
    "target": 1000,
    "progress": 830,
    "completed": false,
    "percent": 83
  },
  "estimatedBlocksPerHour": 2228,
  "estimatedFinishSeconds": 4980,
  "lastSyncedAt": "2024-04-08T14:30:00Z"
}
```

--------------------------------

### POST /api/admin/sources

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Approves or rejects a server source submission.

```APIDOC
## POST /api/admin/sources

### Description
Approves or rejects a server source submission. Requires admin or management role.

### Method
POST

### Endpoint
/api/admin/sources

### Request Body
- **sourceId** (string) - Required - The UUID of the source
- **action** (string) - Required - The action to perform (e.g., "approved")

### Request Example
{
  "sourceId": "source-uuid",
  "action": "approved"
}

### Response
#### Success Response (200)
- **ok** (boolean) - Status of the operation
- **sources** (array) - Updated list of sources
- **minimumBlocks** (number) - Minimum block threshold
```

--------------------------------

### Fetch Leaderboard Data with useLeaderboard

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

React Query hook supporting pagination, filtering, and view selection for leaderboard displays.

```typescript
import { useLeaderboard } from "@/hooks/use-leaderboard";

function Leaderboard() {
  const [view, setView] = useState("global");
  const [page, setPage] = useState(1);
  const [query, setQuery] = useState("");

  const { data, isLoading, error } = useLeaderboard({
    view,
    page,
    pageSize: 50,
    query,
    minBlocks: 0,
  });

  if (isLoading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} />;

  return (
    <div>
      <ViewSelector
        views={data.views}
        selected={view}
        onChange={setView}
      />

      <SearchInput value={query} onChange={setQuery} />

      <h2>{data.selectedViewLabel}</h2>
      <p>{data.playerCount} players • {data.totalBlocks.toLocaleString()} total blocks</p>

      <TopPodium players={data.featuredRows} />

      <LeaderboardTable rows={data.rows} />

      <Pagination
        page={data.page}
        totalPages={data.totalPages}
        onPageChange={setPage}
      />
    </div>
  );
}
```

--------------------------------

### Player Stats API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Returns summarized player statistics including daily goals, estimated mining rate, and last sync time.

```APIDOC
## GET /api/stats

### Description
Retrieves a summary of player statistics, including daily goals and mining rates.

### Method
GET

### Endpoint
/api/stats

### Request Example
```bash
curl -X GET "https://your-domain.com/api/stats" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"
```

### Response
#### Success Response (200 OK)
- **player** (object) - Player-specific statistics.
  - **id** (string) - The unique identifier for the player.
  - **username** (string) - The username of the player.
  - **firstSeenAt** (string) - Timestamp of when the player was first seen (ISO 8601 format).
  - **lastSeenAt** (string) - Timestamp of when the player was last seen (ISO 8601 format).
  - **lastModVersion** (string) - The version of the mod last used by the player.
  - **lastMinecraftVersion** (string) - The version of Minecraft last played by the player.
  - **lastServerName** (string) - The name of the last server the player connected to.
  - **totalSyncedBlocks** (integer) - Total blocks synced for the player.
  - **aeternumTotalDigs** (integer) - Total digs recorded on Aeternum.
  - **totalSessions** (integer) - Total number of mining sessions.
  - **totalPlaySeconds** (integer) - Total seconds played.
  - **trustLevel** (string) - The trust level of the player (e.g., "linked").
- **dailyGoal** (object) - Information about the player's daily goal.
  - **goalDate** (string) - The date for the daily goal (YYYY-MM-DD).
  - **target** (integer) - The target number of blocks for the goal.
  - **progress** (integer) - The current progress towards the goal.
  - **completed** (boolean) - Whether the daily goal has been completed.
  - **percent** (integer) - The percentage completion of the daily goal.
- **estimatedBlocksPerHour** (integer) - Estimated blocks mined per hour.
- **estimatedFinishSeconds** (integer) - Estimated seconds remaining to reach the daily goal.
- **lastSyncedAt** (string) - Timestamp of the last synchronization (ISO 8601 format).

#### Response Example
```json
{
  "player": {
    "id": "player-uuid",
    "username": "PlayerName",
    "firstSeenAt": "2024-01-15T10:00:00Z",
    "lastSeenAt": "2024-04-08T14:30:00Z",
    "lastModVersion": "1.0.0",
    "lastMinecraftVersion": "1.21.4",
    "lastServerName": "play.aeternum.net",
    "totalSyncedBlocks": 125000,
    "aeternumTotalDigs": 98500,
    "totalSessions": 45,
    "totalPlaySeconds": 180000,
    "trustLevel": "linked"
  },
  "dailyGoal": {
    "goalDate": "2024-04-08",
    "target": 1000,
    "progress": 830,
    "completed": false,
    "percent": 83
  },
  "estimatedBlocksPerHour": 2228,
  "estimatedFinishSeconds": 4980,
  "lastSyncedAt": "2024-04-08T14:30:00Z"
}
```
```

--------------------------------

### Active Projects API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Returns only the active projects for the authenticated user.

```APIDOC
## GET /api/projects/active

### Description
Retrieves a list of active projects for the authenticated user.

### Method
GET

### Endpoint
/api/projects/active

### Request Example
```bash
curl -X GET "https://your-domain.com/api/projects/active" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"
```

### Response
#### Success Response (200 OK)
- **projects** (array) - A list of active projects.
  - Each project object contains:
    - **id** (string) - The unique identifier for the project.
    - **key** (string) - The key or slug for the project.
    - **name** (string) - The name of the project.
    - **progress** (integer) - The current progress on the project.
    - **goal** (integer) - The target goal for the project.
    - **percent** (integer) - The percentage completion of the project.
    - **isActive** (boolean) - Indicates if the project is currently active.
    - **lastSyncedAt** (string) - Timestamp of the last synchronization (ISO 8601 format).
    - **status** (string) - The current status of the project (e.g., "active").

#### Response Example
```json
{
  "projects": [
    {
      "id": "project-uuid",
      "key": "main-project",
      "name": "Main Project",
      "progress": 4820,
      "goal": 7200,
      "percent": 67,
      "isActive": true,
      "lastSyncedAt": "2024-04-08T14:30:00Z",
      "status": "active"
    }
  ]
}
```
```

--------------------------------

### Link Code Authentication API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Flow for linking Minecraft accounts using short codes generated in the browser and claimed via the mod client.

```bash
# Create link code from browser
curl -X POST "https://your-domain.com/api/auth/link-code/create" \
  -H "Content-Type: application/json" \
  -d '{ "returnTo": "/dashboard" }'

# Response (200 OK)
{
  "code": "ABC123",
  "browserToken": "browser-token-uuid",
  "expiresAt": "2024-04-08T15:00:00Z"
}
```

```bash
# Claim link code from mod
curl -X POST "https://your-domain.com/api/auth/link-code/claim" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ABC123",
    "minecraftUuid": "00000000-0000-0000-0000-000000000001",
    "username": "PlayerName",
    "clientId": "aet_3bb3e98b-2552-4f26-9d96-a54d9f5697b3"
  }'

# Response (200 OK)
{ "ok": true, "status": "claimed" }
```

```bash
# Check link code status from browser
curl -X GET "https://your-domain.com/api/auth/link-code/status?token=browser-token-uuid"

# Response when claimed (200 OK with session cookies)
{
  "status": "completed",
  "redirectTo": "/dashboard",
  "viewer": {
    "userId": "user-uuid",
    "username": "PlayerName",
    "avatarUrl": "https://minotar.net/avatar/PlayerName/32",
    "provider": "link_code"
  }
}
```

--------------------------------

### Fetch Dashboard Snapshot with useAeTweaksSnapshot

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

React Query hook for retrieving and caching user dashboard data. Handles loading, error, and authentication states.

```typescript
import { useAeTweaksSnapshot } from "@/hooks/use-aetweaks-snapshot";

function Dashboard() {
  const { data: snapshot, isLoading, error } = useAeTweaksSnapshot();

  if (isLoading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} />;
  if (!snapshot || snapshot.meta.source === "auth_required") {
    return <LoginPrompt />;
  }

  return (
    <div>
      <h1>Welcome, {snapshot.viewer?.username}</h1>
      <p>Total Blocks: {snapshot.player?.totalSyncedBlocks.toLocaleString()}</p>
      <p>Daily Progress: {snapshot.dailyGoal?.percent}%</p>
      <p>Mining Rate: {snapshot.estimatedBlocksPerHour} blocks/hour</p>

      <h2>Active Projects</h2>
      {snapshot.projects.filter(p => p.isActive).map(project => (
        <ProjectCard key={project.id} project={project} />
      ))}

      <h2>Recent Sessions</h2>
      {snapshot.sessions.slice(0, 5).map(session => (
        <SessionCard key={session.id} session={session} />
      ))}
    </div>
  );
}
```

--------------------------------

### Profile Settings API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Endpoints for retrieving and updating user profile preferences. Requires a valid session cookie and CSRF protection for PATCH requests.

```bash
# Get current profile
curl -X GET "https://your-domain.com/api/profile" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"

# Response (200 OK)
{
  "user": {
    "userId": "user-uuid",
    "username": "PlayerName",
    "avatarUrl": "https://minotar.net/avatar/PlayerName/32",
    "provider": "microsoft"
  }
}
```

```bash
# Update profile settings
curl -X PATCH "https://your-domain.com/api/profile" \
  -H "Content-Type: application/json" \
  -H "Cookie: aetweaks_session=<session_token>" \
  -H "X-CSRF-Token: <csrf_token>" \
  -d '{
    "publicProfile": false,
    "leaderboardOptIn": true,
    "sessionSharing": false,
    "hudEnabled": true,
    "hudAlignment": "top-left",
    "hudScale": 1.0
  }'

# Response (200 OK)
{ "ok": true }
```

--------------------------------

### Sync Mod Data to Supabase Edge Function

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Use this cURL command to send mining data from the AeTweaks Minecraft mod to the Supabase Edge Function. Ensure you replace placeholders with your actual project details and optional shared secret.

```bash
# Sync mod data to Supabase Edge Function
curl -X POST "https://<project-ref>.supabase.co/functions/v1/aetweaks-sync" \
  -H "Content-Type: application/json" \
  -H "x-sync-secret: <optional-shared-secret>" \
  -d '{
    "client_id": "aet_3bb3e98b-2552-4f26-9d96-a54d9f5697b3",
    "minecraft_uuid": "00000000-0000-0000-0000-000000000001",
    "username": "PlayerName",
    "mod_version": "1.0.0",
    "minecraft_version": "1.21.4",
    "world": {
      "key": "play.aeternum.net",
      "display_name": "play.aeternum.net",
      "kind": "multiplayer",
      "host": "play.aeternum.net"
    },
    "session": {
      "session_key": "sess_1712583195000",
      "started_at": "2024-04-08T12:00:00Z",
      "ended_at": "2024-04-08T13:03:00Z",
      "active_seconds": 3780,
      "total_blocks": 2340,
      "average_bph": 2228,
      "peak_bph": 6800,
      "best_streak_seconds": 840,
      "top_block": "minecraft:stone",
      "status": "ended",
      "block_breakdown": [
        { "block_id": "minecraft:stone", "count": 1880 },
        { "block_id": "minecraft:diorite", "count": 220 }
      ],
      "rate_points": []
    },
    "projects": [
      {
        "project_key": "main-project",
        "name": "Main Project",
        "progress": 4820,
        "goal": 7200,
        "is_active": true
      }
    ],
    "daily_goal": {
      "goal_date": "2024-04-08",
      "target": 1000,
      "progress": 830,
      "completed": false
    },
    "synced_stats": {
      "blocks_per_hour": 2228,
      "estimated_finish_seconds": 4980,
      "current_project_name": "Main Project",
      "current_project_progress": 4820,
      "current_project_goal": 7200,
      "daily_progress": 830,
      "daily_target": 1000
    },
    "aeternum_sidebar": {
      "server_name": "Aeternum",
      "objective_title": "Mining Stats",
      "player_digs": 98500,
      "total_digs": 5000000,
      "captured_at": "2024-04-08T14:30:00Z"
    }
  }'
```

```json
{ "ok": true }
```

```json
{ "error": "Too many requests. Please retry later." }
```

--------------------------------

### Sessions API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Returns the list of completed mining sessions for the authenticated user with filtering for qualifying sessions (minimum 30 seconds duration).

```APIDOC
## GET /api/sessions

### Description
Retrieves a list of completed mining sessions for the authenticated user, filtered for sessions longer than 30 seconds.

### Method
GET

### Endpoint
/api/sessions

### Request Example
```bash
curl -X GET "https://your-domain.com/api/sessions" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"
```

### Response
#### Success Response (200 OK)
- **sessions** (array) - A list of mining sessions.
  - Each session object contains:
    - **id** (string) - The unique identifier for the session.
    - **sessionKey** (string) - The key identifying the session.
    - **worldId** (string) - The identifier for the world where the session took place.
    - **startedAt** (string) - The timestamp when the session started (ISO 8601 format).
    - **endedAt** (string) - The timestamp when the session ended (ISO 8601 format).
    - **activeSeconds** (integer) - The duration of the session in seconds.
    - **totalBlocks** (integer) - The total number of blocks mined during the session.
    - **averageBph** (integer) - The average blocks per hour for the session.
    - **peakBph** (integer) - The peak blocks per hour achieved during the session.
    - **bestStreakSeconds** (integer) - The longest streak of mining in seconds.
    - **topBlock** (string) - The most frequently mined block during the session.
    - **status** (string) - The status of the session (e.g., "ended").

#### Response Example
```json
{
  "sessions": [
    {
      "id": "session-uuid",
      "sessionKey": "sess_1712583195000",
      "worldId": "world-uuid",
      "startedAt": "2024-04-08T12:00:00Z",
      "endedAt": "2024-04-08T13:03:00Z",
      "activeSeconds": 3780,
      "totalBlocks": 2340,
      "averageBph": 2228,
      "peakBph": 6800,
      "bestStreakSeconds": 840,
      "topBlock": "minecraft:stone",
      "status": "ended"
    }
  ]
}
```
```

--------------------------------

### Sessions API

Source: https://context7.com/darealshekel/aewt-sync-pro/llms.txt

Retrieves a list of completed mining sessions for the authenticated user, filtered by a minimum duration of 30 seconds.

```bash
# Get user sessions
curl -X GET "https://your-domain.com/api/sessions" \
  -H "Accept: application/json" \
  -H "Cookie: aetweaks_session=<session_token>"

# Response (200 OK)
{
  "sessions": [
    {
      "id": "session-uuid",
      "sessionKey": "sess_1712583195000",
      "worldId": "world-uuid",
      "startedAt": "2024-04-08T12:00:00Z",
      "endedAt": "2024-04-08T13:03:00Z",
      "activeSeconds": 3780,
      "totalBlocks": 2340,
      "averageBph": 2228,
      "peakBph": 6800,
      "bestStreakSeconds": 840,
      "topBlock": "minecraft:stone",
      "status": "ended"
    }
  ]
}
```