### GET /settings.php

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Retrieves the user's current application settings. These settings are cached for performance.

```APIDOC
## GET /settings.php

### Description
Retrieves the user's current application settings. These settings are cached for performance.

### Method
GET

### Endpoint
/settings.php

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **lang** (string) - The user's preferred language setting.
- **use12Hours** (boolean) - Whether to use 12-hour time format.
- **catchPaste** (boolean) - Whether to catch pasted content.
- **showTrackNumbers** (boolean) - Whether to display track numbers.
- **keepOriginalTimestamp** (boolean) - Whether to keep the original timestamp for scrobbles.

#### Response Example
```json
{
  "lang": "en",
  "use12Hours": false,
  "catchPaste": true,
  "showTrackNumbers": true,
  "keepOriginalTimestamp": true
}
```
```

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

### API Error Handling Structure and Example (TypeScript)

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Defines a consistent API error response structure and provides an example of how to handle these errors uniformly in TypeScript. It includes common error codes and demonstrates using a try-catch block with axios.isAxiosError to differentiate between API errors and other exceptions.

```typescript
// Error response structure
interface APIError {
  error: number;    // Error code
  message: string;  // Human-readable message
}

// Common error codes:
// 400 - Bad request (missing parameters)
// 401 - Unauthorized (invalid session)
// 404 - Not found
// 409 - Conflict (e.g., already logged in)
// 503 - Service unavailable (Last.fm down)

// Error handling example
try {
  const response = await openscrobblerAPI.post('/scrobble.php', data);
  if (response.data.error) {
    console.error(`API Error ${response.data.error}: ${response.data.message}`);
  }
} catch (error) {
  if (axios.isAxiosError(error)) {
    const apiError = error.response?.data as APIError;
    switch (apiError?.error) {
      case 401:
        // Redirect to login
        break;
      case 503:
        // Show service unavailable message
        break;
      default:
        // Generic error handling
    }
  }
}

```

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

### GET /api/v2/settings.php - User Settings

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Retrieves the current user's application settings including language preference, time format, and feature toggles.

```APIDOC
## GET /api/v2/settings.php

### Description
Retrieves the current user's application settings including language preference, time format, and feature toggles.

### Method
GET

### Endpoint
/api/v2/settings.php

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer <jwt_token>`).

### Request Example
```bash
curl -X GET "https://openscrobbler.com/api/v2/settings.php" \
  -H "Authorization: Bearer <jwt_token>"
```

### Response
#### Success Response (200)
- **settings** (object) - User settings object. (Structure not provided in source text, but would typically include fields like language, time_format, etc.)

#### Response Example
```json
{
  "settings": {
    "language": "en",
    "time_format": "12h",
    "show_notifications": true
  }
}
```
```

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

### Get User Settings (Bash)

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Retrieves the current user's application settings. This includes preferences such as language, time format, and feature toggles. The request requires an active JWT token for authentication. The response contains a JSON object detailing these settings.

```bash
# Get user settings
curl -X GET "https://openscrobbler.com/api/v2/settings.php" \
  -H "Authorization: Bearer <jwt_token>"
```

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

### GET /user.php

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Fetches the current user's profile information, including their authentication token, user details, and login status.

```APIDOC
## GET /user.php

### Description
Fetches the current user's profile information, including their authentication token, user details, and login status.

### Method
GET

### Endpoint
/user.php

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **token** (string | null) - The user's authentication token.
- **user** (object | null) - User details including id, name, avatar, and url.
  - **id** (string | null) - User's unique identifier.
  - **name** (string) - User's display name.
  - **avatar** (string) - URL to the user's avatar.
  - **url** (string | null) - URL to the user's profile.
- **isLoggedIn** (boolean) - Indicates if the user is currently logged in.

