Hardcover

https://docs.hardcover.app/
Admin
Hardcover is a social reading app that helps users track, share, and discover books with a community...
Tokens:141,725
Snippets:1,188
Trust Score:9.5
Update:6 days ago
Show doc for...
Tokens:
Raw
### Start the dev server

Source: https://docs.hardcover.app/contributing/api-docs

Start the local development server.

```bash
npm run dev
```

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

### Example 2: Users Query Starting in Static Mode

Source: https://docs.hardcover.app/demos/query-builder-demo

A GraphQL query to fetch users with a limit of 5, returning id, name, and username. This example starts in Static mode but can be switched to Advanced to modify the query.

```graphql
query {
users(limit: 5) {
  id
  name
  username
}
}
```

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

### Get Books in User's Library

Source: https://docs.hardcover.app/api/guides/gettingallbooksinlibrary

Replace ##USER_ID## with your account id, found by completing the 'Example Request' section of the Getting Started guide. This query returns a list of books the user has added to their collection, limited to 5 results with an offset of 0.

```graphql
{
    user_books(
          where: {
              user_id: {_eq: ##USER_ID##}
          },
          distinct_on: book_id
          limit: 5
          offset: 0
    ) {
      book {
            title
            pages
            release_date
      }
    }
}
```

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

### Install dependencies

Source: https://docs.hardcover.app/contributing/api-docs

Install project dependencies using npm.

```bash
npm install
```

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

### UserBookActivity - Started Reading

Source: https://docs.hardcover.app/it/api/graphql/schemas/activities

Example payload for when a user starts reading a book.

```APIDOC
## UserBookActivity - Started Reading

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

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

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

### Start loopback server and generate redirect URI

Source: https://docs.hardcover.app/api/oauth/getting-started-device

Starts a loopback HTTP server on a free port and constructs the redirect URI. Hardcover matches loopback redirect URIs by scheme/host/path only, so the port doesn't need to match the registered one.

```python
# Bind to any free loopback port.
# Hardcover matches loopback redirect URIs by scheme/host/path only, so the registered URI doesn't need to name a specific port
server = http.server.HTTPServer(("127.0.0.1", 0), CallbackHandler)
port = server.server_address[1]
redirect_uri = f"http://127.0.0.1:{port}/callback"
```

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

### Example Request: GetBooksBySeries query

Source: https://docs.hardcover.app/api/guides/gettingbooksinseries

Complete GraphQL query to fetch books in the Harry Potter series, combining all filters and distinct_on to get a clean list.

```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
    }
  }
}
}
```

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

### PromptActivity

Source: https://docs.hardcover.app/it/api/graphql/schemas/activities

Example payload for a PromptActivity event.

```APIDOC
## PromptActivity

### Description
Example payload for a PromptActivity event.

### Example Payload
```json
{
  "data": {
    "prompt": {
      "id": 1,
      "slug": "what-are-your-favorite-books-of-all-time",
      "user": "... See User schema",
      "answers": [
        {
          "book": "... See Book schema"
        }
      ],
      "question": "What are your favorite books of all time?",
      "description": "What are some of your favorites? These can be from any time of your life."
    }
  },
  "event": "PromptActivity",
  "object_type": "Activity",
  "book_id": 370893
}
```
```

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

### ListActivity

Source: https://docs.hardcover.app/it/api/graphql/schemas/activities

Example payload for a ListActivity event.

```APIDOC
## ListActivity

### Description
Example payload for a ListActivity event.

### Example Payload
```json
{
  "data": {
    "list": {
      "id": 1234,
      "url": null,
      "name": "Owned",
      "path": "@user/lists/owned",
      "ranked": false,
      "featured": false,
      "listBooks": [
        {
          "book": "... See Book schema",
          "position": null,
          "updatedAt": "2024-09-23T23:58:14.027Z"
        }
      ],
      "updatedAt": "2024-09-23T23:58:14.040Z",
      "booksCount": 1,
      "description": "Any editions of books you've marked as 'owned' will show up in this list.",
      "followersCount": 0,
      "privacySettingId": 1
    }
  },
  "event": "ListActivity",
  "object_type": "Activity",
  "book_id": 1108457
}
```
```

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

### Example Frontmatter

Source: https://docs.hardcover.app/contributing/frontmatter

A sample frontmatter block showing required and recommended fields for a documentation page.

```yaml
---
title: Getting Started with the API
description: Get started with the Hardcover GraphQL API.
category: guide
layout: /src/layouts/documentation.astro
---
```

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

### GoalActivity

Source: https://docs.hardcover.app/it/api/graphql/schemas/activities

Example payload for a GoalActivity event.

```APIDOC
## GoalActivity

