api

Documentation

Index

• func IsNetworkError(err error) bool
• type APIBook
• type APIContribution
• type APIImage
• type APIUserBook
• type APIUserBookRead
• type Client
  • func NewClient(token string) *Client
  • func (c *Client) GetBookRatingsByIDs(ctx context.Context, ids []int) (map[int]model.Book, error)
  • func (c *Client) GetMe(ctx context.Context) (int, string, error)
  • func (c *Client) InsertUserBook(ctx context.Context, bookID int, statusID int) (int, error)
  • func (c *Client) InsertUserBookRead(ctx context.Context, userBookID int, progressPages int) (*APIUserBookRead, error)
  • func (c *Client) ListUserBooks(ctx context.Context, statusID int) ([]APIUserBook, error)
  • func (c *Client) SearchBooks(ctx context.Context, query string, perPage int, mode model.SearchMode) ([]model.SearchResult, error)
  • func (c *Client) UpdateReadProgress(ctx context.Context, userBookReadID int, progressPages int) error
  • func (c *Client) UpdateUserBookStatus(ctx context.Context, userBookID int, statusID int) error
  • func (c *Client) UpsertUserBookReads(ctx context.Context, userBookID int, progressPages int) error
• type FlexibleFloat
  • func (v *FlexibleFloat) UnmarshalJSON(data []byte) error
• type FlexibleInt
  • func (v *FlexibleInt) UnmarshalJSON(data []byte) error
• type InsertUserBookReadResponse
• type InsertUserBookResponse
• type MeResponse
• type MeUser
• type NetworkError
  • func (e *NetworkError) Error() string
  • func (e *NetworkError) Unwrap() error
• type SearchResponse
• type TypesenseBookDoc
• type TypesenseImage
• type TypesenseResults
• type UpdateUserBookReadResponse
• type UpdateUserBookResponse
• type UpsertUserBookReadsResponse
• type UserBooksResponse

Functions

func IsNetworkError

func IsNetworkError(err error) bool

IsNetworkError reports whether an error should map to network/API exit code 2.

Types

type APIBook

type APIBook struct {
	ID             int               `json:"id"`
	Title          string            `json:"title"`
	Pages          int               `json:"pages"`
	Slug           string            `json:"slug"`
	Rating         float64           `json:"rating"`
	RatingsCount   int               `json:"ratings_count"`
	ReviewsCount   int               `json:"reviews_count"`
	UsersCount     int               `json:"users_count"`
	UsersReadCount int               `json:"users_read_count"`
	ReleaseDate    *string           `json:"release_date"`
	Contributions  []APIContribution `json:"contributions"`
	Image          *APIImage         `json:"image"`
}

APIBook represents a book from the API.

type APIContribution

type APIContribution struct {
	Author struct {
		Name string `json:"name"`
	} `json:"author"`
}

APIContribution represents an author contribution to a book.

type APIImage

type APIImage struct {
	URL string `json:"url"`
}

APIImage represents an image URL from the API.

type APIUserBook

type APIUserBook struct {
	ID            int               `json:"id"`
	StatusID      int               `json:"status_id"`
	UpdatedAt     *string           `json:"updated_at"`
	UserBookReads []APIUserBookRead `json:"user_book_reads"`
	Book          APIBook           `json:"book"`
}

APIUserBook represents a user-book relationship from the API.

type APIUserBookRead

type APIUserBookRead struct {
	ID            int     `json:"id"`
	ProgressPages int     `json:"progress_pages"`
	StartedAt     *string `json:"started_at"`
	FinishedAt    *string `json:"finished_at"`
}

APIUserBookRead represents a reading progress entry from the API.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client wraps the machinebox/graphql client with authentication and rate limiting.

func NewClient

func NewClient(token string) *Client

NewClient creates a new Hardcover API client with the given auth token. The token is normalised to include a "Bearer " prefix if missing.

func (*Client) GetBookRatingsByIDs

func (c *Client) GetBookRatingsByIDs(ctx context.Context, ids []int) (map[int]model.Book, error)

GetBookRatingsByIDs fetches rating metadata for a set of book IDs.

func (*Client) GetMe

func (c *Client) GetMe(ctx context.Context) (int, string, error)

GetMe returns the authenticated user's ID and username.

func (*Client) InsertUserBook

func (c *Client) InsertUserBook(ctx context.Context, bookID int, statusID int) (int, error)

InsertUserBook adds a book to the user's library with the given status and returns the user_book ID.

func (*Client) InsertUserBookRead

func (c *Client) InsertUserBookRead(ctx context.Context, userBookID int, progressPages int) (*APIUserBookRead, error)

InsertUserBookRead creates a new reading progress entry for the given user book.

func (*Client) ListUserBooks

func (c *Client) ListUserBooks(ctx context.Context, statusID int) ([]APIUserBook, error)

ListUserBooks returns the user's books filtered by status ID.

func (*Client) SearchBooks