#### Response Example
```json
{
  "token": "user-auth-token",
  "user": {
    "id": "user-123",
    "name": "ExampleUser",
    "avatar": "https://example.com/avatar.jpg",
    "url": "https://example.com/user/profile"
  },
  "isLoggedIn": true
}
```
```

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

### Setlist.fm Integration - Search and Get Setlists - Bash

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Retrieves concert setlists from Setlist.fm for scrobbling live performances. Supports searching by artist name or fetching a specific setlist by its ID. Requires an Authorization header.

```bash
# Search setlists by artist name
curl -X GET "https://openscrobbler.com/api/v2/setlistfm.php?artistName=Coldplay&page=1" \
  -H "Authorization: Bearer <jwt_token>"
```

```bash
# Get specific setlist by ID
curl -X GET "https://openscrobbler.com/api/v2/setlistfm.php?setlistId=3b85d826" \
  -H "Authorization: Bearer <jwt_token>"
```

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

### Setlist.fm Integration - Search and Get Setlists

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Retrieves concert setlists from Setlist.fm for scrobbling live performances. Search by artist name or get a specific setlist by ID.

```APIDOC
## GET /api/v2/setlistfm.php

### Description
Retrieves concert setlists from Setlist.fm for scrobbling live performances. Search by artist name or get a specific setlist by ID.

### Method
GET

### Endpoint
/api/v2/setlistfm.php

### Parameters
#### Query Parameters
- **artistName** (string) - Optional - The name of the artist to search for setlists.
- **setlistId** (string) - Optional - The ID of a specific setlist to retrieve.
- **page** (integer) - Optional - The page number for artist search results.

### Request Example
```bash
# Search setlists by artist name
curl -X GET "https://openscrobbler.com/api/v2/setlistfm.php?artistName=Coldplay&page=1" \
  -H "Authorization: Bearer <jwt_token>"

# Get specific setlist by ID
curl -X GET "https://openscrobbler.com/api/v2/setlistfm.php?setlistId=3b85d826" \
  -H "Authorization: Bearer <jwt_token>"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the setlist.
- **eventDate** (string) - The date of the event.
- **artist** (object) - Information about the artist.
  - **name** (string) - The name of the artist.
- **venue** (object) - Information about the venue.
  - **name** (string) - The name of the venue.
  - **city** (object) - Information about the city.
    - **name** (string) - The name of the city.
    - **state** (string) - The state or region.
    - **country** (object) - Information about the country.
      - **name** (string) - The name of the country.
- **tour** (object) - Information about the tour.
  - **name** (string) - The name of the tour.
- **sets** (object) - Details about the sets played.
  - **set** (array) - An array of set objects.
    - **song** (array) - An array of song objects performed in the set.
      - **name** (string) - The name of the song.
- **url** (string) - The URL to the setlist on Setlist.fm.

#### Response Example
```json
{
  "id": "3b85d826",
  "eventDate": "15-01-2024",
  "artist": { "name": "Coldplay" },
  "venue": {
    "name": "Wembley Stadium",
    "city": { "name": "London", "state": "", "country": { "name": "United Kingdom" } }
  },
  "tour": { "name": "Music of the Spheres World Tour" },
  "sets": {
    "set": [
      {
        "song": [
          { "name": "Higher Power" },
          { "name": "Adventure of a Lifetime" },
          { "name": "Yellow" }
        ]
      }
    ]
  },
  "url": "https://www.setlist.fm/setlist/coldplay/..."
}
```
```

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

### GET /api/v2/user.php - Get Current User

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Retrieves the currently authenticated user's Last.fm profile information including username, avatar, play count, and account details.

```APIDOC
## GET /api/v2/user.php

### Description
Retrieves the currently authenticated user's Last.fm profile information including username, avatar, play count, and account details.

### Method
GET

### Endpoint
/api/v2/user.php

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer <jwt_token>`).

### Request Example
```bash
curl -X GET "https://openscrobbler.com/api/v2/user.php" \
  -H "Authorization: Bearer <jwt_token>"
```

### Response
#### Success Response (200)
- **user** (object) - User profile object.
  - **name** (string) - Username.
  - **playcount** (string) - Total play count.
  - **url** (string) - URL to the user's Last.fm profile.
  - **image** (array) - Array of image objects with different sizes.
  - **registered** (object) - Registration details.
  - **type** (string) - User type.