### Description
Example payload for a GoalActivity event.

### Example Payload
```json
{
  "data": {
    "goal": {
      "id": 12345,
      "goal": 40,
      "metric": "book",
      "endDate": "2024-12-31",
      "progress": 30,
      "startDate": "2024-01-01",
      "conditions": {},
      "description": "2024 Reading Goal",
      "percentComplete": 0.75,
      "privacySettingId": 1
    }
  },
  "event": "GoalActivity",
  "object_type": "Activity"
}
```
```

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

### Use GraphQLExplorer component

Source: https://docs.hardcover.app/contributing/astro-components

Example usage of the GraphQLExplorer component with query, description, presentation, and title props.

```astro
<GraphQLExplorer
    query={query}
    description="An example query"
    presentation='table'
    title="Example"
/>
```

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

### Example 1: Complex Query with Nested Fields

Source: https://docs.hardcover.app/demos/query-builder-demo

A GraphQL query that fetches user books with nested fields including book, edition, likes, reading journals, referrer, user, and user_books. This example appears to be part of a larger query, as it ends with an extra closing brace.

```graphql
        id
      }
      user_books {
        id
      }
    }
    user_books {
      book {
        id
        release_year
        title
      }
      edition {
        id
        release_year
        title
      }
      id
      likes {
        id
      }
      reading_journals {
        id
      }
      referrer {
        id
      }
      user {
        id
      }
      user_books {
        id
      }
    }
  }
  }
}
```

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

### Use ImageComponent

Source: https://docs.hardcover.app/contributing/astro-components

Example usage of the ImageComponent with imagePath and description props.

```astro
<ImageComponent
    imagePath="/src/content/images/librarians/merging-standards/merge_book_flag.png"
    description="The flag menu on a book page"
/>
```

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

### GraphQL query counting as one request

Source: https://docs.hardcover.app/api/getting-started

This example shows a single GraphQL query that combines the fields from the previous example into one top-level query, counting as only one request. It demonstrates how to reduce request count by consolidating fields.

```graphql
query Test {
  me {
    name
    username
  }
}

```

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

### Use SchemaGraph

Source: https://docs.hardcover.app/contributing/astro-components

Example usage of the SchemaGraph component with a typeName prop.

```astro
<SchemaGraph typeName="series" />
```

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

### UserBookActivity - Review

Source: https://docs.hardcover.app/it/api/graphql/schemas/activities

Example payload for when a user adds a review to a book.

```APIDOC
## UserBookActivity - Review

### Description
Example payload for a UserBookActivity event where a user adds a review to a book.

### Example Payload
```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"
}
```
```

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

### Navigate to project directory

Source: https://docs.hardcover.app/contributing/api-docs

Change into the cloned project directory.

```bash
cd hardcover-docs
```

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

### User Started Reading a Book - UserBookActivity Payload

Source: https://docs.hardcover.app/api/graphql/schemas/activities

Example payload for the UserBookActivity event when a user starts reading a book. Shows the activity object with event, data.userBook containing rating (null), review (empty string), statusId, readingFormatId, and reviewHasSpoilers, along with book_id and object_type.

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

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

### Full demo server for Hardcover OAuth 2.0

Source: https://docs.hardcover.app/api/oauth/getting-started-server

Complete single-file demo server implementing the authorization code flow with PKCE. Requires the 'requests' library and the environment variables HARDCOVER_CLIENT_ID and HARDCOVER_CLIENT_SECRET. It includes endpoints for home, login, callback, and logout, with in-memory token storage and a placeholder for refresh handling.

```python
import base64
import hashlib
import os
import secrets
import sys
import threading
import time
import urllib.parse
from http import cookies
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


import requests


