### Install letterboxd-client

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Install the letterboxd-client package using npm.

```bash
npm install letterboxd-client
```

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

### Installation

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Install the letterboxd-client library using npm.

```APIDOC
## Installation

```bash
npm install letterboxd-client
```
```

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

### GET /me

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve the authenticated member's account details.

```APIDOC
## GET /me

### Description
Retrieve the authenticated member's account details. Requires authentication.

### Method
GET
```

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

### GET /members

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve a paginated list of members.

```APIDOC
## GET /members

### Description
Retrieve a paginated list of members.

### Method
GET

### Parameters
#### Query Parameters
- **sort** (string) - Optional - Sorting criteria.
- **perPage** (number) - Optional - Number of items per page.
```

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

### Initialize and Use Letterboxd Client

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Initialize the client with API credentials and make a request to get film details. Requires API key and secret for initialization.

```javascript
import Client from 'letterboxd-client';
// const { default: Client } = require('letterboxd-client')

const apiKey = 'your letterboxd api key';
const apiSecret = 'your letterboxd api secret';

const client = new Client(apiKey, apiSecret);
const { status, data } = await client.film.get('ljDs');

console.log(data.name); // RRR
console.log(data.tagline); // Rise Roar Revolt
```

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

### GET /logEntry/comments

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve comments on a specific review.

```APIDOC
## GET /logEntry/comments

### Description
Retrieve comments on a review.

### Method
GET

### Parameters
#### Path Parameters
- **logEntryId** (string) - Required - The ID of the review.

#### Query Parameters
- **sort** (string) - Optional - Sorting criteria.
- **perPage** (number) - Optional - Number of items per page.

### Response
#### Success Response (200)
- **items** (array) - List of comments.
```

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

### GET /members/{memberId}

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve detailed information about a member.

```APIDOC
## GET /members/{memberId}

### Description
Retrieve detailed information about a member.

### Method
GET

### Parameters
#### Path Parameters
- **memberId** (string) - Required - The ID of the member.
```

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

### GET /news

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve recent news from Letterboxd editors.

```APIDOC
## GET /news

### Description
Retrieve recent news from Letterboxd editors.

### Method
GET

### Parameters
#### Query Parameters
- **perPage** (number) - Optional - Number of news items to retrieve.
```

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

### GET /stories

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve stories published by members.

```APIDOC
## GET /stories

### Description
Retrieve stories published by members.

### Method
GET

### Parameters
#### Query Parameters
- **sort** (string) - Optional - Sorting criteria.
- **perPage** (number) - Optional - Number of stories to retrieve.
```

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

### GET /stories/{storyId}

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve a specific story by its ID.

```APIDOC
## GET /stories/{storyId}

### Description
Retrieve a specific story by its ID.

### Method
GET

### Parameters
#### Path Parameters
- **storyId** (string) - Required - The ID of the story.
```

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

### GET /members/pronouns

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve the list of pronouns available for member profiles.

```APIDOC
## GET /members/pronouns

### Description
Retrieve the list of pronouns available for member profiles.

### Method
GET
```

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

### Get All Log Entries

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve log entries, including diary entries and reviews, with options for filtering by member, sorting, and specifying conditions. Useful for fetching a user's activity.

```typescript
const { status, data } = await client.logEntry.all({
  member: 'memberId',
  sort: 'WhenAdded',
  where: 'HasReview',
  perPage: 20
});

if (status === 200) {
  data.items.forEach(entry => {
    console.log(`${entry.film.name} - Rating: ${entry.rating}`);
    if (entry.review) {
      console.log(`Review: ${entry.review.text.substring(0, 100)}...`);
    }
    if (entry.diaryDetails) {
      console.log(`Watched: ${entry.diaryDetails.diaryDate}`);
    }
  });
}
```

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

### GET /search

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Search across films, members, lists, contributors, and more.

```APIDOC
## GET /search

### Description
Search across films, members, lists, contributors, and more.

### Method
GET

### Parameters
#### Query Parameters
- **input** (string) - Required - The search query string.
- **searchMethod** (string) - Optional - The search method (e.g., 'FullText').
- **include** (array) - Optional - Types of items to include in results.
- **perPage** (number) - Optional - Number of results per page.
```

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

### Get All Stories

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve stories published by members. Allows sorting by publication date and specifying results per page.

```typescript
const { status, data } = await client.story.all({
  sort: 'WhenPublishedLatestFirst',
  perPage: 10
});

if (status === 200) {
  data.items.forEach(story => {
    console.log(`${story.name} by ${story.author.displayName}`);
  });
}
```

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

### GET /film/member-relationship

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Get details of the authenticated member's relationship with a specific film. Requires authentication.

