### Install Project Dependencies

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/README.md

Install all necessary Node.js dependencies for the Hardcover project.

```bash
npm install
```

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

### Start Development Server

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/README.md

Run this command to start the local development server for the Hardcover documentation.

```bash
npm run dev
```

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

### UserBookActivity Example Payloads

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/it/api/GraphQL/Schemas/Activities.mdx

Examples of payloads for UserBookActivity events, illustrating different user interactions with books such as rating, starting to read, or adding a review.

```APIDOC
## UserBookActivity Example Payloads

### User added a rating to a book

```json
{
  "id": 3,
  "event": "UserBookActivity",
  "data": {
    "userBook": {
      "rating": "4.5",
      "review": null,
      "statusId": 3,
      "readingFormatId": 1,
      "reviewHasSpoilers": false
    }
  },
  "book_id": 10257,
  "object_type": "Activity"
}
```

### User started reading a book

```json
{
  "id": 4,
  "event": "UserBookActivity",
  "data": {
    "userBook": {
      "rating": null,
      "review": "",
      "statusId": 1,
      "readingFormatId": 1,
      "reviewHasSpoilers": false
    }
  },
  "book_id": 10257,
  "object_type": "Activity"
}
```

### User added a review to a book

```json
{
    "id": 1234,
    "event": "UserBookActivity",
    "data": {
      "userBook": {
        "rating": "4.5",
        "review": "This is a great book!",
        "statusId": 3,
        "readingFormatId": 1,
        "reviewHasSpoilers": false
      }
    },
    "book_id": 10257,
    "object_type": "Activity"
}
```
```

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

### User Started Reading a Book Payload

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Activities.mdx

Example payload for a 'UserBookActivity' event where a user starts reading a book.

```APIDOC
#### User Started Reading a Book
<Code
    code={`
      {
        "id": 4,
        "event": "UserBookActivity",
        "data": {
          "userBook": {
            "rating": null,
            "review": "",
            "statusId": 1,
            "readingFormatId": 1,
            "reviewHasSpoilers": false
          }
        },
        "book_id": 10257,
        "object_type": "Activity"
      }
`}
    lang="graphql"
    title="User Started Reading"
/>
```

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

### Showcase Entry Example with Screenshots

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/specs/showcase-feature.md

Example of a showcase entry in YAML format, including screenshots. This format is used for content collection in Astro.

```yaml
# src/content/showcase/marian-the-librarian.yaml
name: "Marian the Librarian"
slug: "marian-the-librarian"
summary: "Chrome extension for quick Hardcover access and book lookups"
description: |
  Marian the Librarian brings Hardcover to your browser. Features include:

  - Quick search from any tab
  - One-click "Want to Read" additions
  - Current reading progress in toolbar
  - Goodreads page integration

author:
  name: "Jane Doe"
  github: "janedoe"
  hardcover: "janedoe"

links:
  - label: "Chrome Web Store"
    url: "https://chromewebstore.google.com/detail/marian-the-librarian/gpnkkkbefalodcjhgafioibknoingann"
    type: "store"
  - label: "GitHub"
    url: "https://github.com/janedoe/marian"
    type: "github"

categories:
  - "Browser Extension"
  - "Productivity"

screenshots:
  - src: "./marian/popup.png"
    alt: "Extension popup showing current reads"
  - src: "./marian/search.png"
    alt: "Search results overlay"

tags:
  - "chrome"
  - "search"
  - "open-source"

dateAdded: 2025-01-15
dateUpdated: 2025-03-20
featured: true
```

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

### User Started Reading Payload Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/it/api/GraphQL/Schemas/Activities.mdx

This payload indicates a user has started reading a book. The userBook object within the data field shows the statusId as 1, signifying the start of reading.

```graphql
{
        "id": 4,
        "event": "UserBookActivity",
        "data": {
          "userBook": {
            "rating": null,
            "review": "",
            "statusId": 1,
            "readingFormatId": 1,
            "reviewHasSpoilers": false
          }
        },
        "book_id": 10257,
        "object_type": "Activity"
      }
```

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

