apiauto

type Car struct {
	// ID is source:source_id, such as encar:43020893, and never changes.
	ID     string `json:"id"`
	Market Market `json:"market"`
	// Source is encar, che168, copart or iaai.
	Source string `json:"source"`
	// SourceID is the listing or lot number at the source.
	SourceID string `json:"source_id"`
	Title    string `json:"title"`
	Brand    string `json:"brand"`
	Model    string `json:"model"`
	// Generation is set in Korea only.
	Generation   string `json:"generation"`
	Trim         string `json:"trim"`
	Year         *int   `json:"year"`
	MileageKM    *int   `json:"mileage_km"`
	Fuel         string `json:"fuel"`
	Transmission string `json:"transmission"`
	EngineCC     *int   `json:"engine_cc"`
	BodyType     string `json:"body_type"`
	Color        string `json:"color"`
	VIN          string `json:"vin"`
	Price        Price  `json:"price"`
	// PriceUSD is the price in dollars at the ECB daily rate, a decimal string.
	PriceUSD      string     `json:"price_usd"`
	Location      Location   `json:"location"`
	Photos        []string   `json:"photos"`
	PhotoCount    int        `json:"photo_count"`
	ListingURL    string     `json:"listing_url"`
	IsActive      bool       `json:"is_active"`
	FirstSeenAt   time.Time  `json:"first_seen_at"`
	LastSeenAt    time.Time  `json:"last_seen_at"`
	DisappearedAt *time.Time `json:"disappeared_at"`
	UpdatedAt     time.Time  `json:"updated_at"`
	// SourceMode is replica, or live for [Client.USLive].
	SourceMode string `json:"source_mode"`
	// Raw holds the fields only the source has, as it sends them, such as damage_main or sale_date.
	Raw map[string]any `json:"raw"`
}

type CarsPage struct {
	Items []Car `json:"items"`
	// NextCursor goes into [CarsParams.Cursor] for the next page; empty on the last one.
	NextCursor string `json:"next_cursor"`
	// Count is the number of cars matching the filters when there are at most 10,000; nil above.
	Count *int `json:"count"`
}

type CarsParams struct {
	// Brand is a make as [Client.Brands] spells it; case, spaces and hyphens are ignored.
	Brand string
	// Model is the model family, one name in every market: Grandeur, 3 Series.
	Model string
	// Generation is for Korea only: the generation as in [Car.Generation].
	Generation string
	// Trim is an exact match.
	Trim    string
	YearMin int
	YearMax int
	// PriceMin and PriceMax are in the market's currency (KRW, CNY or USD).
	PriceMin float64
	PriceMax float64
	// PriceUSDMin and PriceUSDMax are in dollars at the ECB rate.
	PriceUSDMin float64
	PriceUSDMax float64
	// MileageMax is in kilometres.
	MileageMax int
	// Fuel, Transmission and BodyType are canonical values from [Client.Dictionaries].
	Fuel         string
	Transmission string
	BodyType     string
	HasPhotos    *bool
	// IsActive is true by default on the server; false returns cars taken off sale in the last 14 days.
	IsActive *bool
	// Q is up to 6 words of the title: year, make, model, trim.
	Q    string
	Sort Sort
	// Limit is the cars per page, 1-100 (up to 20 on the demo); 20 by default.
	Limit int
	// Cursor is [CarsPage.NextCursor] of the previous page.
	Cursor string
}

type Change struct {
	ID int64 `json:"id"`
	// CarID is the car's id; its prefix tells the source.
	CarID  string     `json:"car_id"`
	Market Market     `json:"market"`
	Type   ChangeType `json:"type"`
	At     time.Time  `json:"at"`
	// OldPrice and NewPrice are decimal strings, set on price events only.
	OldPrice string `json:"old_price"`
	NewPrice string `json:"new_price"`
	// Pct is the size of the price change in percent, always positive; the direction is in Type.
	Pct string `json:"pct"`
}

type ChangeType string

type ChangesPage struct {
	Items []Change `json:"items"`
	// NextCursor goes into [ChangesParams.Cursor] for the next page; empty on the last one.
	NextCursor string `json:"next_cursor"`
}