```APIDOC
## Get Member's Film Relationship

### Description
Get details of the authenticated member's relationship with a specific film. Requires authentication.

### Method
GET

### Endpoint
/film/{filmId}/member-relationship

### Parameters
#### Path Parameters
- **filmId** (string) - Required - The ID of the film.

### Response
#### Success Response (200)
- **watched** (boolean) - Whether the member has watched the film.
- **liked** (boolean) - Whether the member has liked the film.
- **inWatchlist** (boolean) - Whether the film is in the member's watchlist.
- **rating** (integer) - The member's rating for the film (1-5).
- **favorited** (boolean) - Whether the member has favorited the film.

### Response Example
```json
{
  "watched": true,
  "liked": false,
  "inWatchlist": true,
  "rating": 4,
  "favorited": false
}
```
```

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

### Get Member Watchlist

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve a member's public watchlist. Allows sorting by added date and pagination.

```typescript
const { status, data } = await client.member.watchlist('memberId', {
  sort: 'Added',
  perPage: 20
});

if (status === 200) {
  data.items.forEach(film => {
    console.log(`${film.name} (${film.releaseYear})`);
  });
}
```

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

### Get Available Pronouns

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve the list of available pronouns for member profiles. Each entry includes a label and subject/object pronouns.

```typescript
const { status, data } = await client.member.pronouns();

if (status === 200) {
  data.items.forEach(pronoun => {
    console.log(`${pronoun.label}: ${pronoun.subjectPronoun}/${pronoun.objectPronoun}`);
  });
}
```

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

### GET /films/{id}

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve detailed information about a specific film by its Letterboxd ID (LID).

```APIDOC
## GET /films/{id}

### Description
Retrieve detailed information about a specific film by its Letterboxd ID (LID).

### Method
GET

### Path Parameters
- **id** (string) - Required - The Letterboxd ID of the film

### Response
#### Success Response (200)
- **name** (string) - Film title
- **releaseYear** (number) - Release year
- **tagline** (string) - Film tagline
- **description** (string) - Film description
- **runTime** (number) - Runtime in minutes
- **genres** (array) - List of genres
- **countries** (array) - List of countries
- **top250Position** (number) - Position in Top 250 list
```

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

### GET /members/{memberId}/watchlist

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve a member's public watchlist.

```APIDOC
## GET /members/{memberId}/watchlist

### Description
Retrieve a member's public watchlist.

### Method
GET

### Parameters
#### Path Parameters
- **memberId** (string) - Required - The ID of the member.

#### Query Parameters
- **sort** (string) - Optional - Sorting criteria.
- **perPage** (number) - Optional - Number of items per page.
```

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

### GET /film/members

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve a list of members who have interacted with a film.

```APIDOC
## Get Members Who Interacted with Film

### Description
Retrieve a list of members who have interacted with a film.

### Method
GET

### Endpoint
/film/{filmId}/members

### Parameters
#### Path Parameters
- **filmId** (string) - Required - The ID of the film.

#### Query Parameters
- **filmRelationship** (string) - Optional - Filter by relationship type (e.g., 'Liked', 'Watched', 'InWatchlist').
- **perPage** (integer) - Optional - Number of results per page (default: 20).
- **sort** (string) - Optional - Sorting order (e.g., 'Date', 'Username').

### Response
#### Success Response (200)
- **items** (array) - An array of member interaction objects.
  - **member** (object) - Information about the member.
    - **displayName** (string) - The display name of the member.
  - **relationship** (object) - Details of the member's relationship with the film.
    - **rating** (integer) - The member's rating for the film (1-5).

### Response Example
```json
{
  "items": [
    {
      "member": {
        "displayName": "John Doe"
      },
      "relationship": {
        "rating": 5
      }
    }
  ]
}
```
```

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

### GET /films

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve a paginated list of films with optional filtering and sorting parameters.

```APIDOC
## GET /films

### Description
Retrieve a paginated list of films with optional filtering and sorting parameters.

### Method
GET

### Query Parameters
- **perPage** (number) - Optional - Number of items per page
- **decade** (number) - Optional - Filter by decade
- **genre** (string) - Optional - Filter by genre
- **sort** (string) - Optional - Sort criteria
- **where** (string) - Optional - Filter condition
- **cursor** (string) - Optional - Pagination cursor

### Response
#### Success Response (200)
- **items** (array) - List of film objects
- **next** (string) - Cursor for the next page
```

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

### Get All Members

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve a paginated list of all members. Supports sorting by popularity and specifying the number of items per page.

```typescript
const { status, data } = await client.member.all({
  sort: 'MemberPopularity',
  perPage: 20
});

if (status === 200) {
  data.items.forEach(member => {
    console.log(`${member.displayName} (@${member.username})`);
    console.log(`Status: ${member.memberStatus}`);
  });
}
```

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

