javdb

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package javdb is the public Go SDK for the JavDB app JSON API.

Index

Constants

View Source 
const (
	HostMirror = settings.HostMirror
	HostMain   = settings.HostMain
)

Host constants.

Variables

This section is empty.

Functions

func ActorPeriod 

func ActorPeriod(period string) string

ActorPeriod is a deprecated alias for RankingPeriod. Deprecated: Use RankingPeriod instead.

func FilterMagnets 

func FilterMagnets(magnets []map[string]any, cnsub, hd bool, minSize int) []map[string]any

Re-export magnet helpers for SDK callers.

func LoadOrCreateDeviceUUID 

func LoadOrCreateDeviceUUID(path string) (string, error)

LoadOrCreateDeviceUUID loads the stable device identifier at path or creates one when the file is absent. CLI callers use it before constructing a client; SDK callers may use it when they need the same identifier across processes.

func MagnetURI 

func MagnetURI(m map[string]any) string

func PickBestMagnet 

func PickBestMagnet(magnets []map[string]any) map[string]any

func RankingPeriod added in v0.5.1 

func RankingPeriod(period string) string

RankingPeriod re-export.

Types

type APIError 

type APIError = appapi.Error

Error aliases for callers.

type AuthRequired 

type AuthRequired = appapi.AuthRequired

Error aliases for callers.

type AutoHostOptions added in v0.6.0 

type AutoHostOptions struct {
	PreferredHost string
	Proxy         string
	DeviceUUID    string
	Timeout       time.Duration // 每次 probe 请求的 timeout；零值沿用 transport 默认值。
	Lang          string
}

AutoHostOptions 配置显式自动线路选择。PreferredHost 是调用方提供的待验证候选 （通常来自上次选线的 route cache）；SDK 不负责持久化。

type AutoHostResult added in v0.6.0 

type AutoHostResult struct {
	Host            string
	Latency         time.Duration
	ReusedPreferred bool
}

AutoHostResult 是自动选线结果。Latency 是缓存验证成功或全量测速赢家的单次 /startup 耗时。调用方用 javdb.New(WithHost(result.Host), ...) 构造业务客户端。

func SelectAutoHost added in v0.6.0 

func SelectAutoHost(ctx context.Context, options AutoHostOptions) (AutoHostResult, error)

SelectAutoHost 通过真实 /startup 探测选择最快的 JavDB App API host。

它显式联网选线，返回具体 URL；不会让 javdb.New(WithHost("auto")) 自动联网。调用方应先 验证 route cache 中的 PreferredHost，成功后（ReusedPreferred==true）无需写入新结果； 重测选择时再把 result.Host 持久化。

type BrowseOptions 

type BrowseOptions = appapi.BrowseOptions

BrowseOptions re-export.

type Client 

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

Client is a concrete app-API client.

func New 

func New(opts ...Option) (*Client, error)

New builds a Client.

func (*Client) API 

func (c *Client) API() *appapi.Client

API 为兼容旧调用方返回底层 adapter。该返回值不是稳定的外部 SDK 契约；新代码应优先使用 typed 方法。 Deprecated: use the documented Client methods instead.

func (*Client) AllEntityMovies 

func (c *Client) AllEntityMovies(ctx context.Context, kind, entityID string, opt EntityMoviesOptions, maxPages int) ([]map[string]any, error)

AllEntityMovies aggregates filmography pages.

func (*Client) Browse 

func (c *Client) Browse(ctx context.Context, opt BrowseOptions) (SearchResult, error)

Browse lists movies by category filters.

func (*Client) Collected 

func (c *Client) Collected(ctx context.Context, kind string) ([]map[string]any, error)

Collected returns a user collection kind.

func (*Client) DownloadMovieMedia 

func (c *Client) DownloadMovieMedia(ctx context.Context, movieID string, opt MovieMediaDownloadOptions) (MovieMediaDownloadResult, error)

DownloadMovieMedia 下载调用方选择的影片媒体。图片会先验证并还原为标准图片字节； 预览视频会完整下载已结束的 HLS 预览流。输出文件不得预先存在。