#### Response Example
```json
{
  "user": {
    "name": "username",
    "playcount": "12345",
    "url": "https://www.last.fm/user/username",
    "image": [
      { "size": "small", "#text": "https://lastfm.freetls.fastly.net/i/u/34s/avatar.png" },
      { "size": "medium", "#text": "https://lastfm.freetls.fastly.net/i/u/64s/avatar.png" },
      { "size": "large", "#text": "https://lastfm.freetls.fastly.net/i/u/174s/avatar.png" },
      { "size": "extralarge", "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/avatar.png" }
    ],
    "registered": { "unixtime": "1425001265", "#text": 1425001265 },
    "type": "user"
  }
}
```

#### Unauthenticated Response (401)
- **isLoggedIn** (boolean) - False if the user is not authenticated.

#### Unauthenticated Response Example
```json
{
  "isLoggedIn": false
}
```
```

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

### Get User Profile (Bash)

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Retrieves the profile information of the currently authenticated user from Last.fm. This includes their username, avatar URL, total play count, and registration details. The request requires a JWT token for authentication. An unauthenticated request will return a 'isLoggedIn: false' status.

```bash
# Get authenticated user profile
curl -X GET "https://openscrobbler.com/api/v2/user.php" \
  -H "Authorization: Bearer <jwt_token>"

# Success response
{
  "user": {
    "name": "username",
    "playcount": "12345",
    "url": "https://www.last.fm/user/username",
    "image": [
      { "size": "small", "#text": "https://lastfm.freetls.fastly.net/i/u/34s/avatar.png" },
      { "size": "medium", "#text": "https://lastfm.freetls.fastly.net/i/u/64s/avatar.png" },
      { "size": "large", "#text": "https://lastfm.freetls.fastly.net/i/u/174s/avatar.png" },
      { "size": "extralarge", "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/avatar.png" }
    ],
    "registered": { "unixtime": "1425001265", "#text": 1425001265 },
    "type": "user"
  }
}

# Unauthenticated response
{
  "isLoggedIn": false
}
```

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

### API Health Check - Bash

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

A simple GET request to the heartbeat endpoint to verify if the API is running and responsive. No authentication is required for this endpoint.

```bash
# Check API health
curl -X GET "https://openscrobbler.com/api/v2/heartbeat.php"
```

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

### Format and Test Code with Yarn

Source: https://github.com/elamperti/openwebscrobbler/blob/main/AGENTS.md

This snippet demonstrates common yarn commands used for maintaining code quality and ensuring functionality. It includes formatting, unit testing, type checking, and linting.

```shell
yarn prettier:fix
yarn test:unit
yarn typecheck
yarn lint
```

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

### POST /settings.php

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Updates the user's application settings. Accepts partial settings objects for targeted updates.

```APIDOC
## POST /settings.php

### Description
Updates the user's application settings. Accepts partial settings objects for targeted updates.

### Method
POST

### Endpoint
/settings.php

### Parameters
#### Request Body
- **lang** (string) - Optional - The user's preferred language setting.
- **use12Hours** (boolean) - Optional - Whether to use 12-hour time format.
- **catchPaste** (boolean) - Optional - Whether to catch pasted content.
- **showTrackNumbers** (boolean) - Optional - Whether to display track numbers.
- **keepOriginalTimestamp** (boolean) - Optional - Whether to keep the original timestamp for scrobbles.

### Request Example
```json
{
  "use12Hours": true
}
```

### Response
#### Success Response (200)
- **lang** (string) - The updated language setting.
- **use12Hours** (boolean) - The updated 12-hour time format setting.
- **catchPaste** (boolean) - The updated catch paste setting.
- **showTrackNumbers** (boolean) - The updated show track numbers setting.
- **keepOriginalTimestamp** (boolean) - The updated keep original timestamp setting.

#### Response Example
```json
{
  "lang": "en",
  "use12Hours": true,
  "catchPaste": true,
  "showTrackNumbers": true,
  "keepOriginalTimestamp": true
}
```
```

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

### Discogs Integration - Search Albums/Artists - Bash

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Proxies requests to the Discogs API for searching albums, artists, and retrieving album details. Requires an authenticated session via the Authorization header. Supports various search and retrieval methods.

```bash
# Search for albums
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=album.search&q=Meteora&type=release" \
  -H "Authorization: Bearer <jwt_token>"
