https://github.com/michaelfromyeg/betterboxd
Useful functions to interact with Letterboxd data.
https://github.com/michaelfromyeg/betterboxd
Last synced: 3 months ago
JSON representation
Useful functions to interact with Letterboxd data.
- Host: GitHub
- URL: https://github.com/michaelfromyeg/betterboxd
- Owner: michaelfromyeg
- Created: 2024-09-13T17:21:47.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-02-17T21:00:32.000Z (5 months ago)
- Last Synced: 2025-03-27T18:10:01.959Z (3 months ago)
- Language: TypeScript
- Size: 341 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Betterboxd
A small `npm` package to help with fetching Letterboxd data, better. Intended to be used alongside the Letterboxd API, with an even simpler interface and no attempt at authentication.
NOTE: uses `/bin/google-chrome` on local (i.e., assumes you're on something Linux-like), or `playwright-aws-lambda` in a deployed environment. So, this limits where you can deploy code that uses this package.
## Methods
### `fetchLetterboxdFilms(username: string, maxPages: number = 5): Promise<{ films: Film[]; totalPages: number; fetchedPages: number }>`
Fetches a user's Letterboxd films across multiple pages.
- **Parameters**:
- `username`: Letterboxd username.
- `maxPages`: Maximum number of pages to fetch (default: 5).
- **Returns**: A Promise that resolves to an object containing:
- `films`: Array of films fetched.
- `totalPages`: Total number of pages available.
- `fetchedPages`: Number of pages fetched.
### `fetchLetterboxdFilmsByPage(username: string, page: number = 1): Promise<{ films: Film[]; totalPages: number }>`
Fetches a single page of a user's Letterboxd films.
- **Parameters**:
- `username`: Letterboxd username.
- `page`: Page number to fetch (default: 1).
- **Returns**: A Promise that resolves to an object containing:
- `films`: Array of films for the page.
- `totalPages`: Total number of pages available.
### `fetchLetterboxdDiary(username: string, maxPages: number = 5): Promise<{ films: Film[]; totalPages: number; fetchedPages: number }>`
Fetches a user's Letterboxd diary entries across multiple pages.
- **Parameters**:
- `username`: Letterboxd username.
- `maxPages`: Maximum number of pages to fetch (default: 5).
- **Returns**: A Promise that resolves to an object containing:
- `films`: Array of diary entries fetched.
- `totalPages`: Total number of pages available.
- `fetchedPages`: Number of pages fetched.
### `fetchLetterboxdDiaryEntriesByPage(username: string, page: number = 1): Promise<{ films: Film[]; totalPages: number }>`
Fetches a single page of a user's Letterboxd diary entries.
- **Parameters**:
- `username`: Letterboxd username.
- `page`: Page number to fetch (default: 1).
- **Returns**: A Promise that resolves to an object containing:
- `films`: Array of diary entries for the page.
- `totalPages`: Total number of pages available.
### `fetchLetterboxdReviews(username: string, maxPages: number = 5): Promise<{ films: Film[]; totalPages: number; fetchedPages: number }>`
Fetches a user's Letterboxd reviews across multiple pages.
- **Parameters**:
- `username`: Letterboxd username.
- `maxPages`: Maximum number of pages to fetch (default: 5).
- **Returns**: A Promise that resolves to an object containing:
- `films`: Array of reviews fetched.
- `totalPages`: Total number of pages available.
- `fetchedPages`: Number of pages fetched.
### `fetchLetterboxdReviewsByPage(username: string, page: number = 1): Promise<{ films: Film[]; totalPages: number }>`
Fetches a single page of a user's Letterboxd reviews.
- **Parameters**:
- `username`: Letterboxd username.
- `page`: Page number to fetch (default: 1).
- **Returns**: A Promise that resolves to an object containing:
- `films`: Array of reviews for the page.
- `totalPages`: Total number of pages available.
### `addTmdbPosterUrls(films: Film[], apiKey?: string): Promise`
Adds TMDB poster URLs to the provided films by querying the TMDB API.
- **Parameters**:
- `films`: Array of film objects to enrich with TMDB poster URLs.
- `apiKey`: (Optional) TMDB API key. If not provided, it will use the API key set in environment variables.
- **Returns**: A Promise that resolves when TMDB data has been added.
## Types
### `Film`
Represents a film with the following structure:
- `id`: Film ID.
- `name`: Film name.
- `year`: Release year.
- `posterUrl`: Poster URL from Letterboxd.
- `rating`: Film rating.
- (optional) `datetime`: Date associated with the diary entry or review.
- (optional) `action`: Action such as "Watched", "Rewatched".
- (optional) `reviewText`: Text of the review.
- (optional) `likesCount`: Number of likes for the review.
- (optional) `tmdbPosterUrl`: Poster URL from TMDB.