### Showcase Entry Example without Screenshots

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/specs/showcase-feature.md

Example of a showcase entry in YAML format, without screenshots. This format is used for content collection in Astro.

```yaml
# src/content/showcase/hardcover-trmnl.yaml
name: "Hardcover TRMNL"
slug: "hardcover-trmnl"
summary: "Display your reading stats on TRMNL e-ink devices"
description: |
  A TRMNL plugin that shows your Hardcover reading data on e-ink displays.

  Displays:
  - Reading goals and progress
  - Currently reading books
  - Want to read queue
  - Recent activity

author:
  name: "Jacob Tender"
  github: "jacobtender"
  hardcover: "jacobtender"

links:
  - label: "GitHub"
    url: "https://github.com/jacobtender/hardcover_trmnl"
    type: "github"

categories:
  - "E-ink Display"
  - "Widget"

tags:
  - "trmnl"
  - "e-ink"
  - "open-source"

dateAdded: 2025-02-01
dateUpdated: 2025-02-01
featured: false
```

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

### Search Authors

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/Searching.mdx

Get a list of authors matching the query. This example demonstrates searching for authors by name.

```graphql
query BooksByRowling {
    search(
        query: "rowling",
        query_type: "Author",
        per_page: 5,
        page: 1
    ) {
        results
    }
}
```

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

### Edition ID URL Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/LinkingById.mdx

Example of a stable ID URL for an edition. This will redirect to the edition's current slug-based path.

```text
/id/edition/{id}
```

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

### GraphQL Explorer Example Request

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/UpdatingABooksProgress.mdx

This snippet shows an example of a GraphQL query structure that can be used within the GraphQLExplorer component to update a book's progress and dates read. It's a placeholder for actual query details.

```javascript
import GraphQLExplorer from '@/components/GraphQLExplorer/GraphQLExplorer.astro';

## Introduction

This guide will show you how to update a book's progress and dates read.

### Example Request
<GraphQLExplorer query={``} description='' />
```

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

### User ID URL Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/LinkingById.mdx

Example of a stable ID URL for a user. This will redirect to the user's current slug-based path.

```text
/id/user/{id}
```

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

### Book ID URL Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/LinkingById.mdx

Example of a stable ID URL for a book. This will redirect to the book's current slug-based path.

```text
/id/book/{id}
```

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

### Example GraphQL Query

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/Getting-Started.mdx

This is an example GraphQL query to fetch the user's ID and username. It requires an 'Authorization' header with your API token.

```graphql
query {
    me {
        id,
        username
    }
}
```

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

### Publisher ID URL Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/LinkingById.mdx

Example of a stable ID URL for a publisher. This will redirect to the publisher's current slug-based path.

```text
/id/publisher/{id}
```

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

### Get Publisher Details

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Publishers.mdx

Retrieve detailed information about a specific publisher, including their recent editions. This example targets publisher with ID 1.

```graphql
query GetPublisherDetails {
    publishers(where: {id: {_eq: 1}}) {
        id
        name
        slug
        editions_count
        parent_publisher {
            name
        }
        editions(
            limit: 5
            order_by: {release_date: desc}
        ) {
            id
            title
            isbn_13
            release_date
            book {
                title
                contributions {
                    author {
                        name
                    }
                }
            }
        }
    }
}
```

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

### Series ID URL Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/LinkingById.mdx

Example of a stable ID URL for a series. This will redirect to the series' current slug-based path.

```text
/id/series/{id}
```

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

### API Error Response Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/Getting-Started.mdx

This is an example of a generic internal server error response.

```json
{ "error": "An unknown error occurred" }
```

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

### Get Followed Lists

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Lists.mdx

Get all lists that the authenticated user is following, ordered by the creation date of the follow relationship.

```APIDOC
## Query: GetMyFollowedLists

### Description
Retrieves all lists that the currently authenticated user is following, ordered by the creation date of the follow relationship in descending order.

### GraphQL Query
```graphql
query GetMyFollowedLists {
    followed_lists(order_by: {created_at: desc}) {
        id
        created_at
        list {
            id
            name
            description
            books_count
            likes_count
            user {
                username
            }
        }
    }
}
```
```

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