type ChangesParams struct {
	// Types are the event types to return; every type when empty.
	Types []ChangeType
	// MinPct is the smallest price change in percent (0.5 by default on the server).
	MinPct float64
	// Limit is the events per page, 1-100.
	Limit int
	// Cursor is [ChangesPage.NextCursor] of the previous page.
	Cursor string
}

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

type Dictionaries map[string]map[string][]string

type Error struct {
	// Message is a human-readable summary.
	Message string
	// StatusCode is the HTTP status, 0 when no response came.
	StatusCode int
	// Code is the error field of the body, such as quota_exhausted.
	Code string
	// Detail is the detail field: what exactly is wrong with the request. Like Code and ResetAt, it
	// has no control characters and at most 500 characters.
	Detail string
	// Body is the decoded JSON body, or the raw text when it is not JSON.
	Body any
	// RetryAfter is how many seconds to wait before retrying (429 and 503), from 0 to 60; nil when
	// not given. A larger or a negative value from the server is brought into that range.
	RetryAfter *int
	// ResetAt is when the quota renews, ISO 8601 (402).
	ResetAt string
	// contains filtered or unexported fields
}

type Location struct {
	// Country is an ISO 3166 code: KR, CN or US.
	Country string `json:"country"`
	// Region is a province or a US state.
	Region string `json:"region"`
	City   string `json:"city"`
}

type Market string

type MarketStatus struct {
	Market            Market     `json:"market"`
	Source            string     `json:"source"`
	AvailableInPlan   bool       `json:"available_in_plan"`
	Status            string     `json:"status"`
	DataUpdatedAt     *time.Time `json:"data_updated_at"`
	DataAgeSeconds    *int       `json:"data_age_seconds"`
	StaleAfterSeconds int        `json:"stale_after_seconds"`
	Stale             bool       `json:"stale"`
	ActiveCars        int        `json:"active_cars"`
}

type Option func(*Client) error

type Price struct {
	// Amount is a decimal string such as "23900000.00", kept as sent so no precision is lost;
	// empty when the source gives no price.
	Amount string `json:"amount"`
	// Currency is KRW, CNY or USD.
	Currency string `json:"currency"`
}

type ReferenceItem struct {
	Name  string `json:"name"`
	Count int    `json:"count"`
}

type ResponseInfo struct {
	Status int
	// QuotaLimit is the period quota (X-Quota-Limit).
	QuotaLimit *int
	// QuotaRemaining is what is left of it (X-Quota-Remaining).
	QuotaRemaining *int
	// QuotaReset is when it renews, ISO 8601 (X-Quota-Reset).
	QuotaReset string
	// RateLimit is the requests per second the plan allows (X-RateLimit-Limit).
	RateLimit *int
	// RateRemaining is the requests left in the current second (X-RateLimit-Remaining).
	RateRemaining *int
	// RateReset is the seconds until the rate window resets (X-RateLimit-Reset).
	RateReset *int
	// DataAgeSeconds is the age of the market copy that answered (X-Data-Age-Seconds).
	DataAgeSeconds *int
}

type Sort string

type USLiveParams struct {
	Make    string
	Model   string
	YearMin int
	YearMax int
	// PriceMax is in US dollars.
	PriceMax int
	// Page is 1-100.
	Page int
}

type Usage struct {
	Plan string `json:"plan"`
	// Status is demo, active or grace.
	Status    string    `json:"status"`
	ExpiresAt time.Time `json:"expires_at"`
	// Period is YYYY-MM, or demo for the whole demo term.
	Period  string    `json:"period"`
	ResetAt time.Time `json:"reset_at"`
	// QuotaUnit is records on paid plans, requests on the demo.
	QuotaUnit    string        `json:"quota_unit"`
	QuotaLimit   int           `json:"quota_limit"`
	QuotaUsed    int           `json:"quota_used"`
	RecordsLimit int           `json:"records_limit"`
	RecordsUsed  int           `json:"records_used"`
	LiveUSLimit  int           `json:"live_us_limit"`
	LiveUSUsed   int           `json:"live_us_used"`
	ByMarket     []UsageMarket `json:"by_market"`
}

type UsageMarket struct {
	Market         Market `json:"market"`
	Records        int    `json:"records"`
	Requests       int    `json:"requests"`
	LiveUSRequests int    `json:"live_us_requests"`
}