### GET /members/{memberId}/statistics

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve statistics for a member.

```APIDOC
## GET /members/{memberId}/statistics

### Description
Retrieve statistics for a member.

### Method
GET

### Parameters
#### Path Parameters
- **memberId** (string) - Required - The ID of the member.
```

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

### Get Film Collection

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve details about a specific film collection.

```typescript
const { status, data } = await client.filmCollection.get('collectionId', {
  sort: 'ReleaseDateEarliestFirst'
});

if (status === 200) {
  console.log('Collection:', data.name);
  console.log('Films in collection:');
  data.films.forEach((film, index) => {
    console.log(`${index + 1}. ${film.name} (${film.releaseYear})`);
  });
}
```

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

### Get Log Entry by ID

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Fetch a specific log entry using its unique ID. This allows retrieval of details like film name, rating, like status, owner information, and review content if available.

```typescript
const { status, data } = await client.logEntry.get('logEntryId');

if (status === 200) {
  console.log('Film:', data.film.name);
  console.log('Rating:', data.rating);
  console.log('Liked:', data.like);
  console.log('Owner:', data.owner.displayName);

  if (entry.review) {
    console.log('Review:', data.review.text);
    console.log('Contains Spoilers:', data.review.containsSpoilers);
  }
}
```

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

### Get Story by ID

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve a specific story by its ID. Returns status and data including name, author, and body HTML.

```typescript
const { status, data } = await client.story.get('storyId');

if (status === 200) {
  console.log('Title:', data.name);
  console.log('Author:', data.author.displayName);
  console.log('Body:', data.bodyHtml);
}
```

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

### Get Film Details

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve detailed information about a specific film using its Letterboxd ID.

```typescript
const { status, data } = await client.film.get('ljDs');

if (status === 200) {
  console.log('Title:', data.name);
  console.log('Year:', data.releaseYear);
  console.log('Tagline:', data.tagline);
  console.log('Description:', data.description);
  console.log('Runtime:', data.runTime, 'minutes');
  console.log('Genres:', data.genres.map(g => g.name).join(', '));
  console.log('Countries:', data.countries.map(c => c.name).join(', '));
  console.log('Top 250 Position:', data.top250Position);
}
```

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

### GET /members/{memberId}/activity

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve a member's recent activity feed.

```APIDOC
## GET /members/{memberId}/activity

### Description
Retrieve a member's recent activity feed.

### Method
GET

### Parameters
#### Path Parameters
- **memberId** (string) - Required - The ID of the member.

#### Query Parameters
- **include** (string) - Optional - Activity types to include.
- **perPage** (number) - Optional - Number of items per page.
```

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

### GET /films/{id}/statistics

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve statistical data about a film including ratings, watches, and likes.

```APIDOC
## GET /films/{id}/statistics

### Description
Retrieve statistical data about a film including ratings, watches, and likes.

### Method
GET

### Path Parameters
- **id** (string) - Required - The Letterboxd ID of the film

### Response
#### Success Response (200)
- **rating** (number) - Average rating
- **counts** (object) - Object containing watches, likes, ratings, and reviews counts
- **ratingsHistogram** (array) - Histogram data of ratings
```

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

### Get Member by ID

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Fetch detailed information for a specific member using their ID. Includes display name, username, bio, location, status, and favorite films.

```typescript
const { status, data } = await client.member.get('memberId');

if (status === 200) {
  console.log('Display Name:', data.displayName);
  console.log('Username:', data.username);
  console.log('Bio:', data.bio);
  console.log('Location:', data.location);
  console.log('Member Status:', data.memberStatus);

  console.log('Favorite Films:');
  data.favoriteFilms.forEach(film => {
    console.log(`  - ${film.name}`);
  });
}
```

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

### Get Member Statistics

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve various statistics for a member, such as films watched, rated, reviews, lists, followers, following, and watchlist count.

```typescript
const { status, data } = await client.member.statistics('memberId');

if (status === 200) {
  console.log('Films Watched:', data.counts.watches);
  console.log('Films Rated:', data.counts.ratings);
  console.log('Reviews:', data.counts.reviews);
  console.log('Lists:', data.counts.lists);
  console.log('Followers:', data.counts.followers);
  console.log('Following:', data.counts.following);
  console.log('Watchlist:', data.counts.watchlist);
}
```

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

### Get Film Statistics

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve statistical data for a film, including ratings, watches, and likes.

```typescript
const { status, data } = await client.film.statistics('ljDs');

if (status === 200) {
  console.log('Average Rating:', data.rating);
  console.log('Total Watches:', data.counts.watches);
  console.log('Total Likes:', data.counts.likes);
  console.log('Total Ratings:', data.counts.ratings);
  console.log('Total Reviews:', data.counts.reviews);

  // Ratings histogram
  data.ratingsHistogram.forEach(bar => {
    console.log(`${bar.rating} stars: ${bar.count} ratings`);
  });
}
```

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