func (*Client) EntityDetail 

func (c *Client) EntityDetail(ctx context.Context, kind, id string) (map[string]any, error)

EntityDetail fetches entity meta.

func (*Client) EntityMovies 

func (c *Client) EntityMovies(ctx context.Context, kind, entityID string, opt EntityMoviesOptions) (SearchResult, error)

EntityMovies lists filmography for an entity kind.

func (*Client) ListInfo 

func (c *Client) ListInfo(ctx context.Context, listID string) (map[string]any, error)

ListInfo returns list meta payload.

func (*Client) LoadOrRefreshTaxonomy 

func (c *Client) LoadOrRefreshTaxonomy(ctx context.Context, zone string, force bool) (*tags.Doc, string, error)

LoadOrRefreshTaxonomy loads disk taxonomy or refreshes.

func (*Client) Login 

func (c *Client) Login(ctx context.Context, username, password string) (string, error)

Login authenticates and stores the token on the client. ctx is reserved for future cancellation; the underlying client is not yet context-aware.

func (*Client) Mark 

func (c *Client) Mark(ctx context.Context, movieID, status string, score int, content string) (map[string]any, error)

Mark marks a movie watched or want_watch.

func (*Client) MovieComments 

func (c *Client) MovieComments(ctx context.Context, movieID string, page, limit int) ([]map[string]any, error)

MovieComments returns one requested page from GET /api/v1/movies/{id}/reviews. It never follows later pages automatically.

func (*Client) MovieDetail 

func (c *Client) MovieDetail(ctx context.Context, movieID string) (map[string]any, error)

MovieDetail returns GET /api/v4/movies/{id} nested movie map.

func (*Client) MovieMagnets 

func (c *Client) MovieMagnets(ctx context.Context, movieID string) ([]map[string]any, error)

MovieMagnets returns GET /api/v1/movies/{id}/magnets (works anonymously).

func (*Client) MyLists 

func (c *Client) MyLists(ctx context.Context, page, limit int, sortBy string) (SearchResult, error)

MyLists returns the current user's playlists (auth).

func (*Client) RankingsActors 

func (c *Client) RankingsActors(ctx context.Context, period string) (SearchResult, error)

RankingsActors fetches actor rankings; period accepts day|week|month or daily|weekly|monthly.

func (*Client) RankingsMovies 

func (c *Client) RankingsMovies(ctx context.Context, type_, period string) (SearchResult, error)

RankingsMovies fetches movie rankings.

func (*Client) RankingsPlayback 

func (c *Client) RankingsPlayback(ctx context.Context, filterBy, period string) (SearchResult, error)

RankingsPlayback fetches playback rankings.

func (*Client) RecentViewed 

func (c *Client) RecentViewed(ctx context.Context) ([]map[string]any, error)

RecentViewed returns recently viewed movies.

func (*Client) RefreshTagTaxonomy 

func (c *Client) RefreshTagTaxonomy(ctx context.Context, zone string) (*tags.Doc, error)

RefreshTagTaxonomy downloads EN+ZH taxonomies and saves tags-{zone}.json.

func (*Client) RelatedLists 

func (c *Client) RelatedLists(ctx context.Context, movieID string, page, limit int) (SearchResult, error)

RelatedLists returns public lists related to a movie.

func (*Client) ResolveEntity 

func (c *Client) ResolveEntity(ctx context.Context, kind, ref, zone string) (string, error)

ResolveEntity resolves name/id to entity id.

func (*Client) ResolveMovieID 

func (c *Client) ResolveMovieID(ctx context.Context, number string) (string, error)

ResolveMovieID maps a printed number to internal id (search zone=all).

func (*Client) ResolveMovieIDExact added in v0.7.0 

func (c *Client) ResolveMovieIDExact(ctx context.Context, number string) (string, error)

ResolveMovieIDExact 使用 zone=all 搜索，只接受大小写不敏感的完整相等番号； 零匹配与多重精确匹配都显式失败，不沿用旧 ResolveMovieID 的首项回退语义。

func (*Client) ResolveTags 