# Values can come from discovery
# https://api.hardcover.app/.well-known/oauth-authorization-server
AUTHORIZE_ENDPOINT = "https://hardcover.app/oauth2/authorize"
TOKEN_ENDPOINT = "https://api.hardcover.app/oauth2/token"
REVOKE_ENDPOINT = "https://api.hardcover.app/oauth2/revoke"
GRAPHQL_ENDPOINT = "https://api.hardcover.app/v1/graphql"
ISSUER = "https://api.hardcover.app"


PORT = 8080




# Client secret lives on the server only! It must never reach the browser
def must_env(name):
    value = os.environ.get(name)
    if not value:
        sys.exit(f"missing required env var {name}")
    return value




CLIENT_ID = must_env("HARDCOVER_CLIENT_ID")
CLIENT_SECRET = must_env("HARDCOVER_CLIENT_SECRET")


HOST = f"http://localhost:{PORT}"
REDIRECT_URI = f"{HOST}/callback"


SCOPE = "read:me:content"




def random_string(n_bytes):
    return base64.urlsafe_b64encode(secrets.token_bytes(n_bytes)).rstrip(b"=").decode()




def base64url_sha256(verifier):
    digest = hashlib.sha256(verifier.encode()).digest()
    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode()




# Stand-in for wherever you actually keep sessions (a DB row, a signed http-only cookie, etc.) Global + in-memory so this stays a single file
# Probably better to key off of session, but this makes it simpler for the demo
tokens_lock = threading.Lock()
tokens = {}  # session -> {"access_token", "refresh_token", "expires_at"}


# One pending login per state value
pending_lock = threading.Lock()
pending = {}  # state -> verifier




class Handler(BaseHTTPRequestHandler):
    def get_session(self):
        jar = cookies.SimpleCookie(self.headers.get("Cookie", ""))
        return jar["session"].value if "session" in jar else ""


    def send_html(self, status, body):
        self.send_response(status)
        self.send_header("Content-Type", "text/html; charset=utf-8")
        self.end_headers()
        self.wfile.write(body.encode())


    def redirect(self, location):
        self.send_response(302)
        self.send_header("Location", location)
        self.end_headers()


    def do_GET(self):
        path = urllib.parse.urlparse(self.path).path
        if path == "/":
            self.handle_home()
        elif path == "/login":
            self.handle_login()
        elif path == "/callback":
            self.handle_callback()
        elif path == "/logout":
            self.handle_logout()
        else:
            self.send_response(404)
            self.end_headers()


    def handle_home(self):
        session = self.get_session()
        if not session:
            return self.send_html(200, '<a href="/login">Sign in with Hardcover</a>')


        with tokens_lock:
            token = tokens.get(session)


        if not token:
            return self.send_html(200, '<a href="/login">Sign in with Hardcover</a>')


        if token["expires_at"] < time.time():
            # Handle refresh here
            return self.send_html(
                200, 'Your session expired. <a href="/login">Sign in again</a>.'
            )

```

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

### Full example: OAuth client JavaScript (oauth.js)

Source: https://docs.hardcover.app/api/oauth/getting-started-spa

Complete JavaScript implementation of the OAuth 2.0 PKCE flow for Hardcover. It includes constants for endpoints, PKCE helpers, UI rendering, and the main flow: sign-in, callback handling, profile fetching, and sign-out.

```javascript
const CLIENT_ID = "64003fc6-9a33-4787-b80b-4827f40d46c6";


// Values can come from discovery
// https://api.hardcover.app/.well-known/oauth-authorization-server
const AUTHORIZE_ENDPOINT = "https://hardcover.app/oauth2/authorize";
const TOKEN_ENDPOINT = "https://api.hardcover.app/oauth2/token";
const REVOKE_ENDPOINT = "https://api.hardcover.app/oauth2/revoke";
const GRAPHQL_ENDPOINT = "https://api.hardcover.app/v1/graphql";
const ISSUER = "https://api.hardcover.app";


const REDIRECT_URI = location.origin + location.pathname;


const SCOPE = "read:me:content";


const signInBtn = document.getElementById("sign-in");
const signOutBtn = document.getElementById("sign-out");
const statusEl = document.getElementById("status");


// helpers