### Get Review Comments

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve comments for a specific review. Requires a log entry ID and supports sorting and pagination.

```typescript
const { status, data } = await client.logEntry.getComments('logEntryId', {
  sort: 'Date',
  perPage: 20
});

if (status === 200) {
  data.items.forEach(comment => {
    console.log(`${comment.member.displayName}: ${comment.comment}`);
  });
}
```

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

### Get Current Member

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve the authenticated member's account details. Requires authentication and returns information like display name, email, and account settings.

```typescript
const { status, data } = await authenticatedClient.me.get();

if (status === 200) {
  console.log('Member:', data.member.displayName);
  console.log('Email:', data.emailAddress);
  console.log('Email Validated:', data.emailAddressValidated);
  console.log('Can Comment:', data.canComment);
  console.log('Private Account:', data.privateAccount);
}
```

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

### Get Member Activity

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Fetch a member's recent activity feed. Supports filtering by activity type and pagination.

```typescript
const { status, data } = await client.member.getMemberActivity('memberId', {
  include: 'ReviewActivity',
  perPage: 20
});

if (status === 200) {
  data.items.forEach(activity => {
    console.log(`${activity.type} at ${activity.whenCreated}`);
  });
}
```

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

### Retrieve List Statistics

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Get statistics for a list, such as the number of likes and comments. A successful request returns a 204 status code.

```typescript
const { status, data } = await client.list.statistics('listId');

if (status === 204) {
  console.log('Likes:', data.counts.likes);
  console.log('Comments:', data.counts.comments);
}
```

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

### Basic Usage

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Initialize the client with API credentials and make a basic film lookup.

```APIDOC
## Usage

```js
import Client from 'letterboxd-client';
// const { default: Client } = require('letterboxd-client')

const apiKey = 'your letterboxd api key';
const apiSecret = 'your letterboxd api secret';

const client = new Client(apiKey, apiSecret);
const { status, data } = await client.film.get('ljDs');

console.log(data.name); // RRR
console.log(data.tagline); // Rise Roar Revolt
```
```

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

### Initialize Letterboxd Client

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Create a client instance using API credentials. An optional access token is required for authenticated user operations.

```typescript
import Client from 'letterboxd-client';

// Basic client for public endpoints
const client = new Client('your-api-key', 'your-api-secret');

// Client with user authentication for protected endpoints
const authenticatedClient = new Client('your-api-key', 'your-api-secret', 'user-access-token');
```

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

### Create a New List

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Use this to create a new list. Requires authentication. You can specify the list's name, description, whether it's ranked or published, and initial entries.

```typescript
const { status, data } = await authenticatedClient.list.create({
  name: 'My Favorite Sci-Fi Films',
  description: 'A collection of the best science fiction movies',
  ranked: true,
  published: true,
  entries: [
    { film: 'filmId1', rank: 1, notes: 'An absolute masterpiece' },
    { film: 'filmId2', rank: 2 },
    { film: 'filmId3', rank: 3 }
  ],
  tags: ['sci-fi', 'favorites']
});

if (status === 200) {
  console.log('List created:', data.data.id);
}
```

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

### POST /me/push-notifications

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Register a device for push notifications.

```APIDOC
## POST /me/push-notifications

### Description
Register a device for push notifications. Requires authentication.

### Method
POST

### Parameters
#### Request Body
- **deviceId** (string) - Required
- **deviceName** (string) - Required
- **token** (string) - Required
```

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

### Register New Account

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Create a new Letterboxd account. Requires username, email, password, and acceptance of terms.

```typescript
const { status, data } = await client.member.register({
  username: 'newuser',
  emailAddress: 'newuser@example.com',
  password: 'securepassword123',
  acceptTermsOfUse: 'true'
});

if (status === 201) {
  console.log('Account created:', data.id);
}
```

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

### Request Authentication Token

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Request an authentication token using a user's Letterboxd username and password. This is the first step in user authentication.

```javascript
const { status, data } = await client.auth.requestAuthToken(username, password);
```

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

### Me API

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Methods for managing the authenticated user's account.

```APIDOC
## Me API

### Description
Methods for managing the authenticated member's profile and account settings.

### Methods
- **deactivate()**: Deactivate account.
- **deregisterPushNotifications()**: Deregister a device so it no longer receives push notifications.
- **get()**: Get details about the authenticated member.
- **registerPushNotifications()**: Register a device so it can receive push notifications.
- **update()**: Update the profile settings for the authenticated member.
- **validationRequest()**: Request a validation link via email.
```

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

### POST /members/register

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Create a new Letterboxd account.