```

```bash
# Search for artists
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=artist.search&q=Linkin%20Park" \
  -H "Authorization: Bearer <jwt_token>"
```

```bash
# Get album info by ID (master release)
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=album.getInfo&album_id=12345" \
  -H "Authorization: Bearer <jwt_token>"
```

```bash
# Get album info by ID (specific release)
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=album.getInfo&album_id=release-67890" \
  -H "Authorization: Bearer <jwt_token>"
```

```bash
# Get artist's top albums
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=artist.getTopAlbums&artist_id=12345" \
  -H "Authorization: Bearer <jwt_token>"
```

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

### React Hooks for User Data and Settings (TypeScript)

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Provides custom React hooks for accessing user profile and settings with automatic caching and refetching using @tanstack/react-query. `useUserData` fetches user details, while `useSettings` fetches and allows updating user settings. Dependencies include '@tanstack/react-query' and 'openscrobblerAPI'.

```typescript
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

// useUserData hook usage
export const useUserData = () => {
  const { data, isLoading, isError, isFetching } = useQuery({
    queryKey: ['user', 'self'],
    queryFn: () => openscrobblerAPI.get('/user.php').then(({ data }) => ({
      token: data?.token || null,
      user: {
        id: data?.user?.id || null,
        name: data?.user?.name || '',
        avatar: data?.user?.image,
        url: data?.user?.url || null,
      },
      isLoggedIn: !!data?.user?.name,
    })),
    staleTime: 1000 * 60 * 2, // 2 minutes
    refetchOnWindowFocus: true,
  });

  return { user: data?.user, isLoggedIn: data?.isLoggedIn, isLoading, isError, isFetching };
};

// useSettings hook usage
export const useSettings = () => {
  const queryClient = useQueryClient();

  const { data: settings, isLoading } = useQuery({
    queryKey: ['user', 'settings'],
    queryFn: () => openscrobblerAPI.get('/settings.php').then(({ data }) => ({
      lang: data?.lang ?? 'auto',
      use12Hours: !!data?.use12Hours,
      catchPaste: data?.catchPaste ?? true,
      showTrackNumbers: !!data?.showTrackNumbers,
      keepOriginalTimestamp: data?.keepOriginalTimestamp ?? true,
    })),
    staleTime: Infinity,
  });

  const updateSettings = useMutation({
    mutationFn: (newSettings: Partial<Settings>) =>
      openscrobblerAPI.post('/settings.php', new URLSearchParams(newSettings as any)),
    onSuccess: (data) => queryClient.setQueryData(['user', 'settings'], data),
  });

  return { settings, updateSettings: updateSettings.mutate, isLoading };
};

// Component usage example
function SettingsPage() {
  const { settings, updateSettings, isLoading } = useSettings();

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <label>
        <input
          type="checkbox"
          checked={settings.use12Hours}
          onChange={(e) => updateSettings({ use12Hours: e.target.checked })}
        />
        Use 12-hour time format
      </label>
    </div>
  );
}

```

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

### POST /api/v2/scrobble.php - Scrobble Tracks

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Submits one or more tracks to Last.fm for scrobbling. Supports batch scrobbling of up to 50 tracks per request with artist, track, album, album artist, and timestamp information.

```APIDOC
## POST /api/v2/scrobble.php

### Description
Submits one or more tracks to Last.fm for scrobbling. Supports batch scrobbling of up to 50 tracks per request with artist, track, album, album artist, and timestamp information.

### Method
POST