### Author ID URL Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/LinkingById.mdx

Example of a stable ID URL for an author. This will redirect to the author's current slug-based path.

```text
/id/author/{id}
```

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

### Character ID URL Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/LinkingById.mdx

Example of a stable ID URL for a character. This will redirect to the character's current slug-based path.

```text
/id/character/{id}
```

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

### User Book Activity - Started Reading

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Activities.mdx

This payload indicates a user has started reading a book. It captures the status and reading format without a rating or review.

```graphql
{
  "id": 4,
  "event": "UserBookActivity",
  "data": {
    "userBook": {
      "rating": null,
      "review": "",
      "statusId": 1,
      "readingFormatId": 1,
      "reviewHasSpoilers": false
    }
  },
  "book_id": 10257,
  "object_type": "Activity"
}
```

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

### Plurality Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/LinkingById.mdx

Demonstrates that the model portion of the URL accepts both singular and plural forms, functioning identically.

```text
https://hardcover.app/id/book/192946
```

```text
https://hardcover.app/id/books/192946
```

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

### Get My User Information

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Users.mdx

Fetches all available details for the currently authenticated user.

```graphql
query {
      me {
            id
            username
            birthdate
            books_count
            flair
            followers_count
            followed_users_count
            location
            name
            pro
            pronoun_personal
            pronoun_possessive
            sign_in_count
      }
}
```

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

### Build Production Site

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/DEVELOPERS.md

Build the production-ready static site for the Hardcover documentation. The output will be in the ./dist/ directory.

```bash
npm run build
```

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

### Preview Production Build

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/DEVELOPERS.md

Preview the production build of the Hardcover documentation site locally before deploying.

```bash
npm run preview
```

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

### Search Authors

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/Searching.mdx

Get a list of authors matching the search query. This example demonstrates searching for authors by name.

```APIDOC
## Search Authors

### Description
Searches for authors based on the provided query. This example retrieves authors related to 'Rowling'.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Query Parameters
- **query** (String!) - The search term. Defaults to searching for books if not specified.
- **query_type** (String) - The type of content to search for. Options: `author`, `book`, `character`, `list`, `prompt`, `publisher`, `series`, `user`. Case-insensitive. Defaults to `book`.
- **per_page** (Int) - The number of results to return per page. Defaults to 25.
- **page** (Int) - The page number to return. Defaults to 1.
- **sort** (String) - Specifies the sorting criteria for the results.
- **fields** (String) - Specifies which attributes within the `query_type` to include in the search.
- **weights** (String) - A comma-separated list of numbers indicating weights to give each of the `fields` when calculating matches.
- **typos** (String) - A comma-separated list of numbers indicating the typo tolerance for each of the `fields` when calculating matches.

### Request Example
```json
{
  "query": "rowling",
  "query_type": "Author",
  "per_page": 5,
  "page": 1
}
```

### Response
#### Success Response (200)
- **data** (Object) - The main data object.
  - **search** (Object) - The search results.
    - **results** (Array) - An array of search result objects.

#### Response Example
```json
{
  "data": {
    "search": {
      "results": [
        {
          "alternate_names": [
            "Joanne Rowling"
          ],
          "books": [
            "Harry Potter and the Sorcerer's Stone",
            "Harry Potter and the Chamber of Secrets",
            "Harry Potter and the Prisoner of Azkaban",
            "Harry Potter and the Goblet of Fire",
            "Harry Potter and the Order of the Phoenix"
          ],
          "books_count": 65,
          "image": {
            "url": "https://example.com/images/joanne-rowling.jpg",
            "width": 500,
            "height": 750,
            "color": "#a38c7c"
          },
          "name": "J.K. Rowling",
          "name_personal": "Joanne Rowling",
          "series_names": [
            "Harry Potter",
            "The Casual Vacancy",
            "The Cormoran Strike Series"
          ],
          "slug": "j-k-rowling"
        }
      ]
    }
  }
}
```
```

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

### GraphQL Query Builder Usage Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/demos/query-builder-demo.mdx