// Modern browsers can use `Uint8Array.prototype.toBase64({ alphabet: "base64url" })`
// But since it was was only added to all browsers in 2025 https://caniuse.com/mdn-javascript_builtins_uint8array_tobase64
// We will be using btoa and replacing the chars needed to get to the url alphabet, also dropping the padding
const base64url = (bytes) =>
  btoa(String.fromCharCode(...bytes))
    .replaceAll("+", "-")
    .replaceAll("/", "_")
    .replace(/=+$/, "");


const randomString = (byteLength) =>
  base64url(crypto.getRandomValues(new Uint8Array(byteLength)));


async function sha256(input) {
  const digest = await crypto.subtle.digest(
    "SHA-256",
    new TextEncoder().encode(input),
  );
  return base64url(new Uint8Array(digest));
}


// ui helper


function render({ signedIn, message }) {
  statusEl.textContent = message;
  signInBtn.hidden = signedIn;
  signOutBtn.hidden = !signedIn;
}


// entry point


function main() {
  signInBtn.addEventListener("click", signIn);
  signOutBtn.addEventListener("click", signOut);


  const params = new URLSearchParams(location.search);
  const savedToken = localStorage.getItem("oauth_token");


  if (params.has("error")) {
    // The user declined, or the app is misconfigured.
    history.replaceState({}, "", REDIRECT_URI);
    render({
      signedIn: false,
      message: `Sign-in failed: ${params.get("error_description") ?? params.get("error")}`,
    });
  } else if (params.has("code")) {
    handleCallback(params);
  } else if (savedToken) {
    showProfile(savedToken); // still signed in from a previous visit
  }
}


// step 1/2: prep and send the user


async function signIn() {
  const state = randomString(24);
  const verifier = randomString(32);
  const challenge_code = await sha256(verifier);


  sessionStorage.setItem("pkce_verifier", verifier);
  sessionStorage.setItem("oauth_state", state);


  const queryParams = new URLSearchParams({
    response_type: "code",
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    state: state,
    code_challenge: challenge_code,
    code_challenge_method: "S256",
    scope: SCOPE,
  });


  location.href = `${AUTHORIZE_ENDPOINT}?${queryParams}`;
}


// step 4: catch and verify the user
```

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

### Get a Single List by ID - GetListById query

Source: https://docs.hardcover.app/api/graphql/schemas/lists

Fetches a specific list using its primary key. This example uses list ID 3. Returns list details, counts, privacy setting, timestamps, and the owner's user info.

```graphql
query GetListById {
  lists_by_pk(id: 3) {
      id
      name
      description
      books_count
      likes_count
      privacy_setting_id
      created_at
      updated_at
      user {
          id
          username
          image_id
      }
  }
}
```

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

### Get Books in a Specific List - GetListBooks query

Source: https://docs.hardcover.app/api/graphql/schemas/lists

Retrieves all books in a specific list with their details. This example uses NPR Top 100 Science Fiction Fantasy list (ID: 3). Includes book title, author contributions, rating, pages, position, and date added.

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

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

### Showcase Project YAML Template

Source: https://docs.hardcover.app/showcase/submit

Use this YAML template to create your project entry file at src/content/showcase/your-project-slug.yaml. It includes required fields like name, slug, summary, description, author, links, categories, and dates, plus optional sections for screenshots, tags, featured, and stats.

```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"      # at least one of github or hardcover is required
  hardcover: "your-hardcover-username"


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


categories:
  - "Browser Extension"  # See full list below


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


# Optional
screenshots:
  - src: "/showcase/your-project-slug/screenshot-1.png"
    alt: "Description of screenshot"
    origin: "top"  # Optional crop position: top (default), center, bottom, or a percentage like "8%"


tags:
  - "relevant"
  - "tags"


featured: false  # Set by maintainers


# Optional - GitHub stats (updated manually or by script)
stats:
  githubStars: 100

```

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

### Query ReadingStats: Get aggregate statistics

Source: https://docs.hardcover.app/api/graphql/schemas/userbooks

Uses user_books_aggregate to get the count of books and average rating for the user. Replace ##USER_ID## with the actual user ID.

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

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

### Search prompts about learning from books (GraphQL)

Source: https://docs.hardcover.app/api/guides/searching

Example query for the Prompt search endpoint. Uses the search field with query_type 'Prompt', per_page 5, and page 1. Returns the results field. Default fields are question, books; default sort is _text_match:desc; default weights are 2,1; default typos is 5.

```graphql
  query PromptsAboutLearning {
      search(
          query: "learn from",
          query_type: "Prompt",
          per_page: 5,
          page: 1
      ) {
          results
      }
  }