func (c *Client) ResolveTags(ctx context.Context, refs []string, zone string) ([]string, error)

ResolveTags maps free-form tag refs to ids.

func (*Client) ResolveUserID 

func (c *Client) ResolveUserID(ctx context.Context) (userID int64, username string, err error)

ResolveUserID returns the numeric user id (and optional display name) for the current token.

func (*Client) ReverseSearch added in v0.7.0 

func (c *Client) ReverseSearch(ctx context.Context, request ReverseSearchRequest) (ReverseSearchResponse, error)

ReverseSearch 上传原始图片并返回规范化候选。Source 为空时使用内置 AVScan provider。provider 顶层失败返回 error；缓存命中时跳过 provider。

func (*Client) Search 

func (c *Client) Search(ctx context.Context, keyword string, opt SearchOptions) (SearchResult, error)

Search runs GET /api/v2/search.

func (*Client) SearchByImage added in v0.7.0 

func (c *Client) SearchByImage(ctx context.Context, request ReverseSearchRequest, _ ImageSearchOptions) (ImageSearchResult, error)

SearchByImage 反搜并对全部候选并发执行严格番号解析与完整详情；结果按 provider 原始顺序恢复。候选级失败写入 ImageSearchMatch.Error 并继续， provider 顶层失败直接返回 error。

func (*Client) SetToken 

func (c *Client) SetToken(token string)

SetToken updates the bearer token.

func (*Client) Token 

func (c *Client) Token() string

Token returns the current bearer token.

func (*Client) Top250 

func (c *Client) Top250(ctx context.Context, zone, year string, startRank, page, limit int, ignoreWatched bool) (SearchResult, error)

Top250 fetches TOP250 (auth).

func (*Client) Unmark 

func (c *Client) Unmark(ctx context.Context, movieID string) (bool, error)

Unmark removes the user's review mark.

func (*Client) WantMovies 

func (c *Client) WantMovies(ctx context.Context) ([]map[string]any, error)

WantMovies returns all want_watch (想看) movies.

func (*Client) WatchedMovies 

func (c *Client) WatchedMovies(ctx context.Context) ([]map[string]any, error)

WatchedMovies returns all watched (看過) movies.

type EntityMoviesOptions 

type EntityMoviesOptions = appapi.EntityMoviesOptions

EntityMoviesOptions re-export.

type ImageSearchError added in v0.7.0 

type ImageSearchError struct {
	Stage   string `json:"stage"`
	Code    string `json:"code"`
	Message string `json:"message"`
}

ImageSearchError 是单候选联动失败的稳定错误。

func (*ImageSearchError) Error added in v0.7.0 

func (e *ImageSearchError) Error() string

type ImageSearchMatch added in v0.7.0 

type ImageSearchMatch struct {
	Candidate ReverseSearchCandidate `json:"candidate"`
	MovieID   string                 `json:"movie_id,omitempty"`
	Movie     map[string]any         `json:"movie,omitempty"`
	Error     *ImageSearchError      `json:"error,omitempty"`
}

ImageSearchMatch 是单个候选的联动结果；失败时 Error 非空。

type ImageSearchOptions added in v0.7.0 

type ImageSearchOptions struct{}

ImageSearchOptions 控制候选到 JavDB 的联动解析；当前固定严格精确匹配， 保留该类型以便未来扩展（并发数、解析重试等）。

type ImageSearchResult added in v0.7.0 

type ImageSearchResult struct {
	ReverseSearch ReverseSearchResponse `json:"reverse_search"`
	Matches       []ImageSearchMatch    `json:"matches"`
}

ImageSearchResult 保留 provider 原始候选顺序。

type MovieMediaDownloadOptions 

type MovieMediaDownloadOptions struct {
	ThumbnailPath    string
	PreviewImagePath string
	PreviewVideoPath string
}

MovieMediaDownloadOptions 指定要保存到本地的影片媒体。空路径表示不下载该媒体。 PreviewImagePath 始终只对应详情返回的第一张预览图。

type MovieMediaDownloadResult 