Shows how to integrate the GraphQLExplorerEnhanced component into Astro documentation pages, including essential props for configuration.

```astro
---
import GraphQLExplorerEnhanced from '@/components/GraphQLExplorer/GraphQLExplorerEnhanced.astro';
---

<GraphQLExplorerEnhanced
  query={`query { ... }`}
  description="Your query description"
  initialQueryType="books"
  defaultMode="advanced"
  showQueryTypeSelector={true}
/>
```

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

### Navigate to Project Directory

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/README.md

Change your current directory to the cloned Hardcover project folder.

```bash
cd hardcover-docs
```

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

### Get Books in a Specific List

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Lists.mdx

Get all books within a specific list, including their details and position. This example uses the NPR Top 100 Science Fiction Fantasy list (ID: 3). The list must be public or owned by the authenticated user.

```APIDOC
## Query: GetListBooks

### Description
Retrieves all books within a specific list, along with their details and position in the list. Requires the list to be public or owned by the authenticated user.

### GraphQL Query
```graphql
query GetListBooks {
    lists(where: {id: {_eq: 3}}) {
        name
        description
        list_books {
            book {
                id
                title
                contributions {
                    author {
                        name
                    }
                }
                rating
                pages
            }
            position
            date_added
        }
    }
}
```
```

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

### GraphQL Query: Get Books in a Specific List

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Lists.mdx

Retrieve all books within a specific list, including their details and position. The list must be public or owned by the authenticated user. This example uses NPR Top 100 Science Fiction Fantasy list (ID: 3).

```graphql
query GetListBooks {
    lists(where: {id: {_eq: 3}}) {
        name
        description
        list_books {
            book {
                id
                title
                contributions {
                    author {
                        name
                    }
                }
                rating
                pages
            }
            position
            date_added
        }
    }
}
```

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

### API Error Response Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/Getting-Started.mdx

This is an example of a rate limiting error response.

```json
{ "error": "Throttled" }
```

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

### Run Individual Schema Graph Addition Script

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/scripts/schema-tools/README.md

Adds SchemaGraph visualizations to new documentation pages. This script is run from the project root.

```bash
node scripts/schema-tools/add-schema-graphs.js
```

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

### Run Project Unit Tests

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/DEVELOPERS.md

Execute the unit tests for the Hardcover project using Vitest.

```bash
npx vitest
```

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

### API Error Response Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/Getting-Started.mdx

This is an example of an error response body for unauthorized access.

```json
{ "error": "Message describing the error" }
```

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

### Astro Project Commands

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/contributing/API-Docs.mdx

Lists common commands for managing and building an Astro project, including installation, development, building, and previewing.

```bash
npm install
```

```bash
npm run dev
```

```bash
npm run build
```

```bash
npm run preview
```

```bash
npm run astro ...
```

```bash
npm run astro -- --help
```

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

### Get Help with Astro CLI

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/DEVELOPERS.md

Display help information for the Astro CLI, listing available commands and options.

```bash
npm run astro -- --help
```

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

### API Error Response Example

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/Getting-Started.mdx

This is an example of an error response body for an invalid or expired token.

```json
{ "error": "Unable to verify token" }
```

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

### Showcase Submission Instructions Template

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/specs/showcase-feature.md

Markdown template for contributors to submit their projects to the Hardcover showcase. Includes instructions and a YAML structure.

```markdown
## Add Your Project

Built something cool with the Hardcover API? We'd love to feature it!

### How to Submit

1. Fork the [docs repository](https://github.com/hardcover/docs)
2. Create a new file: `src/content/showcase/your-project-slug.yaml`
3. Use the template below
4. Add any screenshots to `src/assets/showcase/your-project-slug/`
5. Open a Pull Request
6. Tag `@revelry` in the [Hardcover Discord](https://discord.gg/hardcover) to let us know!

### Template

```yaml
name: "Your Project Name"
slug: "your-project-slug"
summary: "One-line description (under 100 characters)"
description: |
  Longer description of your project. Markdown supported.

  - Feature 1
  - Feature 2