```

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

### Full example: HTML page for OAuth demo

Source: https://docs.hardcover.app/api/oauth/getting-started-spa

The HTML page for the full OAuth demo. It includes sign-in and sign-out buttons and a status area, and loads the oauth.js script.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Hardcover OAuth demo</title>
</head>
<body>
  <button id="sign-in">Sign in with Hardcover</button>
  <button id="sign-out" hidden>Sign out</button>
  <p id="status" role="status"></p>


  <script src="./oauth.js"></script>
</body>
</html>
```

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

### Get List Statistics - GetListStats query

Source: https://docs.hardcover.app/api/graphql/schemas/lists

Uses aggregate queries to get statistics about public lists. Returns count, average, and maximum values for books_count and likes_count.

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

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

### Get one book per position with distinct_on and order_by

Source: https://docs.hardcover.app/api/guides/gettingbooksinseries

Uses distinct_on: position with order_by position and users_count to get the most popular book for each position, hiding unmerged duplicates.

```graphql
book_series(
  distinct_on: position
  order_by: [
    {position: asc},
    {book: {users_count: desc}}
  ]
) {
# ...
}
```

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

### Create a new book

Source: https://docs.hardcover.app/it/api/graphql/schemas/books

Mutation to create a new book with title, pages, release_date, and description. Returns the created book's details.

```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 the repository

Source: https://docs.hardcover.app/contributing/api-docs

Clone the Hardcover documentation repository from GitHub.

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

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

### Example 3: Authors Query with Hidden Type Selector

Source: https://docs.hardcover.app/demos/query-builder-demo

A GraphQL query to fetch authors with a limit of 10, returning id, name, and bio. This example hides the query type selector, useful when you want to lock the query type.

```graphql
query {
authors(limit: 10) {
  id
  name
  bio
}
}
```

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

### Build authorization URL with PKCE parameters

Source: https://docs.hardcover.app/api/oauth/getting-started-device

Constructs the authorization URL with required parameters: response_type, client_id, redirect_uri, state, code_challenge, code_challenge_method, and scope.

```python
params = urllib.parse.urlencode(
    {
        "response_type": "code",
        "client_id": CLIENT_ID,
        "redirect_uri": redirect_uri,
        "state": state,
        "code_challenge": code_challenge,
        "code_challenge_method": "S256",
        "scope": SCOPE,
    }
)
auth_url = f"{AUTHORIZE_ENDPOINT}?{params}"
```

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

### GetMyFollowedLists

Source: https://docs.hardcover.app/api/graphql/schemas/lists

Gets all lists that the authenticated user is following.

```APIDOC
## GetMyFollowedLists

### Description
Gets all lists that the authenticated user is following.

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

### Response Fields
- **id** (ID) - The unique identifier of the followed list record.
- **created_at** (Timestamp) - When the list was followed.
- **list** (Object) - The followed list details.
  - **id** (ID) - The list's ID.
  - **name** (String) - The list's name.
  - **description** (String) - The list's description.
  - **books_count** (Int) - The number of books in the list.
  - **likes_count** (Int) - The number of likes the list has received.
  - **user** (Object) - The user who created the list.
    - **username** (String) - The username of the list creator.
```

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

### Search prompts by question (GraphQL)

Source: https://docs.hardcover.app/it/api/guides/searching

Example query to search for prompts using the search field with query_type 'Prompt'. Returns a list of results matching the query 'learn from'.

```graphql
query PromptsAboutLearning {
    search(
        query: "learn from",
        query_type: "Prompt",
        per_page: 5,
        page: 1
    ) {
        results
    }
}
```

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

### list_books_aggregate

Source: https://docs.hardcover.app/api/graphql/schemas/lists

Get aggregated data about books in lists.

```APIDOC
## Query: list_books_aggregate

### Description
Get aggregated data about books in lists.

### Returns
- **list_books_aggregate** - Aggregated data about books in lists
```

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

### GetPublisherEditions

Source: https://docs.hardcover.app/api/graphql/schemas/editions

Gets recent editions from a specific publisher.

```APIDOC
## GetPublisherEditions

