api

Documentation

Overview

Package api is a thin HTTP client for the BiblioScan public API. The API key is sent raw in the Authorization header (no Bearer prefix), exactly like a session token — see API_KEYS.md.

Index

• Constants
• func AbsoluteImageURL(baseURL, p string) string
• type AmazonStatus
• type BarcodeHistoryItem
• type BarcodeList
• type BarcodeSnapshot
• type BooklistSummary
• type Client
  • func New(baseURL, key string) *Client
  • func (c *Client) BaseURL() string
  • func (c *Client) JSON(method, path string, payload any, out any) ([]byte, error)
  • func (c *Client) Upload(path string, fields map[string]string, fileField, filePath string, out any) ([]byte, error)
• type Error
  • func (e *Error) Error() string
• type FbaInventory
• type FlexString
  • func (s *FlexString) UnmarshalJSON(b []byte) error
• type JobState
• type Keepa
• type Metadata
• type MetadataResponse
• type Referrals
• type RestrictionResult
• type ResyncResult
• type SalesHistory
• type ScanCreated
• type ScanDetail
• type ScanJob
• type ScanListResponse
• type ScanSummary
• type Spine
• type SpineResult
  • func (r *SpineResult) Keepa() *Keepa
• type StockBook
• type StockCreated
• type StockPlatform
• type User

Constants

const DefaultBaseURL = "https://biblioscan.ai"

Functions

func AbsoluteImageURL

func AbsoluteImageURL(baseURL, p string) string

AbsoluteImageURL rewrites the API's relative image paths ("../images/…") into absolute URLs. Already-absolute URLs and empty strings pass through.

Types

type AmazonStatus

type AmazonStatus struct {
	Linked           bool   `json:"linked"`
	SellingPartnerID string `json:"selling_partner_id"`
	LinkedAt         string `json:"linked_at"`
	FbaSyncStatus    string `json:"fba_sync_status"`
	FbaSyncedAt      string `json:"fba_synced_at"`
}

AmazonStatus is GET /api/amazon/status.

type BarcodeHistoryItem

type BarcodeHistoryItem struct {
	BarcodeScanID string `json:"barcodeScanId"`
	ISBN          string `json:"ISBN"`
	Lang          string `json:"lang"`
	State         string `json:"state"`
	ScannedAt     string `json:"scannedAt"`
	ImageURL      string `json:"imageurl"`
}

BarcodeHistoryItem is one row of GET /api/barcode/list.

type BarcodeList

type BarcodeList struct {
	Barcodes []BarcodeHistoryItem `json:"barcodes"`
	HasMore  bool                 `json:"hasMore"`
}

BarcodeList is GET /api/barcode/list.

type BarcodeSnapshot

type BarcodeSnapshot struct {
	BarcodeScanID string    `json:"barcodeScanId"`
	State         string    `json:"state"`
	Fresh         bool      `json:"fresh"`
	Metadata      *Metadata `json:"metadata"`
}

BarcodeSnapshot is POST /api/barcode/scan and GET /api/barcode/scan/:id. Poll until Fresh (data < 3 days) or State == "error"; an "error" state with non-nil Metadata means the cache is stale but usable.

type BooklistSummary

type BooklistSummary struct {
	ID        string     `json:"_id"`
	Name      string     `json:"name"`
	CreatedAt string     `json:"createdAt"`
	Jobs      []JobState `json:"jobs"`
}

BooklistSummary is one row of GET /api/booklist.

type Client

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

func New

func New(baseURL, key string) *Client

func (*Client) BaseURL

func (c *Client) BaseURL() string

func (*Client) JSON

func (c *Client) JSON(method, path string, payload any, out any) ([]byte, error)

JSON sends a request with an optional JSON payload, decodes the response into out (if non-nil), and always returns the raw response body.

func (*Client) Upload

func (c *Client) Upload(path string, fields map[string]string, fileField, filePath string, out any) ([]byte, error)

Upload sends a multipart/form-data request with one file and extra fields.

type Error

type Error struct {
	Status  int
	Message string
}

Error is a non-2xx API response. Message carries the backend's {"error": "…"} body when present.

func (*Error) Error

func (e *Error) Error() string

type FbaInventory

type FbaInventory struct {
	Fulfillable  *float64 `json:"fulfillable"`
	Inbound      *float64 `json:"inbound"`
	Reserved     *float64 `json:"reserved"`
	LastSyncedAt string   `json:"last_synced_at"`
	SyncStatus   string   `json:"sync_status"`
	Stale        bool     `json:"stale"`
}

FbaInventory is GET /api/amazon/book/fba-inventory (and the refresh POST).

type FlexString

type FlexString string

FlexString decodes JSON strings and numbers alike — numeric-looking fields such as isbn may arrive as either.

func (*FlexString) UnmarshalJSON

func (s *FlexString) UnmarshalJSON(b []byte) error

type JobState

type JobState struct {
	State string `json:"state"`
}

JobState is the only job info present in /api/scan/list.

type Keepa

type Keepa struct {
	ISBN             FlexString `json:"isbn"`
	ASIN             string     `json:"asin"`
	Title            string     `json:"title"`
	Authors          string     `json:"authors"`
	ImageURL         string     `json:"imageurl"`
	CurrentUsedPrice *float64   `json:"currentusedprice"`
	MeanUsedPrice    *float64   `json:"meanusedprice"`
	MinPriceNow      *float64   `json:"MinPriceNow"`
	AmazonMinPrice   *float64   `json:"AmazonMinPrice"`
	ListPrice        *float64   `json:"listprice"`
	Rank             *float64   `json:"rank"`
	CurrentOffers    *float64   `json:"currentOffers"`
	UsedCount        *float64   `json:"usedcount"`
	Freq12           *float64   `json:"freq12"`
	Freq6            *float64   `json:"freq6"`
	Freq3            *float64   `json:"freq3"`
	Freq1            *float64   `json:"freq1"`
}