author:
  name: "Your Name"
  github: "your-github-username"      # optional
  hardcover: "your-hardcover-username"  # optional

links:
  - label: "GitHub"
    url: "https://github.com/..."
    type: "github"
  - label: "Website"
    url: "https://..."
    type: "website"

categories:
  - "Choose from: Browser Extension, Mobile App, Web App, CLI Tool, E-ink Display, Home Automation, Desktop App, Widget, Integration, Automation, Other"

dateAdded: 2025-01-15  # Today's date
dateUpdated: 2025-01-15

```

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

### Users Query Starting in Static Mode

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/demos/query-builder-demo.mdx

Initializes the query builder in Static mode, with the option to switch to Advanced mode for query modification. Fetches user data with a limit.

```astro
<GraphQLExplorerEnhanced
  query={`query {
  users(limit: 5) {
    id
    name
    username
  }
}`}
  description="Query to fetch users"
  initialQueryType="users"
  defaultMode="static"
  canToggleMode={true}
/>
```

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

### Create New Book

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Books.mdx

Creates a new book entry with provided title, pages, release date, and description.

```graphql
mutation {
      createBook(input: {
            title: "My First Book",
            pages: 300,
            release_date: "2024-09-07"
            description: "This is my first book."
        }) {
        book {
              title
              pages
              release_date
              description
        }
      }
}

```

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

### Clone Hardcover Repository

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/README.md

Use this command to clone the Hardcover documentation repository to your local machine.

```bash
git clone https://github.com/hardcoverapp/hardcover-docs.git
```

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

### Run Full Documentation Update Pipeline

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/scripts/schema-tools/README.md

Executes the complete documentation update pipeline. Requires a bearer token for authentication, which can be provided as a CLI argument, via the HARDCOVER_API_TOKEN environment variable, or in a .env file.

```bash
./scripts/schema-tools/update-all.sh YOUR_BEARER_TOKEN
```

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

### File Tree Structure

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/contributing/API-Docs.mdx

Illustrates the directory structure of the Starlight documentation project, showing where different types of files are located.

```tree
- public favicons and other static assets
    - ...
    - src
        - assets Images for doc pages
            - ...
        - components Custom components
            - GraphQLExplorer
                - GraphQLExplorer.astro Main file of the GraphQL Explorer component
                - ...
            - ui shadcn/ui components
                - ...
            - ...
        - content
            - docs mdx files that generates doc pages
                - api
                    - GraphQL
                        - Schema Data schemas
                            - ...
                    - ...
                    - guides Guides and tutorials
                        - ...
                    - getting-started.mdx
                    - ...
                - contributing Contributing guidelines
                    - ...
                - it Italian translations
                    - ...
                -  librarians Librarian guides
                    - ...
                - ui.json translations for any UI strings
        - layouts Layouts for doc pages
            - documentation.astro Main layout for doc pages
            - ...
    - astro.config.mjs Astro configuration file
    - components.json shadcn/ui components
    - CONTRIBUTING Contributing guidelines
    - DEVELOPERS.md Developer FAQs
    - tailwind.config.mjs Tailwind CSS configuration
    - ...
```

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

### Get Reading Statistics

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/UserBooks.mdx

Use aggregate queries to get statistics about a user's library, such as the total count of books and the average rating.

```APIDOC
## Get Reading Statistics

### Description
Use aggregate queries to get statistics about a user's library.

### Method
GraphQL Query

### Endpoint
N/A (GraphQL endpoint)

### Parameters
#### Query Parameters
- **where** (object) - Required - Filter criteria for user books. Example: `{user_id: {_eq: ##USER_ID##}}`

### Request Example
```graphql
query ReadingStats {
    user_books_aggregate(
        where: {user_id: {_eq: ##USER_ID##}}
    ) {
        aggregate {
            count
            avg {
                rating
            }
        }
    }
}
```

### Response
#### Success Response
Returns aggregate statistics for the user's library.