### Description
Get recent editions from a specific publisher.

### Query
```graphql
query GetPublisherEditions {
  editions(
      where: {publisher_id: {_eq: 1}}
      order_by: {release_date: desc}
      limit: 10
  ) {
      id
      title
      isbn_13
      release_date
      physical_format
      book {
          title
          rating
          contributions {
              author {
                  name
              }
          }
      }
  }
}
```

### Parameters
- **where** (object) - Required - Filter conditions. In this example, `publisher_id` is set to `{_eq: 1}`.
- **order_by** (object) - Optional - Sorting criteria. In this example, `release_date` is sorted descending.
- **limit** (integer) - Optional - Maximum number of records to return. In this example, set to 10.

### Response
Returns a list of edition objects with the requested fields.
```

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

### GetListStats

Source: https://docs.hardcover.app/api/graphql/schemas/lists

Uses aggregate queries to get statistics about lists.

```APIDOC
## GetListStats

### Description
Uses aggregate queries to get statistics about lists.

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

### Response Fields
- **aggregate** (Object) - The aggregate statistics.
  - **count** (Int) - The total number of public lists.
  - **avg** (Object) - The average values.
    - **books_count** (Float) - The average number of books per list.
    - **likes_count** (Float) - The average number of likes per list.
  - **max** (Object) - The maximum values.
    - **books_count** (Int) - The maximum number of books in a list.
    - **likes_count** (Int) - The maximum number of likes on a list.
```

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

### vibes_aggregate

Source: https://docs.hardcover.app/api/graphql/schemas/vibes

Get aggregated data about vibes (count, etc.).

```APIDOC
## Query: vibes_aggregate

### Description
Get aggregated data about vibes (count, etc.).

### Returns
vibes_aggregate
```

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

### Full OAuth 2.0 Server Implementation (Python)

Source: https://docs.hardcover.app/api/oauth/getting-started-server

Complete server code implementing the OAuth 2.0 authorization code flow with PKCE. Includes handlers for login, callback, token exchange, session management, and logout, plus a helper to fetch the user profile. Requires a configured CLIENT_ID, CLIENT_SECRET, and endpoints.

```python
profile = fetch_profile(token["access_token"])
        if profile is None:
            # Usually a saved token that has been revoked since last visit
            with tokens_lock:
                tokens.pop(session, None)
            return self.send_html(
                200, 'Your session expired. <a href="/login">Sign in again</a>.'
            )


        name, username = profile
        self.send_html(
            200, f'Signed in as {name} (@{username}). <a href="/logout">Sign out</a>'
        )


    # step 1/2: prep and send the user


    def handle_login(self):
        state = random_string(24)
        verifier = random_string(32)
        code_challenge = base64url_sha256(verifier)


        with pending_lock:
            pending[state] = verifier


        params = urllib.parse.urlencode(
            {
                "response_type": "code",
                "client_id": CLIENT_ID,
                "redirect_uri": REDIRECT_URI,
                "state": state,
                "code_challenge": code_challenge,
                "code_challenge_method": "S256",
                "scope": SCOPE,
            }
        )


        self.redirect(f"{AUTHORIZE_ENDPOINT}?{params}")


    # step 4: catch and verify the user


    def handle_callback(self):
        query = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
        q = {k: v[0] for k, v in query.items()}


        if "error" in q:
            # The user declined, or the app is misconfigured
            return self.send_html(
                400, f"sign-in failed: {q.get('error_description', '')}"
            )


        state = q.get("state", "")
        with pending_lock:
            verifier = pending.pop(state, None)


        if verifier is None or not q.get("code"):
            return self.send_html(400, "sign-in failed: unexpected callback, try again")


        if q.get("iss") != ISSUER:
            return self.send_html(
                400, "sign-in failed: response came from the wrong issuer"
            )


        # step 5: trade for the token


        resp = requests.post(
            TOKEN_ENDPOINT,
            auth=(CLIENT_ID, CLIENT_SECRET),
            data={
                "grant_type": "authorization_code",
                "code": q["code"],
                "redirect_uri": REDIRECT_URI,  # must match step 2 exactly
                "code_verifier": verifier,
            },
        )
        token = resp.json()


        if not resp.ok:
            # Read this one. Nearly every first-run failure lands here, usually a redirect_uri that doesn't match what's registered
            return self.send_html(
                502, f"sign-in failed: {token.get('error_description', '')}"
            )


        # Set a session so we know who they are
        session = random_string(32)
        self.send_response(302)
        self.send_header("Location", "/")
        self.send_header("Set-Cookie", f"session={session}; HttpOnly")
        self.end_headers()


        with tokens_lock:
            tokens[session] = {
                "access_token": token["access_token"],
                "refresh_token": token["refresh_token"],
                "expires_at": time.time() + token["expires_in"],
            }


    def handle_logout(self):
        session = self.get_session()
        if not session:
            return self.redirect("/")


        with tokens_lock:
            token = tokens.pop(session, None)


        # Optional, but tells the server the token is dead now instead of leaving it valid until it expires
        if token and token.get("refresh_token"):
            threading.Thread(
                target=lambda: requests.post(
                    REVOKE_ENDPOINT,
                    auth=(CLIENT_ID, CLIENT_SECRET),
                    data={
                        "token": token["refresh_token"],
                        "token_type_hint": "refresh_token",
                    },
                )
            ).start()


        self.redirect("/")


    def log_message(self, format, *args):
        pass  # keep stdout clean