Keepa is the pricing/sales block under metadata.sources.keepa (subset of fields — see NEEDED_RESULT_KEYS in biblioscan-mobile/src/services/api.ts).

type Metadata

type Metadata struct {
	Lang      string `json:"lang"`
	UpdatedAt string `json:"updatedAt"`
	Sources   struct {
		Keepa *Keepa `json:"keepa"`
	} `json:"sources"`
}

Metadata is the cached analysis object returned by barcode and metadata routes.

type MetadataResponse

type MetadataResponse struct {
	Fresh    bool      `json:"fresh"`
	Metadata *Metadata `json:"metadata"`
}

MetadataResponse is GET /api/metadata/:ASIN.

type Referrals

type Referrals struct {
	ReferralCount int `json:"referralCount"`
}

Referrals is GET /api/user/referrals.

type RestrictionResult

type RestrictionResult struct {
	Status       string   `json:"status"`
	ApprovalLink string   `json:"approval_link"`
	Reasons      []string `json:"reasons"`
}

RestrictionResult is POST /api/amazon/book/check-restrictions.

type ResyncResult

type ResyncResult struct {
	SyncStatus     string `json:"sync_status"`
	AlreadyRunning bool   `json:"already_running"`
}

ResyncResult is POST /api/amazon/fba/resync.

type SalesHistory

type SalesHistory struct {
	UnitsSold    *float64 `json:"units_sold"`
	TotalRevenue *float64 `json:"total_revenue"`
	Currency     string   `json:"currency"`
}

SalesHistory is GET /api/amazon/book/sales-history.

type ScanCreated

type ScanCreated struct {
	ID   string `json:"_id"`
	Name string `json:"name"`
}

ScanCreated is POST /api/scan/new.

type ScanDetail

type ScanDetail struct {
	ID        string    `json:"_id"`
	Name      string    `json:"name"`
	CreatedAt string    `json:"createdAt"`
	Jobs      []ScanJob `json:"jobs"`
}

ScanDetail is GET /api/scan/:batchId.

type ScanJob

type ScanJob struct {
	ID     string  `json:"_id"`
	State  string  `json:"state"`
	Lang   string  `json:"lang"`
	Spines []Spine `json:"spines"`
}

ScanJob is one uploaded image within a scan. Terminal states are "finished" and "error".

type ScanListResponse

type ScanListResponse struct {
	Scans      []ScanSummary `json:"scans"`
	TotalPages int           `json:"totalPages"`
}

ScanListResponse is GET /api/scan/list.

type ScanSummary

type ScanSummary struct {
	ID        string     `json:"_id"`
	Name      string     `json:"name"`
	CreatedAt string     `json:"createdAt"`
	Jobs      []JobState `json:"jobs"`
}

ScanSummary is one row of GET /api/scan/list.

type Spine

type Spine struct {
	ID      string        `json:"_id"`
	Results []SpineResult `json:"results"`
}

Spine is one detected book spine.

type SpineResult

type SpineResult struct {
	Title    string   `json:"title"`
	Authors  string   `json:"authors"`
	ASIN     string   `json:"ASIN"`
	Score    *float64 `json:"score"`
	Metadata *Keepa   `json:"metadata"`
	Sources  *struct {
		Keepa *Keepa `json:"keepa"`
	} `json:"sources"`
}

SpineResult is one candidate match for a spine (clients use results[0]).

func (*SpineResult) Keepa

func (r *SpineResult) Keepa() *Keepa

Keepa returns the pricing block, preferring the new sources.keepa location over the legacy metadata field.

type StockBook

type StockBook struct {
	ID               string          `json:"_id"`
	ISBN             string          `json:"isbn"`
	ASIN             string          `json:"asin"`
	Title            string          `json:"title"`
	Author           string          `json:"author"`
	Publisher        string          `json:"publisher"`
	ImageURL         string          `json:"imageUrl"`
	PurchaseDate     string          `json:"purchaseDate"`
	PurchasePrice    *float64        `json:"purchasePrice"`
	PurchaseLocation string          `json:"purchaseLocation"`
	Condition        *float64        `json:"condition"`
	Platforms        []StockPlatform `json:"platforms"`
	SaleDate         string          `json:"saleDate"`
	SalePrice        *float64        `json:"salePrice"`
	CreatedAt        string          `json:"createdAt"`
}

StockBook is one entry of GET /api/stock.

type StockCreated

type StockCreated struct {
	ID string `json:"id"`
}

StockCreated is POST /api/stock — the one route that answers "id", not "_id".

type StockPlatform

type StockPlatform struct {
	Name      string   `json:"name"`
	SalePrice *float64 `json:"salePrice"`
	URL       string   `json:"url"`
	Sold      bool     `json:"sold"`
}

StockPlatform is a marketplace listing attached to a stock book.

type User

type User struct {
	Username            string `json:"username"`
	Email               string `json:"email"`
	PhoneNumber         string `json:"phone_number"`
	PhoneNumberVerified bool   `json:"phone_number_verified"`
	Credit              int    `json:"credit"`
	BarcodeCredit       int    `json:"barcode_credit"`
	Language            string `json:"language"`
	Country             string `json:"country"`
	ReferralCode        string `json:"referral_code"`
}

User is GET /api/user/me.