#### Response Example
```json
{
  "data": {
    "user_books_aggregate": {
      "aggregate": {
        "count": 150,
        "avg": {
          "rating": 4.2
        }
      }
    }
  }
}
```
```

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

### Showcase Data Schema (YAML)

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/specs/showcase-feature.md

Defines the required and optional fields for a showcase entry in YAML format. Includes project details, author information, links, categories, dates, and media.

```yaml
# Required fields
name: "Project Name"
slug: "project-name"  # URL-safe identifier
summary: "Brief one-line description for card preview"
description: |
  Full markdown description with features, use cases,
  installation notes, etc. Supports formatting.

author:
  name: "Display Name"
  github: "github-username"      # optional
  hardcover: "hardcover-username"  # optional

links:
  - label: "Primary Link"
    url: "https://..."
    type: "website"  # website | github | store | docs | demo

categories:
  - "Browser Extension"  # At least one required

# Dates
dateAdded: 2025-01-15
dateUpdated: 2025-01-15

# Optional fields
screenshots:
  - src: "./images/project-1.png"  # Local or external URL
    alt: "Description of screenshot"
  - src: "https://example.com/image.png"
    alt: "Another screenshot"

tags:
  - "open-source"
  - "tracking"

featured: false  # Defaults to false

```

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

### Get List Statistics

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Lists.mdx

Use aggregate queries to get statistics about public lists, such as the total count and average/maximum values for book counts and likes.

```APIDOC
## Query: GetListStats

### Description
Retrieves aggregate statistics for public lists, including count, average, and maximum values for books_count and likes_count.

### GraphQL Query
```graphql
query GetListStats {
    lists_aggregate(where: {public: {_eq: true}}) {
        aggregate {
            count
            avg {
                books_count
                likes_count
            }
            max {
                books_count
                likes_count
            }
        }
    }
}
```
```

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

### Example Frontmatter for Markdown Files

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/CONTRIBUTING.md

This frontmatter is required for all Markdown files and includes metadata such as title, description, category, lastUpdated, and layout.

```markdown
---
title: Getting Started with the API
description: Get started with the Hardcover GraphQL API.
category: guide
lastUpdated: 2025-02-01 17:03:00
layout: ../../layouts/documentation.astro
---
```

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

### Run Project Tests

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/contributing/API-Docs.mdx

Commands to run unit tests for the project using Vitest, with an option to enable code coverage.

```bash
npx vitest
```

```bash
npx vitest --coverage.enabled true
```

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

### Get Lists by a Specific User

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Lists.mdx

Get all lists created by a specific user, ordered by their last update time. Replace ##USER_ID## with the actual user ID.

```APIDOC
## Query: GetUserLists

### Description
Retrieves all lists created by a specific user, ordered by the last updated timestamp in descending order.