### Endpoint
/api/v2/scrobble.php

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer <jwt_token>`).
- **Content-Type** (string) - Required - `application/x-www-form-urlencoded`.
- **scrobbleUUID** (string) - Optional - A unique identifier for the scrobble request.

#### Request Body
- **artist[n]** (string) - Required - Artist name for track 'n'.
- **track[n]** (string) - Required - Track title for track 'n'.
- **album[n]** (string) - Optional - Album name for track 'n'.
- **albumArtist[n]** (string) - Optional - Album artist name for track 'n'.
- **timestamp[n]** (string) - Required - ISO 8601 timestamp for track 'n' (e.g., `2024-01-15T20:30:00.000Z`).
- **validationToken** (string) - Optional - Token for validation (e.g., captcha).

### Request Example (Single Track)
```bash
curl -X POST "https://openscrobbler.com/api/v2/scrobble.php" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "scrobbleUUID: abc123" \
  -d "artist[0]=Arctic Monkeys" \
  -d "track[0]=Arabella" \
  -d "album[0]=AM" \
  -d "albumArtist[0]=Arctic Monkeys" \
  -d "timestamp[0]=2024-01-15T20:30:00.000Z" \
  -d "validationToken=captcha_token"
```

### Request Example (Batch Tracks)
```bash
curl -X POST "https://openscrobbler.com/api/v2/scrobble.php" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "artist[0]=Radiohead&track[0]=Paranoid Android&album[0]=OK Computer&timestamp[0]=2024-01-15T20:00:00.000Z" \
  -d "artist[1]=Radiohead&track[1]=Karma Police&album[1]=OK Computer&timestamp[1]=2024-01-15T20:06:00.000Z"
```

### Response
#### Success Response (200)
- **scrobbles** (object) - Contains information about the scrobbled tracks.
  - **scrobble** (object or array) - Details of the scrobbled track(s).
    - **artist** (object) - Artist details.
    - **album** (object) - Album details.
    - **track** (object) - Track details.
    - **ignoredMessage** (object) - Information if the scrobble was ignored.
    - **albumArtist** (object) - Album artist details.
    - **timestamp** (string) - Unix timestamp of the scrobble.
  - **@attr** (object) - Attributes of the scrobble request.
    - **ignored** (integer) - Number of ignored scrobbles.
    - **accepted** (integer) - Number of accepted scrobbles.

#### Success Response Example
```json
{
  "scrobbles": {
    "scrobble": {
      "artist": { "corrected": "0", "#text": "Arctic Monkeys" },
      "album": { "corrected": "0", "#text": "AM" },
      "track": { "corrected": "0", "#text": "Arabella" },
      "ignoredMessage": { "code": "0", "#text": "" },
      "albumArtist": { "corrected": "0", "#text": "Arctic Monkeys" },
      "timestamp": "1705351800"
    },
    "@attr": { "ignored": 0, "accepted": 1 }
  }
}
```

#### Error Response (e.g., 400)
- **error** (integer) - Error code.
- **message** (string) - Error description.

#### Error Response Example
```json
{
  "error": 400,
  "message": "Artist or title missing"
}
```
```

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

### Scrobble Tracks (Bash)

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Submits one or more tracks to Last.fm for scrobbling. This endpoint supports both single track submissions and batch submissions of up to 50 tracks. Each track requires artist, track name, album, album artist, and a timestamp. A validation token may also be required. The response indicates which tracks were accepted and provides details for successful scrobbles, or an error message for missing data.

```bash
# Scrobble a single track
curl -X POST "https://openscrobbler.com/api/v2/scrobble.php" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "scrobbleUUID: abc123" \
  -d "artist[0]=Arctic Monkeys" \
  -d "track[0]=Arabella" \
  -d "album[0]=AM" \
  -d "albumArtist[0]=Arctic Monkeys" \
  -d "timestamp[0]=2024-01-15T20:30:00.000Z" \
  -d "validationToken=captcha_token"

# Scrobble multiple tracks (batch)
curl -X POST "https://openscrobbler.com/api/v2/scrobble.php" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "artist[0]=Radiohead&track[0]=Paranoid Android&album[0]=OK Computer&timestamp[0]=2024-01-15T20:00:00.000Z" \
  -d "artist[1]=Radiohead&track[1]=Karma Police&album[1]=OK Computer&timestamp[1]=2024-01-15T20:06:00.000Z"

# Success response
{
  "scrobbles": {
    "scrobble": {
      "artist": { "corrected": "0", "#text": "Arctic Monkeys" },
      "album": { "corrected": "0", "#text": "AM" },
      "track": { "corrected": "0", "#text": "Arabella" },
      "ignoredMessage": { "code": "0", "#text": "" },
      "albumArtist": { "corrected": "0", "#text": "Arctic Monkeys" },
      "timestamp": "1705351800"
    },
    "@attr": { "ignored": 0, "accepted": 1 }
  }
}

# Error response (missing data)
{
  "error": 400,
  "message": "Artist or title missing"
}
```

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

