hardcover

Documentation

Overview

Package hardcover is a first-party ingest provider for a Hardcover (hardcover.app) "Read" shelf. It pulls a user's read books over Hardcover's GraphQL API and yields them as resolvable records for the shared ingest.Run pipeline (ARCHITECTURE §9), so a Hardcover shelf flows through the same identity/clustering and `lcat project` path as any other source -- no bespoke clustering, facet counting, or subject control outside the framework.

Each read book is exploded into one record per collapsed edition format (physical / audiobook / ebook): the records share the book's Work-clustering key (author, title, language) so they cluster into a single Work, while each carries a distinct per-format instance key, so a mixed-format read becomes one Work with an Instance per format -- exactly how OverDrive editions cluster.

Index

• Constants
• func New(cfg ingest.Config) (ingest.Provider, error)
• type Provider
  • func (p Provider) Introspect(ctx context.Context, typeName string) ([]byte, error)
  • func (p Provider) Name() string
  • func (p Provider) Records(ctx context.Context) ([]ingest.Record, error)
  • func (p Provider) Role() ingest.Role

Constants

const ProviderName = "hardcover"

ProviderName is the Hardcover provider's registry key and default provenance feed graph (feed:hardcover).

const SourceHardcover = "hardcover"

SourceHardcover is the bf:source scheme of a Hardcover instance's provenance id (the book/edition id), tagged so it is recoverable from a grain for back-links (mirrors OverDrive's source-tagged identifiers; ARCHITECTURE §9).

Functions

func New

func New(cfg ingest.Config) (ingest.Provider, error)

New is the ingest.Factory for Hardcover. Config.Feed overrides the provenance feed (default feed:hardcover); Config.Source, when set, is a captured user_books JSON file replayed instead of calling the API; Config.Params["limit"] sets the page size. For a live fetch the API token comes from Params["token"] or $HARDCOVER_API_TOKEN / $HARDCOVER_TOKEN and is required -- it is never written to disk.

Types

type Provider

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

Provider is the Hardcover ingest provider. It either fetches a user's Read shelf live over the GraphQL API (with a bearer token) or replays a captured shelf JSON from Source -- the latter powers offline rebuilds and the golden test.

func (Provider) Introspect

func (p Provider) Introspect(ctx context.Context, typeName string) ([]byte, error)

Introspect dumps the fields of a GraphQL type (default "query_root") as pretty JSON, a diagnostic for Hardcover's drifting schema. It is exposed for the CLI subcommand.

func (Provider) Name

func (p Provider) Name() string

Name returns the provider's provenance feed graph name.

func (Provider) Records

func (p Provider) Records(ctx context.Context) ([]ingest.Record, error)

Records returns the shelf as ingest records: each read book is exploded into one record per collapsed edition format, so the shared pipeline clusters a book's formats into a single Work (they share the author/title/language cluster key) with one Instance each (distinct per-format instance keys). A book with no derivable format yields a single formatless record. ctx cancels a live fetch.

func (Provider) Role

func (p Provider) Role() ingest.Role

Role reports Hardcover as a bibliographic ingest source (feed:<name>).