```APIDOC
## POST /members/register

### Description
Create a new Letterboxd account.

### Method
POST

### Parameters
#### Request Body
- **username** (string) - Required
- **emailAddress** (string) - Required
- **password** (string) - Required
- **acceptTermsOfUse** (string) - Required
```

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

### Check Username Availability

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Verify if a specific username is available for registration.

```typescript
const { status, data } = await client.auth.usernameCheck('desiredUsername');

if (status === 200) {
  console.log('Username availability:', data.result);
  // Returns: 'Available', 'NotAvailable', 'Invalid', 'TooShort', or 'TooLong'
}
```

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

### Generate Login Token

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Generate a single-use token for signing a member into the Letterboxd website. Requires an authenticated client.

```typescript
const authenticatedClient = new Client('api-key', 'api-secret', 'access-token');

const { status, data } = await authenticatedClient.auth.getLoginToken();

if (status === 200) {
  const websiteUrl = `https://letterboxd.com/?urt=${data.token}`;
  console.log('Login URL:', websiteUrl);
}
```

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

### Lists API

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Methods for managing and retrieving user-created lists.

```APIDOC
## Lists API

### Description
Methods for creating, updating, and retrieving information about film lists.

### Methods
- **all()**: A cursored window over a list of lists.
- **create()**: Create a list.
- **createComment()**: Create a comment on a list.
- **delete(id)**: Delete a list by ID.
- **get(id)**: Get details of a list by ID.
- **getComments(id)**: A cursored window over the comments for a list.
- **getEntries(id)**: Get entries for a list by ID.
- **getRelationship(id)**: Get details of the authenticated member's relationship with a list by ID.
- **report(id)**: Report a list by ID.
- **statistics(id)**: Get statistical data about a list by ID.
- **topics()**: Get a list of featured topics/lists.
- **update(id)**: Update a list by ID.
- **updateLists()**: Add one or more films to one or more lists.
- **updateRelationship(id)**: Update the authenticated member's relationship with a list by ID.
```

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

### Search API

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

The main entry point for searching content on Letterboxd. Refer to the official Letterboxd API documentation for detailed parameter information.

```APIDOC
## Search

### Description
Provides the main entry point for searching Letterboxd.

### Method
Various (details depend on implementation)

### Endpoint
`/search` (conceptual, actual endpoint may vary based on library usage)

### Parameters
Refer to the Letterboxd API documentation for specific search parameters.

### Request Example
```json
{
  "query": "example search term"
}
```

### Response
Details of search results (structure depends on query).
```

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

### POST /auth/token

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Authenticate a user with their Letterboxd credentials to obtain an access token.

```APIDOC
## POST /auth/token

### Description
Authenticate a user with their Letterboxd credentials to obtain an access token for subsequent authenticated requests.

### Method
POST

### Request Body
- **username** (string) - Required - User's Letterboxd username
- **password** (string) - Required - User's Letterboxd password

### Response
#### Success Response (200)
- **access_token** (string) - The access token for authenticated requests
- **refresh_token** (string) - The refresh token
- **expires_in** (number) - Token expiration time in seconds
```

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

### Retrieve Featured List Topics

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Fetch featured list topics that can be used for browsing. The response includes topic names and lists within each topic.

```typescript
const { status, data } = await client.list.topics();

if (status === 200) {
  data.items.forEach(topic => {
    console.log(`Topic: ${topic.name}`);
    topic.items.forEach(list => {
      console.log(`  - ${list.name}`);
    });
  });
}
```

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

### User Authentication

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Authenticate a user by providing their Letterboxd username and password to request an authentication token.

```APIDOC
### User Authentication

To authenticate a user you will need their Letterboxd credentials (`username` + `password`), which you will supply to `client.auth.requestAuthToken` like so:

```js
const { status, data } = await client.auth.requestAuthToken(username, password);
```

If successful you will receive back an `AccessToken` response that will contain the users `acessToken` that you can then pass back into the main `Client` instance in order to authenticate all API requests as that user.
```

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

### POST /logEntry/comments

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Add a comment to a review. Requires authentication.

```APIDOC
## POST /logEntry/comments

### Description
Add a comment to a review. Requires authentication.

### Method
POST

### Parameters
#### Path Parameters
- **logEntryId** (string) - Required - The ID of the review.

#### Request Body
- **comment** (string) - Required - The comment text.
```

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

### PUT /me

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Update the authenticated member's profile settings.

```APIDOC
## PUT /me

### Description
Update the authenticated member's profile settings. Requires authentication.

### Method
PUT