### Authenticate Last.fm Token (Bash)

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Validates a Last.fm authentication token received from the OAuth callback to establish a user session. It sends the token and a Cloudflare challenge response to the API and returns a JWT for subsequent authenticated requests. Invalid tokens result in an error response.

```bash
# Validate Last.fm token after OAuth callback
curl -X POST "https://openscrobbler.com/api/v2/callback.php" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=abc123def456ghi789jkl012mno345pq" \
  -d "cfchallenge=turnstile_response_token"

# Success response
{
  "status": "ok",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

# Error response (invalid token)
{
  "error": 999,
  "message": "Last.fm authentication failed"
}
```

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

### Update User Settings - Bash

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Updates one or more user settings via a POST request. Supports partial updates, meaning only the specified fields will be modified. Requires an Authorization header with a JWT token.

```bash
# Update user settings
curl -X POST "https://openscrobbler.com/api/v2/settings.php" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "use12Hours=true" \
  -d "lang=es" \
  -d "catchPaste=true" \
  -d "showTrackNumbers=true" \
  -d "keepOriginalTimestamp=false" \
  -d "dataProvider=discogs"
```

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

### API Client Configuration - TypeScript

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Configures the Axios HTTP client for making API calls to the OpenWebScrobbler backend. It automatically handles authentication tokens and API versioning, and customizes status code validation.

```typescript
import axios from 'axios';

// API client setup (from src/utils/clients/api/apiClient.ts)
export const openscrobblerAPI = axios.create({
  baseURL: '/api/v2',
  headers: {
    'OWS-Version': process.env.REACT_APP_VERSION || '',
  },
  validateStatus: (statusCode: number) => {
    if (statusCode === 503) return true;
    return statusCode >= 200 && statusCode < 300;
  },
});

// Token interceptor for authenticated requests
openscrobblerAPI.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});
```

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

### POST /api/v2/callback.php - Validate Last.fm Token

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Validates a Last.fm authentication token received from the OAuth callback and establishes a user session. Returns a JWT token for subsequent API calls.

```APIDOC
## POST /api/v2/callback.php

### Description
Validates a Last.fm authentication token received from the OAuth callback and establishes a user session. Returns a JWT token for subsequent API calls.

### Method
POST

### Endpoint
/api/v2/callback.php

### Parameters
#### Query Parameters
- **token** (string) - Required - The Last.fm authentication token.
- **cfchallenge** (string) - Optional - Cloudflare challenge token.

### Request Example
```bash
curl -X POST "https://openscrobbler.com/api/v2/callback.php" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=abc123def456ghi789jkl012mno345pq" \
  -d "cfchallenge=turnstile_response_token"
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success ('ok').
- **token** (string) - The JWT token for authenticated requests.

#### Response Example
```json
{
  "status": "ok",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Error Response (e.g., 400)
- **error** (integer) - Error code.
- **message** (string) - Error description.

#### Error Response Example
```json
{
  "error": 999,
  "message": "Last.fm authentication failed"
}
```
```

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

### POST /scrobble.php

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Submits tracks to the scrobble API with proper payload transformation. It requires a validation token and scrobble UUID for authentication and tracking.