# step 6: use the token




def fetch_profile(access_token):
    resp = requests.post(
        GRAPHQL_ENDPOINT,
        headers={"Authorization": f"Bearer {access_token}"},
        json={"query": "{ me { id username name } }"},
    )
    result = resp.json()
    me = result.get("data", {}).get("me") or []


    if not me:
        return None
    return me[0]["name"], me[0]["username"]




if __name__ == "__main__":
    print(f"listening on {HOST}")
    ThreadingHTTPServer(("", PORT), Handler).serve_forever()
```

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

### Get All Authors

Source: https://docs.hardcover.app/api/graphql/schemas/authors

Query to retrieve a list of authors with a limit.

```APIDOC
## Get All Authors

### Description
Retrieves a list of authors, limited to 10 results.

### Query
```graphql
query {
  authors(limit: 10) {
      id,
      name
  }
}
```

### Response
Returns a list of authors with their `id` and `name` fields.
```

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

### Import GraphQLExplorer component

Source: https://docs.hardcover.app/contributing/astro-components

Import path for the GraphQLExplorer Astro component.

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

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

### lists_aggregate

Source: https://docs.hardcover.app/api/graphql/schemas/lists

Get aggregated data about lists (count, averages, etc.).

```APIDOC
## Query: lists_aggregate

### Description
Get aggregated data about lists (count, averages, etc.).

### Returns
- **lists_aggregate** - Aggregated data about lists
```

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

### Import and use ImageComponent in Astro

Source: https://docs.hardcover.app/contributing/librarian-guides

Add the import once below the frontmatter, then use the component wherever the image should appear. The imagePath is the full path to the image starting with /src/content/images/, and the description is shown as the caption and used as alt text.

```astro
import ImageComponent from "@/components/ImageComponent.astro";


<ImageComponent
  imagePath="/src/content/images/librarians/long-title-example.png"
  description="Example of a long title on Hardcover"
/>
```

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

### Get an Author by Name

Source: https://docs.hardcover.app/api/graphql/schemas/authors

Query to retrieve an author by their display name.

```APIDOC
## Get an Author by Name

### Description
Retrieves an author by name using an equality filter.

### Query
```graphql
query {
  authors(where: {name: {_eq: "Robert Jordan"}}) {
      books_count
      identifiers
      name
  }
}
```

### Response
Returns the author's name, books count, and identifiers.
```

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

### Get All Characters

Source: https://docs.hardcover.app/api/graphql/schemas/characters

Query to retrieve a list of characters with their id and name.

```APIDOC
## Get All Characters

### Description
Retrieves a list of characters with their id and name.

### Query
```graphql
query {
  characters(limit: 10) {
      id,
      name
  }
}
```

### Parameters
- **limit** (Int) - Optional - Maximum number of characters to return.

### Response
Returns a list of character objects with fields `id` and `name`.
```
Tokens:
Raw