func (c *Client) SearchBooks(ctx context.Context, query string, perPage int, mode model.SearchMode) ([]model.SearchResult, error)

SearchBooks searches for books by query string and returns parsed results.

func (*Client) UpdateReadProgress

func (c *Client) UpdateReadProgress(ctx context.Context, userBookReadID int, progressPages int) error

UpdateReadProgress updates the progress pages on an existing user book read.

func (*Client) UpdateUserBookStatus

func (c *Client) UpdateUserBookStatus(ctx context.Context, userBookID int, statusID int) error

UpdateUserBookStatus changes the status of an existing user book.

func (*Client) UpsertUserBookReads

func (c *Client) UpsertUserBookReads(ctx context.Context, userBookID int, progressPages int) error

UpsertUserBookReads creates or updates a reading progress entry for the given user book.

type FlexibleFloat

type FlexibleFloat float64

FlexibleFloat handles APIs that may return a number or a quoted number.

func (*FlexibleFloat) UnmarshalJSON

func (v *FlexibleFloat) UnmarshalJSON(data []byte) error

type FlexibleInt

type FlexibleInt int

FlexibleInt handles APIs that sometimes return a number and sometimes a quoted number.

func (*FlexibleInt) UnmarshalJSON

func (v *FlexibleInt) UnmarshalJSON(data []byte) error

type InsertUserBookReadResponse

type InsertUserBookReadResponse struct {
	InsertUserBookRead struct {
		ID           *int             `json:"id"`
		Error        *string          `json:"error"`
		UserBookRead *APIUserBookRead `json:"user_book_read"`
	} `json:"insert_user_book_read"`
}

InsertUserBookReadResponse is the response shape for inserting a user book read.

type InsertUserBookResponse

type InsertUserBookResponse struct {
	InsertUserBook struct {
		ID       *int `json:"id"`
		UserBook *struct {
			ID int `json:"id"`
		} `json:"user_book"`
		Error *string `json:"error"`
	} `json:"insert_user_book"`
}

InsertUserBookResponse is the response shape for inserting a user book.

type MeResponse

type MeResponse struct {
	Me []MeUser `json:"me"`
}

MeResponse is the response shape for the me query.

type MeUser

type MeUser struct {
	ID        int           `json:"id"`
	Username  string        `json:"username"`
	UserBooks []APIUserBook `json:"user_books"`
}

MeUser represents a single user entry from the me query.

type NetworkError

type NetworkError struct {
	Err error
}

NetworkError marks transient request failures (timeouts, 429, 5xx, transport errors). The CLI maps these to exit code 2.

func (*NetworkError) Error

func (e *NetworkError) Error() string

func (*NetworkError) Unwrap

func (e *NetworkError) Unwrap() error

type SearchResponse

type SearchResponse struct {
	Search struct {
		Results json.RawMessage `json:"results"`
	} `json:"search"`
}

SearchResponse is the response shape for book search queries. The results field contains raw Typesense JSON.

type TypesenseBookDoc

type TypesenseBookDoc struct {
	ID          FlexibleInt     `json:"id"`
	Title       string          `json:"title"`
	AuthorNames []string        `json:"author_names"`
	Pages       FlexibleInt     `json:"pages"`
	Slug        string          `json:"slug"`
	Rating      FlexibleFloat   `json:"rating"`
	Ratings     FlexibleInt     `json:"ratings_count"`
	Image       *TypesenseImage `json:"image"`
}

TypesenseBookDoc represents a book document from Typesense search.

type TypesenseImage

type TypesenseImage struct {
	URL string `json:"url"`
}

TypesenseImage represents an image in Typesense search results.

type TypesenseResults

type TypesenseResults struct {
	Hits []struct {
		Document TypesenseBookDoc `json:"document"`
	} `json:"hits"`
}

TypesenseResults represents parsed Typesense search results.

type UpdateUserBookReadResponse

type UpdateUserBookReadResponse struct {
	UpdateUserBookRead struct {
		ID    *int    `json:"id"`
		Error *string `json:"error"`
	} `json:"update_user_book_read"`
}

UpdateUserBookReadResponse is the response shape for updating a user book read.

type UpdateUserBookResponse

type UpdateUserBookResponse struct {
	UpdateUserBook struct {
		ID    *int    `json:"id"`
		Error *string `json:"error"`
	} `json:"update_user_book"`
}

UpdateUserBookResponse is the response shape for updating a user book.

type UpsertUserBookReadsResponse

type UpsertUserBookReadsResponse struct {
	UpsertUserBookReads struct {
		Error      *string `json:"error"`
		UserBookID *int    `json:"user_book_id"`
	} `json:"upsert_user_book_reads"`
}

UpsertUserBookReadsResponse is the response shape for upserting user book reads.

type UserBooksResponse

type UserBooksResponse struct {
	Me []MeUser `json:"me"`
}

UserBooksResponse is the response shape for listing user books.