type MovieMediaDownloadResult struct {
	ThumbnailPath     string
	ThumbnailBytes    int64
	PreviewImagePath  string
	PreviewImageBytes int64
	PreviewVideoPath  string
	PreviewVideoBytes int64
}

MovieMediaDownloadResult 记录实际写入的媒体路径和字节数。

type Option 

type Option func(*options)

Option configures New.

func WithDeviceUUID 

func WithDeviceUUID(id string) Option

WithDeviceUUID sets the app device_uuid public param.

func WithHost 

func WithHost(host string) Option

WithHost sets logical host (mirror|main) or absolute base URL.

func WithLang 

func WithLang(lang string) Option

WithLang sets Accept-Language / app lang.

func WithProxy 

func WithProxy(proxy string) Option

WithProxy sets an HTTP(S) proxy URL.

func WithReverseSearch added in v0.7.0 

func WithReverseSearch(opts ReverseSearchOptions) Option

WithReverseSearch 注入反搜缓存与传输配置。javdb.New 本身仍不联网。

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets request timeout.

func WithToken 

func WithToken(token string) Option

WithToken sets the bearer token.

type ReverseSearchCache added in v0.7.0 

type ReverseSearchCache interface {
	Get(context.Context, string) (ReverseSearchResponse, bool, error)
	Put(context.Context, string, ReverseSearchResponse) error
}

ReverseSearchCache 是 SDK 可注入的响应缓存。key 是 "<source>:<原图 SHA-256 十六进制>"（source 隔离是硬性要求，不同 provider 对同一图片不得共享缓存）；实现不得保存图片、鉴权 header 或 JavDB 详情。 CLI 以本接口注入本机文件缓存。

type ReverseSearchCandidate added in v0.7.0 

type ReverseSearchCandidate struct {
	VideoCode  string               `json:"video_code"`
	Similarity float64              `json:"best_similarity,omitempty"`
	Frames     []ReverseSearchFrame `json:"frames,omitempty"`
}

ReverseSearchCandidate 是一个视频候选。

type ReverseSearchFrame added in v0.7.0 

type ReverseSearchFrame struct {
	ImageName    string  `json:"image_name,omitempty"`
	Similarity   float64 `json:"similarity,omitempty"`
	Timestamp    string  `json:"timestamp,omitempty"`
	ThumbnailURL string  `json:"thumbnail_url,omitempty"`
}

ReverseSearchFrame 是候选结果中的一帧。

type ReverseSearchOptions added in v0.7.0 

type ReverseSearchOptions struct {
	Cache          ReverseSearchCache
	Retries        int
	RetryWait      time.Duration
	RequestTimeout time.Duration
}

ReverseSearchOptions 配置反搜传输与缓存。零值使用默认三次总请求与 30/60 秒退避、60 秒单请求超时。

type ReverseSearchRequest added in v0.7.0 

type ReverseSearchRequest struct {
	Image    []byte              `json:"image"`
	Filename string              `json:"filename,omitempty"`
	Source   ReverseSearchSource `json:"source,omitempty"`
	// BypassCache 请求级绕过缓存读写。
	BypassCache bool `json:"bypass_cache,omitempty"`
}

ReverseSearchRequest 是一次以图搜番的原始图片输入。

type ReverseSearchResponse added in v0.7.0 

type ReverseSearchResponse struct {
	Source     string                   `json:"source"`
	Candidates []ReverseSearchCandidate `json:"candidates"`
}

ReverseSearchResponse 是反搜的规范化结果。

type ReverseSearchSource added in v0.7.0 

type ReverseSearchSource struct {
	Name    string            `json:"name"`
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers,omitempty"`
}

ReverseSearchSource 描述一个反搜 source。Name 为空或 "builtin" 时使用内置 AVScan provider；否则 URL 必须是绝对 HTTP(S) 地址，Headers 必须已展开。

type SearchOptions 

type SearchOptions = appapi.SearchOptions

SearchOptions is re-exported for SDK callers.

type SearchResult 

type SearchResult = appapi.SearchResult

SearchResult is re-exported.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.