### GraphQL Query
```graphql
query GetUserLists {
    lists(
        where: {user_id: {_eq: ##USER_ID##}},
        order_by: {updated_at: desc}
    ) {
        id
        name
        description
        books_count
        public
        created_at
        updated_at
    }
}
```
```

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

### Run Unit Tests with Code Coverage

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/DEVELOPERS.md

Execute the unit tests for the Hardcover project and generate a code coverage report.

```bash
npx vitest --coverage.enabled true
```

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

### GraphQL Query: Get Lists by a Specific User

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Lists.mdx

Get all lists created by a specific user, ordered by their last update. Replace ##USER_ID## with the actual user ID.

```graphql
query GetUserLists {
    lists(
        where: {user_id: {_eq: ##USER_ID##}},
        order_by: {updated_at: desc}
    ) {
        id
        name
        description
        books_count
        public
        created_at
        updated_at
    }
}
```

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

### Import GraphQLExplorer Component

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/DEVELOPERS.md

Import the GraphQLExplorer component for use in Astro projects. Ensure the path is correct for your project structure.

```javascript
import GraphQLExplorer from '@/components/GraphQLExplorer/GraphQLExplorer.astro';
```

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

### Books Query in Advanced Mode

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/demos/query-builder-demo.mdx

Starts the query builder in Advanced mode for exploring the 'books' query. Allows basic information retrieval with a limit.

```astro
<GraphQLExplorerEnhanced
  query={`query {
  books(limit: 10) {
    id
    title
    release_year
  }
}`}
  description="Query to fetch books with basic information"
  initialQueryType="books"
  defaultMode="advanced"
  canToggleMode={true}
/>
```

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

### My Information

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Users.mdx

Get information for the current user.

```APIDOC
## My Information

### Description
Retrieves detailed information for the currently authenticated user.

### Method
GraphQL Query

### Query
query {
      me {
            id
            username
            birthdate
            books_count
            flair
            followers_count
            followed_users_count
            location
            name
            pro
            pronoun_personal
            pronoun_possessive
            sign_in_count
      }
}

### Response Example
```json
{
  "data": {
    "me": {
      "id": "string",
      "username": "string",
      "birthdate": "string",
      "books_count": "integer",
      "flair": "string",
      "followers_count": "integer",
      "followed_users_count": "integer",
      "location": "string",
      "name": "string",
      "pro": "boolean",
      "pronoun_personal": "string",
      "pronoun_possessive": "string",
      "sign_in_count": "integer"
    }
  }
}
```
```

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

### Search Characters

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/Searching.mdx

Get a list of characters named Peter.

```APIDOC
## Search Characters

### Description
Get a list of characters named Peter.

### Method
POST

### Endpoint
/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search term.
- **query_type** (string) - Required - The type of entity to search for (e.g., "Character").
- **per_page** (integer) - Optional - The number of results per page.
- **page** (integer) - Optional - The page number.

#### Request Body
(Not specified in source)

### Request Example
```json
{
  "query": "peter",
  "query_type": "Character",
  "per_page": 5,
  "page": 1
}
```

### Response
#### Success Response (200)
- **results** (array) - The search results.

#### Response Example
```json
{
  "results": [
    // ... character objects
  ]
}
```
```

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

### Project File Structure

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/specs/showcase-feature.md

This outlines the directory structure for the Hardcover showcase feature, detailing the location of content files, components, pages, and assets.

```tree
src/
├── content/
│   └── showcase/
│       ├── marian-the-librarian.yaml
│       ├── hardcover-trmnl.yaml
│       └── ...
├── components/
│   └── showcase/
│       ├── ShowcaseGrid.tsx      # Main grid with filtering
│       ├── ShowcaseCard.tsx      # Individual card
│       ├── ShowcaseModal.tsx     # Expanded detail view
│       ├── ShowcaseFilters.tsx   # Category/search controls
│       ├── ImageGallery.tsx      # Screenshot carousel
│       └── AuthorLinks.tsx       # GitHub/HC profile links
├── pages/
│   └── showcase/
│       └── index.astro           # Main showcase page
└── assets/
    └── showcase/
        └── [project-slug]/
            ├── screenshot-1.png
            └── screenshot-2.png
```

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

### Get My Activities

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/it/api/GraphQL/Schemas/Activities.mdx

Retrieves a list of activities performed by the current user.

```APIDOC
## Get My Activities

### Description
This query will return a list of 10 activities that the current user has performed.

### Query
```graphql
{
    activities(where: {user_id: {_eq: ##USER_ID##}}, limit: 10) {
        event
        likes_count
        book_id
        created_at
    }
}
```
```

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

### Search List Books

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/guides/GettingBooksInSeries.mdx

This example query searches for a specific series by name, filters out merged series, and retrieves a clean list of books within that series, excluding merged and partial books.

```graphql
query GetBooksBySeries {
  series(
    where: {
      name: {_eq: "Harry Potter"},
      books_count: {_gt: 0},
      canonical_id: {_is_null: true}
    }
  ) {
    id
    name
    slug
    author {
      name
    }
    books_count
    book_series(
      distinct_on: position
      order_by: [{position: asc}, {book: {users_count: desc}}]
      where: {
          book: {canonical_id: {_is_null: true}, is_partial_book: {_eq: false}},
          compilation: {_eq: false}
      }
    ) {
      position
      book {
        id
        slug
        title
      }
    }
  }
}
```

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

### Find Editions by Publisher

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Editions.mdx

Get recent editions published by a specific publisher.

```APIDOC
## Find Editions by Publisher

### Description
Get recent editions from a specific publisher, ordered by release date.

### Method
GraphQL Query

### Endpoint
N/A (GraphQL)

### Parameters
#### Query Parameters
- **publisher_id** (Int) - Required - The ID of the publisher.
- **limit** (Int) - Optional - The maximum number of editions to return. Defaults to 10.
- **order_by** (Object) - Optional - Specifies the sorting order. Defaults to `release_date: desc`.

### Request Body
```graphql
query GetPublisherEditions($publisherId: Int!, $limit: Int) {
    editions(where: {publisher_id: {_eq: $publisherId}}, order_by: {release_date: desc}, limit: $limit) {
        id
        title
        isbn_13
        release_date
        physical_format
        book {
            title
            rating
            contributions {
                author {
                    name
                }
            }
        }
    }
}
```

### Response
#### Success Response
Returns a list of recent editions from the specified publisher, including edition ID, title, ISBN-13, release date, physical format, and associated book details (title, rating, author).

#### Response Example
```json
{
  "data": {
    "editions": [
      {
        "id": 201,
        "title": "Publisher's Latest",
        "isbn_13": "9781111111111",
        "release_date": "2023-08-01",
        "physical_format": "Hardcover",
        "book": {
          "title": "Book Title X",
          "rating": 4.7,
          "contributions": [
            {
              "author": {
                "name": "Author Z"
              }
            }
          ]
        }
      },
      {
        "id": 202,
        "title": "Another Recent Release",
        "isbn_13": "9782222222222",
        "release_date": "2023-07-15",
        "physical_format": "Paperback",
        "book": {
          "title": "Book Title Y",
          "rating": 4.3,
          "contributions": [
            {
              "author": {
                "name": "Author W"
              }
            }
          ]
        }
      }
    ]
  }
}
```
```

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

### Search users

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/it/api/guides/Searching.mdx

Get a list of users with the name "adam".

```APIDOC
## Search users

### Description
Get a list of users with the name "adam".

### Method
query

### Endpoint
search

### Parameters
#### Query Parameters
- **query** (String) - Required - The search term.
- **query_type** (String) - Required - The type of entity to search for (e.g., "User").
- **per_page** (Int) - Optional - The number of results per page.
- **page** (Int) - Optional - The page number of the results.

### Request Example
```json
{
    "query": "adam",
    "query_type": "User",
    "per_page": 5,
    "page": 1
}
```

### Response
#### Success Response (200)
- **results** (Array) - A list of users matching the search criteria.

### Response Example
```json
{
  "results": [
    // User objects will be listed here
  ]
}
```
```

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

### Get User by Username

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/it/api/GraphQL/Schemas/Users.mdx

Retrieve a user's basic information by their username.

```APIDOC
## Get a User by Username

### Description
Retrieve a user's basic information by their username.

### Query
query {
    users(where: {username: {_eq: "adam"}}, limit: 1) {
        id,
        username
    }
}
```

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

### Create a New Book

Source: https://github.com/hardcoverapp/hardcover-docs/blob/main/src/content/docs/api/GraphQL/Schemas/Books.mdx

This mutation allows for the creation of a new book entry in the system. It requires the book's title, number of pages, release date, and an optional description.

```APIDOC
## Create a New Book

### Description
Creates a new book record in the system. This mutation requires the `title`, `pages`, and `release_date` of the book, and optionally accepts a `description`.

### Mutation
```graphql
mutation {
      createBook(input: {
            title: "My First Book",
            pages: 300,
            release_date: "2024-09-07"
            description: "This is my first book."
        }) {
        book {
              title
              pages
              release_date
              description
        }
      }
}
```

### Parameters
#### Input Arguments
- **input** (Object) - Required - Contains the details for the new book.
  - **title** (String) - Required - The title of the book.
  - **pages** (Int) - Required - The total number of pages in the book.
  - **release_date** (Date) - Required - The date the book was released.
  - **description** (String) - Optional - A brief description of the book.

### Response
#### Success Response
Returns the created book object, including its `title`, `pages`, `release_date`, and `description`.
```