### Parameters
#### Request Body
- **bio** (string) - Optional
- **location** (string) - Optional
- **website** (string) - Optional
- **favoriteFilms** (array) - Optional
- **emailComments** (boolean) - Optional
- **emailNews** (boolean) - Optional
- **privateAccount** (boolean) - Optional
```

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

### Retrieve Films

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Fetch a paginated list of films with optional filtering and sorting parameters.

```typescript
const { status, data } = await client.film.all({
  perPage: 20,
  decade: 1990,
  genre: 'action',
  sort: 'FilmPopularityThisWeek',
  where: 'Released'
});

if (status === 200) {
  data.items.forEach(film => {
    console.log(`${film.name} (${film.releaseYear})`);
    console.log(`Directors: ${film.directors.map(d => d.name).join(', ')}`);
  });

  // Use cursor for pagination
  if (data.next) {
    const nextPage = await client.film.all({ cursor: data.next });
  }
}
```

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

### Register Push Notifications

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Register a device for push notifications. Requires authentication and device details like ID, name, and token.

```typescript
const { status } = await authenticatedClient.me.registerPushNotifications({
  deviceId: 'unique-device-id',
  deviceName: 'iPhone 15',
  token: 'firebase-token'
});

if (status === 204) {
  console.log('Device registered for push notifications');
}
```

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

### Story API

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Methods for interacting with stories on Letterboxd, including retrieving all stories and fetching details for a specific story.

```APIDOC
## Stories

### Description
Provides methods to interact with stories on Letterboxd.

### Methods

#### `client.story.all()`

##### Description
A cursored window over a list of stories.

##### Method
GET (assumed)

##### Endpoint
`/stories` (conceptual)

#### `client.story.get(storyId)`

##### Description
Get details of a story by its ID.

##### Method
GET (assumed)

##### Endpoint
`/stories/{storyId}` (conceptual)

##### Parameters
*   **storyId** (string) - Required - The unique identifier of the story.
```

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

### List Management API

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Endpoints for creating, updating, and deleting user-created lists.

```APIDOC
## POST /api/lists

### Description
Create a new list. Requires authentication.

### Method
POST

### Endpoint
/api/lists

### Parameters
#### Request Body
- **name** (string) - Required - The name of the list.
- **description** (string) - Optional - A description for the list.
- **ranked** (boolean) - Optional - Whether the list is ranked.
- **published** (boolean) - Optional - Whether the list is published.
- **entries** (array) - Optional - An array of initial entries for the list.
  - **film** (string) - Required - The ID of the film.
  - **rank** (number) - Optional - The rank of the film in the list.
  - **notes** (string) - Optional - Notes associated with the film entry.
- **tags** (array) - Optional - An array of tags for the list.