```APIDOC
## POST /scrobble.php

### Description
Submits tracks to the scrobble API with proper payload transformation. It requires a validation token and scrobble UUID for authentication and tracking.

### Method
POST

### Endpoint
/scrobble.php

### Parameters
#### Query Parameters
- **validationToken** (string) - Required - Token for validating the request.
- **scrobbleUUID** (string) - Required - Unique identifier for the scrobble batch.

#### Request Body
- **artist** (string[]) - Required - Array of artist names.
- **track** (string[]) - Required - Array of track titles.
- **album** (string[]) - Optional - Array of album names.
- **albumArtist** (string[]) - Optional - Array of album artist names.
- **timestamp** (string[]) - Required - Array of ISO 8601 formatted timestamps.

### Request Example
```json
{
  "artist": ["Daft Punk"],
  "track": ["Get Lucky"],
  "album": ["Random Access Memories"],
  "albumArtist": ["Daft Punk"],
  "timestamp": ["2024-01-15T20:00:00Z"],
  "validationToken": "captcha-token"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success status of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### Discogs Integration - Search Albums/Artists

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Proxies requests to the Discogs API for searching albums, artists, and retrieving album details. Requires an authenticated session.

```APIDOC
## GET /api/v2/discogs.php

### Description
Proxies requests to the Discogs API for searching albums, artists, and retrieving album details. Requires an authenticated session.

### Method
GET

### Endpoint
/api/v2/discogs.php

### Parameters
#### Query Parameters
- **method** (string) - Required - The Discogs API method to call (e.g., 'album.search', 'artist.search', 'album.getInfo', 'artist.getTopAlbums').
- **q** (string) - Optional - The search query (for artist and album searches).
- **type** (string) - Optional - The type of search (e.g., 'release' for album search).
- **album_id** (string) - Optional - The ID of the album or release.
- **artist_id** (string) - Optional - The ID of the artist.
- **page** (integer) - Optional - The page number for search results.

### Request Example
```bash
# Search for albums
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=album.search&q=Meteora&type=release" \
  -H "Authorization: Bearer <jwt_token>"

# Search for artists
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=artist.search&q=Linkin%20Park" \
  -H "Authorization: Bearer <jwt_token>"

# Get album info by ID (master release)
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=album.getInfo&album_id=12345" \
  -H "Authorization: Bearer <jwt_token>"

# Get album info by ID (specific release)
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=album.getInfo&album_id=release-67890" \
  -H "Authorization: Bearer <jwt_token>"

# Get artist's top albums
curl -X GET "https://openscrobbler.com/api/v2/discogs.php?method=artist.getTopAlbums&artist_id=12345" \
  -H "Authorization: Bearer <jwt_token>"
```

### Response
#### Success Response (200)
- The response structure varies depending on the 'method' called. Refer to Discogs API documentation for specific response formats.

#### Error Response
- **error** (integer) - Error code.
- **message** (string) - Error description.

#### Response Example (Error)
```json
{
  "error": 603,
  "message": "Invalid method"
}
```
```

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

### User Settings - Update Settings

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Updates one or more user settings. Supports partial updates, meaning only the specified fields will be modified.

```APIDOC
## POST /api/v2/settings.php

### Description
Updates one or more user settings. Supports partial updates - only specified fields will be modified.

### Method
POST

### Endpoint
/api/v2/settings.php

### Parameters
#### Query Parameters
- **use12Hours** (boolean) - Optional - Use 12-hour format for time.
- **lang** (string) - Optional - Language code for the user interface.
- **catchPaste** (boolean) - Optional - Enable or disable catch paste functionality.
- **showTrackNumbers** (boolean) - Optional - Show track numbers in lists.
- **keepOriginalTimestamp** (boolean) - Optional - Keep the original timestamp for scrobbles.
- **dataProvider** (string) - Optional - Preferred data provider (e.g., 'discogs').

### Request Example
```bash
curl -X POST "https://openscrobbler.com/api/v2/settings.php" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "use12Hours=true" \
  -d "lang=es" \
  -d "catchPaste=true" \
  -d "showTrackNumbers=true" \
  -d "keepOriginalTimestamp=false" \
  -d "dataProvider=discogs"
```

### Response
#### Success Response (200)
- **catchPaste** (boolean) - The current setting for catchPaste.
- **use12Hours** (boolean) - The current setting for use12Hours.
- **showTrackNumbers** (boolean) - The current setting for showTrackNumbers.
- **lang** (string) - The current language setting.
- **keepOriginalTimestamp** (boolean) - The current setting for keepOriginalTimestamp.
- **dataProvider** (string) - The current data provider setting.
- **saved** (boolean) - Indicates if the settings were saved successfully.

#### Response Example
```json
{
  "catchPaste": true,
  "use12Hours": true,
  "showTrackNumbers": true,
  "lang": "es",
  "keepOriginalTimestamp": false,
  "dataProvider": "discogs",
  "saved": true
}
```
```

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

### Submit Tracks to Scrobble API (TypeScript)

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Submits tracks to the scrobble API with proper payload transformation. It defines Track and Scrobble types, prepares data using prepareScrobbles, and makes the API call using openscrobblerAPI.post. Dependencies include 'utils/types/scrobble' and 'openscrobblerAPI'.

```typescript
import type { Scrobble } from 'utils/types/scrobble';

// Track type definition
type Track = {
  id: string;
  trackNumber: string | number;
  artist: string;
  title: string;
  album: string;
  albumArtist: string;
  cover?: { sm?: string; lg?: string };
  duration: number;
};

// Scrobble type extends Track
type Scrobble = Track & {
  scrobbleUUID?: string;
  status: 'pending' | 'queued' | 'success' | 'error' | 'retry';
  errorMessage?: string;
  errorDescription?: string;
  timestamp: Date;
};

// Prepare scrobbles for API submission
function prepareScrobbles(scrobbles: Partial<Scrobble>[]) {
  return {
    artist: scrobbles.map(s => s.artist),
    track: scrobbles.map(s => s.title),
    album: scrobbles.map(s => s.album || ''),
    albumArtist: scrobbles.map(s => s.albumArtist || ''),
    timestamp: scrobbles.map(s => new Date(s.timestamp).toISOString()),
  };
}

// Scrobble API call
export function scrobble(scrobbles: Scrobble[], scrobbleUUID: string, validationToken: string) {
  return openscrobblerAPI.post(
    '/scrobble.php',
    { ...prepareScrobbles(scrobbles), validationToken },
    {
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        scrobbleUUID,
      },
    }
  );
}

// Usage example
const tracks: Scrobble[] = [
  {
    id: 'track-1',
    trackNumber: 1,
    artist: 'Daft Punk',
    title: 'Get Lucky',
    album: 'Random Access Memories',
    albumArtist: 'Daft Punk',
    duration: 369,
    status: 'queued',
    timestamp: new Date('2024-01-15T20:00:00Z'),
  }
];
await scrobble(tracks, 'uuid-123', 'captcha-token');

```

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

### POST /api/v2/logout.php - Logout

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Destroys the user session and clears all authentication data. Returns a simple status confirmation.

```APIDOC
## POST /api/v2/logout.php

### Description
Destroys the user session and clears all authentication data. Returns a simple status confirmation.

### Method
POST

### Endpoint
/api/v2/logout.php

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer <jwt_token>`).

### Request Example
```bash
curl -X POST "https://openscrobbler.com/api/v2/logout.php" \
  -H "Authorization: Bearer <jwt_token>"
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success ('ok').

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

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

### Logout User (Bash)

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

Destroys the current user's session and invalidates all authentication data. This is achieved by sending a POST request with the JWT token in the Authorization header. A successful logout returns a simple status confirmation.

```bash
# Logout current user
curl -X POST "https://openscrobbler.com/api/v2/logout.php" \
  -H "Authorization: Bearer <jwt_token>"

# Success response
{
  "status": "ok"
}
```

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

### API Health Check

Source: https://context7.com/elamperti/openwebscrobbler/llms.txt

A simple heartbeat endpoint to verify that the API is running and responsive.

```APIDOC
## GET /api/v2/heartbeat.php

### Description
Simple heartbeat endpoint to verify the API is running and responsive.

### Method
GET

### Endpoint
/api/v2/heartbeat.php

### Parameters
No parameters required.

### Request Example
```bash
curl -X GET "https://openscrobbler.com/api/v2/heartbeat.php"
```

### Response
#### Success Response (200)
- The response indicates that the server is running. The exact content may vary, but a successful response signifies the API is operational.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.