### Request Example
```json
{
  "name": "My Favorite Sci-Fi Films",
  "description": "A collection of the best science fiction movies",
  "ranked": true,
  "published": true,
  "entries": [
    { "film": "filmId1", "rank": 1, "notes": "An absolute masterpiece" },
    { "film": "filmId2", "rank": 2 },
    { "film": "filmId3", "rank": 3 }
  ],
  "tags": ["sci-fi", "favorites"]
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created list information.
  - **id** (string) - The ID of the newly created list.

#### Response Example
```json
{
  "data": {
    "id": "newListId"
  }
}
```

## PUT /api/lists/{listId}

### Description
Update an existing list. Requires authentication.

### Method
PUT

### Endpoint
/api/lists/{listId}

### Parameters
#### Path Parameters
- **listId** (string) - Required - The ID of the list to update.

#### Request Body
- **name** (string) - Optional - The updated name of the list.
- **description** (string) - Optional - The updated description for the list.
- **entries** (array) - Optional - An array of actions to modify list entries.
  - **action** (string) - Required - The action to perform (ADD, DELETE, UPDATE).
  - **film** (string) - Required if action is ADD - The ID of the film to add.
  - **position** (number) - Required if action is DELETE or UPDATE - The position of the entry to modify.
  - **notes** (string) - Optional if action is UPDATE - Updated notes for the entry.

### Request Example
```json
{
  "name": "Updated List Name",
  "description": "New description",
  "entries": [
    { "action": "ADD", "film": "newFilmId", "rank": 1 },
    { "action": "DELETE", "position": 5 },
    { "action": "UPDATE", "position": 2, "notes": "Updated notes" }
  ]
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the updated list information (structure may vary).

#### Response Example
```json
{
  "data": { ... }
}
```

## DELETE /api/lists/{listId}

### Description
Delete a list. Requires authentication.

### Method
DELETE

### Endpoint
/api/lists/{listId}

### Parameters
#### Path Parameters
- **listId** (string) - Required - The ID of the list to delete.

### Response
#### Success Response (204)
No content is returned upon successful deletion.

#### Response Example
(No content)

```

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

### Manage Lists

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Retrieve public lists, specific list details, or entries within a list.

```typescript
const { status, data } = await client.list.all({
  sort: 'ListPopularityThisWeek',
  perPage: 10
});

if (status === 200) {
  data.items.forEach(list => {
    console.log(`${list.name} by ${list.owner.displayName}`);
    console.log(`Films: ${list.filmCount}, Ranked: ${list.ranked}`);
  });
}
```

```typescript
const { status, data } = await client.list.get('listId');

if (status === 200) {
  console.log('Name:', data.name);
  console.log('Description:', data.description);
  console.log('Owner:', data.owner.displayName);
  console.log('Film Count:', data.filmCount);
  console.log('Ranked:', data.ranked);
  console.log('Published:', data.published);
}
```

```typescript
const { status, data } = await client.list.getEntries('listId', {
  perPage: 50,
  sort: 'ListRanking'
});

if (status === 200) {
  data.items.forEach(entry => {
    console.log(`#${entry.rank}: ${entry.film.name}`);
    if (entry.notes) {
      console.log(`Notes: ${entry.notes}`);
    }
  });
}
```

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

### Create a New Log Entry

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Create a new diary entry or review for a film. Requires authentication. You can include rating, like status, diary details (like watch date), and review text.

```typescript
const { status, data } = await authenticatedClient.logEntry.create({
  filmId: 'ljDs',
  rating: 4.5,
  like: true,
  diaryDetails: {
    diaryDate: '2024-01-15',
    rewatch: false
  },
  review: {
    text: 'An incredible film with stunning visuals and a compelling story.',
    containsSpoilers: false
  },
  tags: ['masterpiece', 'must-watch']
});

if (status === 201) {
  console.log('Log entry created:', data.id);
}
```

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

### Auth API Endpoints

Source: https://github.com/erunion/letterboxd-client/blob/main/README.md

Methods available for authentication and account management.

```APIDOC
### Auth

The following methods are available on the `client.auth.*` namespace:

<!-- prettier-ignore-start -->
| Method | Description |
| :--- | :--- |
| `#forgottenPasswordRequest()` | Request a link via email to reset the password for a member's account. |
| `#getLoginToken()`* | Generate a single-use token for the current member, which can be used to sign the member into the Letterboxd website by passing it as the value of the `urt` query parameter. |
| `#requestAuthToken()` | Use a member's credentials to sign in and receive an authentication token. |
| `#revokeAuth()`* | Revoke a users' access token. |
| `#usernameCheck()` | Check if a username is available to register. |
<!-- prettier-ignore-end -->
```

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

### List Statistics and Topics API

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Endpoints for retrieving list statistics and featured topics.

```APIDOC
## GET /api/lists/{listId}/statistics

### Description
Retrieve statistics for a list.

### Method
GET

### Endpoint
/api/lists/{listId}/statistics

### Parameters
#### Path Parameters
- **listId** (string) - Required - The ID of the list to get statistics for.

### Response
#### Success Response (204)
- **counts** (object) - Contains various counts related to the list.
  - **likes** (number) - The number of likes the list has.
  - **comments** (number) - The number of comments the list has.

#### Response Example
```json
{
  "counts": {
    "likes": 150,
    "comments": 25
  }
}
```

## GET /api/lists/topics

### Description
Retrieve featured list topics for browsing.

### Method
GET

### Endpoint
/api/lists/topics

### Response
#### Success Response (200)
- **items** (array) - An array of featured topics.
  - **name** (string) - The name of the topic.
  - **items** (array) - An array of lists within this topic.
    - **name** (string) - The name of the list.

#### Response Example
```json
{
  "items": [
    {
      "name": "Genre",
      "items": [
        { "name": "Horror" },
        { "name": "Comedy" }
      ]
    }
  ]
}
```
```

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

### Error Handling - Missing Access Token

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Handles `MissingAccessTokenError` when attempting to call authenticated endpoints without a valid access token. Requires importing the specific error type.

```typescript
import Client from 'letterboxd-client';
import { MissingAccessTokenError } from 'letterboxd-client/lib/errors';

const client = new Client('api-key', 'api-secret');

try {
  await client.me.get();
} catch (error) {
  if (error instanceof MissingAccessTokenError) {
    console.error('Authentication required. Please provide an access token.');
  }
}
```

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

### Request Password Reset

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Send a password reset link to a member's email address.

```typescript
const { status } = await client.auth.forgottenPasswordRequest({
  emailAddress: 'user@example.com'
});

if (status === 204) {
  console.log('Password reset email sent');
}
```

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

### Lists API

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Endpoints for retrieving and managing public lists.

```APIDOC
## Get All Lists

### Description
Retrieve a paginated list of public lists.

### Method
GET

### Endpoint
/lists

### Parameters
#### Query Parameters
- **sort** (string) - Optional - Sorting order (e.g., 'ListPopularityThisWeek', 'DateCreated').
- **perPage** (integer) - Optional - Number of results per page (default: 20).

### Response
#### Success Response (200)
- **items** (array) - An array of list objects.
  - **name** (string) - The name of the list.
  - **owner** (object) - Information about the list owner.
    - **displayName** (string) - The display name of the owner.
  - **filmCount** (integer) - The number of films in the list.
  - **ranked** (boolean) - Whether the list is ranked.

### Response Example
```json
{
  "items": [
    {
      "name": "My Favorite Sci-Fi Films",
      "owner": {
        "displayName": "Alice"
      },
      "filmCount": 50,
      "ranked": true
    }
  ]
}
```
```

```APIDOC
## Get List by ID

### Description
Retrieve detailed information about a specific list.

### Method
GET

### Endpoint
/list/{listId}

### Parameters
#### Path Parameters
- **listId** (string) - Required - The ID of the list.

### Response
#### Success Response (200)
- **name** (string) - The name of the list.
- **description** (string) - The description of the list.
- **owner** (object) - Information about the list owner.
  - **displayName** (string) - The display name of the owner.
- **filmCount** (integer) - The number of films in the list.
- **ranked** (boolean) - Whether the list is ranked.
- **published** (boolean) - Whether the list is published.

### Response Example
```json
{
  "name": "Classic Horror Movies",
  "description": "A collection of essential horror films.",
  "owner": {
    "displayName": "Bob"
  },
  "filmCount": 100,
  "ranked": true,
  "published": true
}
```
```

```APIDOC
## Get List Entries

### Description
Retrieve the films in a list with pagination support.

### Method
GET

### Endpoint
/list/{listId}/entries

### Parameters
#### Path Parameters
- **listId** (string) - Required - The ID of the list.

#### Query Parameters
- **perPage** (integer) - Optional - Number of results per page (default: 20).
- **sort** (string) - Optional - Sorting order (e.g., 'ListRanking', 'DateAdded').

### Response
#### Success Response (200)
- **items** (array) - An array of list entry objects.
  - **rank** (integer) - The rank of the film in the list.
  - **film** (object) - Details of the film.
    - **name** (string) - The name of the film.
  - **notes** (string) - Optional - User-added notes for this film in the list.

### Response Example
```json
{
  "items": [
    {
      "rank": 1,
      "film": {
        "name": "Psycho"
      },
      "notes": "A groundbreaking thriller."
    },
    {
      "rank": 2,
      "film": {
        "name": "The Shining"
      }
    }
  ]
}
```
```

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

### Request Authentication Token

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Authenticate a user with their credentials to obtain an access token for subsequent requests.

```typescript
import Client from 'letterboxd-client';

const client = new Client('your-api-key', 'your-api-secret');

const { status, data } = await client.auth.requestAuthToken('username', 'password');

if (status === 200) {
  console.log('Access Token:', data.access_token);
  console.log('Refresh Token:', data.refresh_token);
  console.log('Expires In:', data.expires_in, 'seconds');

  // Create authenticated client with the token
  const authClient = new Client('your-api-key', 'your-api-secret', data.access_token);
}
```

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

### List Comments API

Source: https://context7.com/erunion/letterboxd-client/llms.txt

Endpoints for retrieving and creating comments on user lists.

```APIDOC
## GET /api/lists/{listId}/comments

### Description
Retrieve comments on a list.

### Method
GET

### Endpoint
/api/lists/{listId}/comments

### Parameters
#### Path Parameters
- **listId** (string) - Required - The ID of the list to retrieve comments from.

#### Query Parameters
- **sort** (string) - Optional - The sorting order for comments (e.g., 'DateLatestFirst').
- **perPage** (number) - Optional - The number of comments to return per page.

### Response
#### Success Response (200)
- **items** (array) - An array of comment objects.
  - **member** (object) - Information about the member who posted the comment.
    - **displayName** (string) - The display name of the member.
  - **comment** (string) - The content of the comment.
  - **whenCreated** (string) - The timestamp when the comment was created.

#### Response Example
```json
{
  "items": [
    {
      "member": { "displayName": "User1" },
      "comment": "Great list!",
      "whenCreated": "2023-10-27T10:00:00Z"
    }
  ]
}
```

## POST /api/lists/{listId}/comments

### Description
Add a comment to a list. Requires authentication.

### Method
POST

### Endpoint
/api/lists/{listId}/comments

### Parameters
#### Path Parameters
- **listId** (string) - Required - The ID of the list to comment on.

#### Request Body
- **comment** (string) - Required - The content of the comment.

### Request Example
```json
{
  "comment": "Great list! I would add a few more classics though."
}
```

### Response
#### Success Response (201)
- **id** (string) - The ID of the newly created comment.

#### Response Example
```json
{
  "id": "newCommentId"
}
```
```