pkggodev

README

Typed Go client for pkg.go.dev

A typed Go client for the pkg.go.dev API (the "Go Pkgsite API", https://pkg.go.dev/v1beta): search packages and symbols, read documentation (whole package or a single symbol), list versions, importers, known vulnerabilities and a module's dependencies.

The public API lives at the module root (package pkggodev): context-first methods, functional options, clean typed results (no ogen codegen leakage) and auto-paginating iterators. It wraps an ogen-generated client kept under internal/api.

Optional response fields are typed as mo.Option[T] (e.g. pkg.Synopsis is mo.Option[string], module.Size is mo.Option[int64]): the type tells absent apart from a zero value, with no leaked codegen wrappers. Read them with .OrEmpty(), .Get(), .MustGet() or .IsAbsent(). Required fields stay plain (pkg.Path is a string). When marshalled back to JSON, absent options are omitted (omitzero).

[!TIP] Looking for a CLI or MCP instead of a Go library? Use samber/godig — the pkg.go.dev CLI powered by this client.

🚀 Install

go get github.com/samber/go-pkggodev-client

This library is v0 and follows SemVer. It is compatible with Go >= 1.25 (uses iter.Seq2).

💡 Quick start

import pkggodev "github.com/samber/go-pkggodev-client"

c, err := pkggodev.New(pkggodev.WithUserAgent("my-app/1.0"))
if err != nil {
	panic(err)
}

// Single object.
pkg, _ := c.Package(ctx, "github.com/samber/lo")
fmt.Println(pkg.Path, pkg.Synopsis.OrEmpty()) // required string + optional mo.Option[string]

// A single symbol's documentation (token-efficient, no full package blob).
sym, err := c.Symbol(ctx, "github.com/samber/lo", "Map", pkggodev.WithExamples())
if errors.Is(err, pkggodev.ErrSymbolNotFound) {
	// symbol does not exist in the package
}
fmt.Println(sym.Kind, sym.Signature) // "Function", "func Map[...](...) ..."
fmt.Println(sym.Synopsis.OrEmpty())  // first sentence of the doc

// One page.
page, _ := c.Versions(ctx, "github.com/samber/lo", pkggodev.WithLimit(10))
fmt.Println(page.Total, page.NextToken.OrEmpty())

// All results, auto-paginated.
for v, err := range c.AllVersions(ctx, "github.com/samber/lo") {
	if err != nil {
		break
	}
	fmt.Println(v.Version, v.CommitTime)
}

// A module's dependencies, parsed from the go.mod on the Go module proxy.
deps, _ := c.Dependencies(ctx, "github.com/samber/do/v2")
for _, d := range deps.Requires {
	fmt.Println(d.Path, d.Version.OrEmpty(), d.Indirect) // github.com/samber/go-type-to-string v1.8.0 false
}

// Module download size (Content-Length of the proxy zip), opt-in via WithSize.
m, _ := c.Module(ctx, "github.com/samber/do/v2", pkggodev.WithSize())
fmt.Println(m.GoVersion.OrEmpty(), m.Size.OrEmpty()) // "1.18" 65031 (bytes)

🧠 Spec

GoDoc: https://pkg.go.dev/github.com/samber/go-pkggodev-client

Client constructor

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

• WithBaseURL(url) — override the API base URL.
• WithVulnBaseURL(url) — override the Go vulnerability database base URL used by Vulns (defaults to https://vuln.go.dev).
• WithHTTPClient(*http.Client) — custom timeouts / transport.
• WithUserAgent(string) — set the User-Agent header.
• WithGoproxy(string) — override the module proxy list used by MajorVersions, Dependencies and Module/Versions with WithSize (same syntax as the GOPROXY env var; honored by default, defaulting to https://proxy.golang.org).

Methods

All take context.Context first and return clean, typed values:

Method	Returns
Search(ctx, opts...)	*Page[SearchResult]
Package(ctx, path, opts...)	*Package
ImportedBy(ctx, path, opts...)	*ImportedByResult
Packages(ctx, path, opts...)	*PackagesResult
Module(ctx, path, opts...)	*Module
Versions(ctx, path, opts...)	*Page[ModuleVersion]
Symbols(ctx, path, opts...)	*Page[SymbolInfo]
Symbol(ctx, path, symbol, opts...)	*Symbol
Vulns(ctx, path, opts...)	[]Vulnerability
MajorVersions(ctx, modulePath, opts...)	*Page[MajorVersion]
Dependencies(ctx, modulePath, opts...)	*DependenciesResult

Symbols lists the package symbols as lightweight SymbolInfo values (name, kind, synopsis, parent). Symbol returns the full documentation of a single symbol (func, type, method, var or const) instead of the whole package doc blob — handy to keep token usage low. symbol is the exported identifier ("Map") or "Type.Method" ("Either.ForEach"); matching is case-sensitive. The doc is derived client-side from the package documentation (always fetched as Markdown, so WithDoc is ignored here) and the method returns ErrSymbolNotFound when the symbol is absent. Pass WithExamples to include runnable examples.

Vulnerabilities

Vulns is sourced directly from the Go vulnerability database in OSV format, so each Vulnerability carries far more than a summary: CVE/GHSA Aliases, affected version Ranges, the affected Packages and their Symbols, References, review status and the pkg.go.dev/vuln URL. path may be a module path (exact match) or a package path (matched to its owning module); standard-library imports such as crypto/x509 resolve to the stdlib pseudo-module.

The result is scoped to the queried module, so there is no single fixedVersion field: a module can be fixed across several disjoint intervals, so the fix lives per-interval in Ranges[].Fixed.

for _, v := range vulns {
    fmt.Println(v.ID, v.Aliases) // GO-2021-0113 [CVE-2021-38561 GHSA-ppp9-7jff-5vj2]
    for _, r := range v.Ranges {
        fmt.Printf("  introduced %s, fixed %s\n", r.Introduced.OrEmpty(), r.Fixed.OrEmpty())
    }
}

Pass WithVersion with a concrete semver to keep only the vulnerabilities actually affecting that version (read the covering fix from Ranges); WithLimit caps the result. The database is fetched whole rather than paginated, so Vulns returns a plain slice.

Major versions

In Go, major versions beyond v1 live as separate modules (path, path/v2, path/v3…) and can be non-contiguous (e.g. v1, v2, v4, v6). pkg.go.dev does not yet expose a MajorVersions endpoint (golang/go#76718), so MajorVersions derives the answer from the Go module proxy — honoring GOPROXY (see WithGoproxy). It lists the tagged versions of the base path (which yields v0, v1 and any +incompatible majors that share it) and probes path/vN for higher majors. gopkg.in/pkg.vN paths are supported too.

page, _ := c.MajorVersions(ctx, "github.com/samber/do")
for _, mv := range page.Items {
	fmt.Println(mv.Major, mv.ModulePath, mv.Version, mv.IsLatest)
	// v2 github.com/samber/do/v2 v2.0.0 true
	// v1 github.com/samber/do    v1.6.0 false
}

Each MajorVersion carries its own ModulePath, the Major ("v2"), the latest Version in that major, and IsLatest for the highest major. Results are sorted newest-major-first. The module proxy has no pagination cursor, so the result is a single page. WithExcludePseudo drops majors whose latest version is a pseudo-version (reflecting ExcludePseudo from the proposal); WithLimit caps the number of returned majors (the proposal's Max); WithFilter matches each major's module path. MajorVersions returns ErrProxyDisabled when GOPROXY is off/direct-only and ErrInvalidModulePath for an unparsable path.

Dependencies

pkg.go.dev does not expose a dependencies endpoint, so Dependencies reads and parses the module's go.mod straight from the Go module proxy (honoring GOPROXY, see WithGoproxy). It returns the require directives (each with its version and whether it is // indirect), plus any replace and exclude directives and the module's go directive.

deps, _ := c.Dependencies(ctx, "github.com/samber/do/v2")
fmt.Println(deps.Version, deps.GoVersion.OrEmpty()) // resolved version + go directive, e.g. "v2.0.0" "1.18"
for _, d := range deps.Requires {
	fmt.Println(d.Path, d.Version.OrEmpty(), d.Indirect)
}

WithVersion selects the version; when unset (or "latest") the proxy's latest version is used and Version reports the concrete version the go.mod was read at. Dependencies returns ErrProxyDisabled when GOPROXY is off/direct-only, ErrInvalidModulePath for an unparsable path, and ErrModuleNotFound when the module version is unknown to every proxy.

Module download size

Module always reports the go directive of the module's go.mod in Module.GoVersion (read from the already-returned go.mod contents, no extra request). Download sizes are opt-in via WithSize: a size is the Content-Length of the module zip on the Go module proxy, fetched with a HEAD request (the archive is never downloaded). It populates Module.Size (one extra request) and, on Versions / AllVersions, ModuleVersion.Size for each listed version (one concurrent request per version).

m, _ := c.Module(ctx, "github.com/samber/do/v2", pkggodev.WithSize())
fmt.Println(m.GoVersion.OrEmpty(), m.Size.OrEmpty()) // "1.18" 65031  (bytes)

// Size of every release, fetched concurrently.
for v, err := range c.AllVersions(ctx, "github.com/samber/do/v2", pkggodev.WithSize()) {
	if err != nil {
		break
	}
	fmt.Println(v.Version, v.Size.OrEmpty())
}

Module and Versions return ErrProxyDisabled when WithSize is set but GOPROXY is off/direct-only.

Call options

WithVersion, WithModule, WithLimit, WithToken, WithFilter, WithGOOS, WithGOARCH, WithDoc, WithQuery, WithSymbol, WithExamples, WithImports, WithLicenses, WithReadme, WithSize, WithExcludePseudo. Each method ignores options that do not apply to it.

Iterators (auto-pagination)

Each listing endpoint has an All… variant returning a Go 1.25 iter.Seq2[T, error] that lazily follows NextToken across pages:

AllSearch, AllVersions, AllSymbols, AllPackages, AllImportedBy. (Vulns is not paginated — it already returns the full slice — so there is no AllVulns.)

for v, err := range c.AllVersions(ctx, "github.com/samber/lo") {
	if err != nil {
		return err
	}
	fmt.Println(v.Version, v.CommitTime)
}

WithLimit controls the page size; WithToken sets the starting cursor.

🤝 Contributing

# Install dev dependencies
make tools

# Run tests
make test

# Lint
make lint

👤 Contributors

💫 Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2026 Samuel Berthe.

This project is MIT licensed.

Documentation

Overview

Package pkggodev is a typed Go client for the pkg.go.dev API.

It wraps the ogen-generated client (under internal/api) with an ergonomic, context-first surface and clean response types.

Index

• Constants
• Variables
• type AffectedPackage
• type Client
  • func New(opts ...ClientOption) (*Client, error)
  • func (c *Client) AllImportedBy(ctx context.Context, path string, opts ...Option) iter.Seq2[string, error]
  • func (c *Client) AllPackages(ctx context.Context, path string, opts ...Option) iter.Seq2[PackageInfo, error]
  • func (c *Client) AllSearch(ctx context.Context, opts ...Option) iter.Seq2[SearchResult, error]
  • func (c *Client) AllSymbols(ctx context.Context, path string, opts ...Option) iter.Seq2[SymbolInfo, error]
  • func (c *Client) AllVersions(ctx context.Context, path string, opts ...Option) iter.Seq2[ModuleVersion, error]
  • func (c *Client) Dependencies(ctx context.Context, modulePath string, opts ...Option) (*DependenciesResult, error)
  • func (c *Client) ImportedBy(ctx context.Context, path string, opts ...Option) (*ImportedByResult, error)
  • func (c *Client) MajorVersions(ctx context.Context, modulePath string, opts ...Option) (*Page[MajorVersion], error)
  • func (c *Client) Module(ctx context.Context, path string, opts ...Option) (*Module, error)
  • func (c *Client) Package(ctx context.Context, path string, opts ...Option) (*Package, error)
  • func (c *Client) Packages(ctx context.Context, path string, opts ...Option) (*PackagesResult, error)
  • func (c *Client) Search(ctx context.Context, opts ...Option) (*Page[SearchResult], error)
  • func (c *Client) Symbol(ctx context.Context, path, symbol string, opts ...Option) (*Symbol, error)
  • func (c *Client) Symbols(ctx context.Context, path string, opts ...Option) (*Page[SymbolInfo], error)
  • func (c *Client) Versions(ctx context.Context, path string, opts ...Option) (*Page[ModuleVersion], error)
  • func (c *Client) Vulns(ctx context.Context, path string, opts ...Option) ([]Vulnerability, error)
• type ClientOption
  • func WithBaseURL(u string) ClientOption
  • func WithGoproxy(s string) ClientOption
  • func WithHTTPClient(h *http.Client) ClientOption
  • func WithUserAgent(ua string) ClientOption
  • func WithVulnBaseURL(u string) ClientOption
• type DependenciesResult
• type Dependency
• type Example
• type ImportedByResult
• type License
• type MajorVersion
• type Module
• type ModuleVersion
• type Option
  • func WithDoc(s string) Option
  • func WithExamples() Option
  • func WithExcludePseudo() Option
  • func WithFilter(f string) Option
  • func WithGOARCH(s string) Option
  • func WithGOOS(s string) Option
  • func WithImports() Option
  • func WithLicenses() Option
  • func WithLimit(n int) Option
  • func WithModule(m string) Option
  • func WithQuery(q string) Option
  • func WithReadme() Option
  • func WithSize() Option
  • func WithSymbol(s string) Option
  • func WithToken(t string) Option
  • func WithVersion(v string) Option
• type Package
• type PackageInfo
• type PackagesResult
• type Page
• type Readme
• type Reference
• type Replacement
• type SearchResult
• type Symbol
• type SymbolInfo
• type VersionRange
• type Vulnerability

Constants

const DefaultBaseURL = api.DefaultBaseURL

DefaultBaseURL is the production pkg.go.dev API base URL.

const DefaultMaxIdleConns = 1000

DefaultMaxIdleConns is the number of idle keep-alive connections the default HTTP client keeps open for reuse, shared across the API and proxy calls. The standard http.DefaultTransport keeps only 2 idle connections per host, which throttles the highly concurrent calls this client is built for.

Variables

var ErrInvalidModulePath = errors.New("pkggodev: invalid module path")

ErrInvalidModulePath is returned when a module path cannot be parsed, e.g. by MajorVersions.

var ErrModuleNotFound = errors.New("pkggodev: module not found")

ErrModuleNotFound is returned by Dependencies when the module (at the requested version) is unknown to every configured proxy.

var ErrProxyDisabled = errors.New("pkggodev: no usable module proxy (GOPROXY)")

ErrProxyDisabled is returned by MajorVersions and Dependencies (and by Module/ Versions when WithSize is set) when no usable module proxy is configured (GOPROXY is "off" or resolves to "direct" only).

var ErrSymbolNotFound = errors.New("pkggodev: symbol not found")

ErrSymbolNotFound is returned by Client.Symbol when the requested symbol is absent from the package documentation.

Types

type AffectedPackage

type AffectedPackage struct {
	// Path is the affected import path, e.g. "crypto/x509".
	Path string `json:"path"`
	// Symbols are the affected exported identifiers ("Fn", "Type.Method"). SLICE:
	// a vulnerability can live in several functions/methods of the package. EMPTY
	// means the whole package is affected (no symbol-level narrowing) — treat
	// empty as "all symbols", not "none".
	Symbols []string `json:"symbols,omitempty"`
	// Goos restricts the affected build to these operating systems. SLICE: a vuln
	// can be specific to multiple GOOS values (e.g. "windows", "darwin"). EMPTY
	// means all operating systems.
	Goos []string `json:"goos,omitempty"`
	// Goarch restricts the affected build to these architectures. SLICE: same
	// rationale as Goos. EMPTY means all architectures.
	Goarch []string `json:"goarch,omitempty"`
}

AffectedPackage is one affected import path within the queried module.

type Client

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

Client is the pkg.go.dev API api.

func New

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

New builds a pkg.go.dev client with sane defaults.

func (*Client) AllImportedBy

func (c *Client) AllImportedBy(ctx context.Context, path string, opts ...Option) iter.Seq2[string, error]

AllImportedBy iterates all packages that import the package at path.

func (*Client) AllPackages

func (c *Client) AllPackages(ctx context.Context, path string, opts ...Option) iter.Seq2[PackageInfo, error]

AllPackages iterates all packages contained in the module at path.

func (*Client) AllSearch

func (c *Client) AllSearch(ctx context.Context, opts ...Option) iter.Seq2[SearchResult, error]

AllSearch iterates all search results, fetching pages lazily.

func (*Client) AllSymbols

func (c *Client) AllSymbols(ctx context.Context, path string, opts ...Option) iter.Seq2[SymbolInfo, error]

AllSymbols iterates all exported symbols of the package at path.

func (*Client) AllVersions

func (c *Client) AllVersions(ctx context.Context, path string, opts ...Option) iter.Seq2[ModuleVersion, error]

AllVersions iterates all versions of the module at path, fetching pages lazily.

func (*Client) Dependencies

func (c *Client) Dependencies(ctx context.Context, modulePath string, opts ...Option) (*DependenciesResult, error)

Dependencies returns the dependencies declared in the go.mod of the module at modulePath, parsed from the Go module proxy (honoring GOPROXY, see WithGoproxy). It reports the require directives — each with its version and whether it is "// indirect" — plus any replace and exclude directives and the module's go directive.

WithVersion selects the version; when unset (or "latest") the proxy's latest version is used, and the result's Version is the concrete version the go.mod was read at. Dependencies returns ErrProxyDisabled when GOPROXY is "off"/"direct"-only, ErrInvalidModulePath for an unparsable path, and ErrModuleNotFound when the module version is unknown to every proxy.

func (*Client) ImportedBy

func (c *Client) ImportedBy(ctx context.Context, path string, opts ...Option) (*ImportedByResult, error)

ImportedBy lists the packages that import the package at path. Use WithModule and WithVersion to scope the package; WithLimit, WithToken and WithFilter tune the listing. The importer paths are paginated inside ImportedByResult.Packages (see AllImportedBy to auto-paginate).

func (*Client) MajorVersions

func (c *Client) MajorVersions(ctx context.Context, modulePath string, opts ...Option) (*Page[MajorVersion], error)

MajorVersions discovers the major versions of the module at modulePath.

In Go, majors beyond v1 live as separate modules (path, path/v2, path/v3...) and can be non-contiguous. pkg.go.dev does not (yet) expose a MajorVersions endpoint (golang/go#76718), so this derives the answer from the module proxy (honoring GOPROXY, see WithGoproxy). modulePath may already carry a major suffix (path/v2 or gopkg.in/pkg.v2); it is normalized to the base path first.

WithExcludePseudo drops majors whose latest version is a pseudo-version. WithFilter applies a regular expression to each major's module path. WithLimit caps the number of returned majors (the proposal's Max), keeping the most recent ones. The module proxy has no pagination cursor, so the result is always a single page (NextToken is empty); Total is the count before WithLimit.

func (*Client) Module

func (c *Client) Module(ctx context.Context, path string, opts ...Option) (*Module, error)

Module returns metadata for the module at path. Use WithVersion to pin a version and WithLicenses/WithReadme to include the licenses/README. WithSize fills Module.Size from the module proxy with one extra HEAD request and returns ErrProxyDisabled when GOPROXY is "off"/"direct"-only.

func (*Client) Package

func (c *Client) Package(ctx context.Context, path string, opts ...Option) (*Package, error)

Package returns documentation and metadata for the package at path. Use WithModule to disambiguate the owning module and WithVersion to pin a version; WithGOOS/WithGOARCH set the build context and WithDoc the doc format. By default docs, examples, imports and licenses are omitted — request them with WithDoc-bearing options, WithExamples, WithImports and WithLicenses.

func (*Client) Packages

func (c *Client) Packages(ctx context.Context, path string, opts ...Option) (*PackagesResult, error)

Packages lists the packages contained in the module at path. Use WithVersion to pin a version; WithLimit, WithToken and WithFilter tune the listing. The packages are paginated inside PackagesResult.Packages (see AllPackages to auto-paginate).

func (*Client) Search

func (c *Client) Search(ctx context.Context, opts ...Option) (*Page[SearchResult], error)

Search finds packages and symbols. Use WithQuery and/or WithSymbol to set the query; WithLimit, WithToken and WithFilter tune the listing. Results are paginated (see Page and AllSearch to auto-paginate).

func (*Client) Symbol

func (c *Client) Symbol(ctx context.Context, path, symbol string, opts ...Option) (*Symbol, error)

Symbol returns the full documentation of a single symbol of the package at path. symbol is the exported identifier (e.g. "Map") or "Type.Method" (e.g. "Either.ForEach"); matching is case-sensitive. WithExamples includes runnable examples.

The documentation is derived client-side from the package documentation, which is always requested in Markdown form, so WithDoc has no effect here. It returns ErrSymbolNotFound when the symbol is absent from the package.

func (*Client) Symbols

func (c *Client) Symbols(ctx context.Context, path string, opts ...Option) (*Page[SymbolInfo], error)

Symbols lists the exported symbols of the package at path as lightweight SymbolInfo values (use Client.Symbol for one symbol's full doc). Use WithModule and WithVersion to scope the package and WithGOOS/WithGOARCH the build context; WithLimit, WithToken and WithFilter tune the listing. Results are paginated (see Page and AllSymbols to auto-paginate).

func (*Client) Versions

func (c *Client) Versions(ctx context.Context, path string, opts ...Option) (*Page[ModuleVersion], error)

Versions lists the versions of the module at path. WithLimit, WithToken and WithFilter tune the listing; WithSize fills each ModuleVersion.Size from the module proxy with one concurrent HEAD per version (ErrProxyDisabled when GOPROXY is "off"/"direct"-only). Results are paginated (see Page and AllVersions to auto-paginate).

func (*Client) Vulns

func (c *Client) Vulns(ctx context.Context, path string, opts ...Option) ([]Vulnerability, error)

Vulns lists known vulnerabilities for the module or package at path, sourced from the Go vulnerability database (https://vuln.go.dev) in OSV format.

path may be a module path (exact match) or a package path (matched to its owning module); standard-library imports such as "crypto/x509" resolve to the "stdlib" pseudo-module. With WithVersion set to a concrete semver, only the vulnerabilities actually affecting that version are returned (a symbolic version like "latest" disables this filtering; read the covering fix from each Vulnerability.Ranges). WithLimit caps the result, which is ordered by ID.

The result is scoped to the queried module: each Vulnerability hoists that one module's version ranges and packages to the root. Unlike the other listing methods this returns a plain slice — the database is fetched whole, so there is no server-side pagination.

type ClientOption

type ClientOption func(*clientConfig)

ClientOption configures the Client built by New.

func WithBaseURL

func WithBaseURL(u string) ClientOption

WithBaseURL overrides the API base URL.

func WithGoproxy

func WithGoproxy(s string) ClientOption

WithGoproxy overrides the module proxy list used by MajorVersions. The value uses the same syntax as the GOPROXY environment variable (a "," or "|" separated list of base URLs, plus the keywords "direct" and "off"). When unset, the client honors the GOPROXY environment variable, defaulting to https://proxy.golang.org.

func WithHTTPClient

func WithHTTPClient(h *http.Client) ClientOption

WithHTTPClient sets a custom *http.Client (timeouts, transport, etc.).

func WithUserAgent

func WithUserAgent(ua string) ClientOption

WithUserAgent sets the User-Agent header sent on every request.

func WithVulnBaseURL

func WithVulnBaseURL(u string) ClientOption

WithVulnBaseURL overrides the Go vulnerability database base URL used by Vulns. It defaults to https://vuln.go.dev.

type DependenciesResult

type DependenciesResult struct {
	// ModulePath is the queried module path.
	ModulePath string `json:"modulePath"`
	// Version is the concrete version the go.mod was read at.
	Version string `json:"version"`
	// GoVersion is the "go" directive, e.g. "1.25". None if absent.
	GoVersion mo.Option[string] `json:"goVersion,omitzero"`
	// Requires are the module's direct and indirect requirements. SLICE: a module
	// typically requires many dependencies.
	Requires []Dependency `json:"requires,omitempty"`
	// Replaces are the go.mod replace directives. SLICE: a go.mod can hold several.
	Replaces []Replacement `json:"replaces,omitempty"`
	// Excludes are the go.mod exclude directives. SLICE: a go.mod can hold several.
	Excludes []Dependency `json:"excludes,omitempty"`
}

DependenciesResult is the parsed go.mod of a module: the dependencies it declares (requires), plus any replace/exclude directives, fetched from the Go module proxy. See Client.Dependencies.

type Dependency

type Dependency struct {
	// Path is the dependency module path.
	Path string `json:"path"`
	// Version is the required version. None for an exclude (which has no single version).
	Version mo.Option[string] `json:"version,omitzero"`
	// Indirect is true for a "// indirect" require (transitive, not imported directly).
	Indirect bool `json:"indirect,omitempty"`
}

Dependency is one module a target module depends on, parsed from a go.mod require (or exclude) directive.

type Example

type Example struct {
	// Name is the suffix of "Example (name)"; None for a bare "Example".
	Name mo.Option[string] `json:"name,omitzero"`
	// Code is the example source.
	Code string `json:"code"`
	// Output is the expected output (the "// Output:" block). None if absent.
	Output mo.Option[string] `json:"output,omitzero"`
}

Example is a runnable example attached to a symbol.

type ImportedByResult

type ImportedByResult struct {
	// ModulePath is the module of the queried package. None if unknown.
	ModulePath mo.Option[string] `json:"modulePath,omitzero"`
	// Version is the version the result was computed at. None if unset.
	Version mo.Option[string] `json:"version,omitzero"`
	// Packages is the paginated page of importer package paths (see Page; many
	// packages may import one).
	Packages Page[string] `json:"packages"`
}

ImportedByResult lists the packages that import a given package, returned by Client.ImportedBy.

type License

type License struct {
	// Contents is the full license text. None unless the endpoint returned it.
	Contents mo.Option[string] `json:"contents,omitzero"`
	// FilePath is the license file path within the module. None if unknown.
	FilePath mo.Option[string] `json:"filePath,omitzero"`
	// Types are the detected SPDX license identifiers. SLICE: a single file can
	// match several licenses (e.g. dual-licensed); empty when none were detected.
	Types []string `json:"types,omitempty"`
}

License describes a license file detected in a module or package.

type MajorVersion

type MajorVersion struct {
	ModulePath string `json:"modulePath"` // e.g. "github.com/samber/do/v2"
	Major      string `json:"major"`      // e.g. "v2"
	Version    string `json:"version"`    // latest version in this major, e.g. "v2.0.0"
	IsLatest   bool   `json:"isLatest"`   // true for the highest major
}

MajorVersion is one major version of a module, discovered via the module proxy (see Client.MajorVersions). Majors beyond v1 live as separate modules (path, path/v2, path/v3...), so each MajorVersion carries its own module path.

type Module

type Module struct {
	// Path is the module path, e.g. "github.com/samber/lo". Always present.
	Path string `json:"path"`
	// Version is the module version this metadata was read at. None if unset.
	Version mo.Option[string] `json:"version,omitzero"`
	// GoVersion is the "go" directive of go.mod, e.g. "1.25". None if unknown.
	GoVersion mo.Option[string] `json:"goVersion,omitzero"`
	// RepoURL is the source repository URL. None if unknown.
	RepoURL mo.Option[string] `json:"repoUrl,omitzero"`
	// GoModContents is the raw go.mod file. None unless returned.
	GoModContents mo.Option[string] `json:"goModContents,omitzero"`
	// CommitTime is the version's commit/tag time. None if unknown.
	CommitTime mo.Option[time.Time] `json:"commitTime,omitzero"`
	// Size is the module zip size in bytes. None unless requested with WithSize.
	Size mo.Option[int64] `json:"size,omitzero"`
	// HasGoMod reports whether the module has a go.mod file.
	HasGoMod bool `json:"hasGoMod"`
	// IsLatest reports whether Version is the latest released version.
	IsLatest bool `json:"isLatest"`
	// IsRedistributable reports whether the module may be redistributed (license-wise).
	IsRedistributable bool `json:"isRedistributable"`
	// IsStandardLibrary reports whether this is the standard library.
	IsStandardLibrary bool `json:"isStandardLibrary"`
	// Licenses are the licenses detected for the module. SLICE: a module can be
	// covered by several license files; populated only with WithLicenses.
	Licenses []License `json:"licenses,omitempty"`
	// Readme is the module README. None unless requested with WithReadme.
	Readme mo.Option[Readme] `json:"readme,omitzero"`
}

Module is metadata about a single module, returned by Client.Module.

type ModuleVersion

type ModuleVersion struct {
	// ModulePath is the module path.
	ModulePath string `json:"modulePath"`
	// Version is this released version, e.g. "v1.2.3".
	Version string `json:"version"`
	// LatestVersion is the module's latest version (identical across the listing).
	LatestVersion string `json:"latestVersion"`
	// CommitTime is when this version was committed/tagged.
	CommitTime time.Time `json:"commitTime"`
	// Size is the version zip size in bytes. None unless requested with WithSize.
	Size mo.Option[int64] `json:"size,omitzero"`
	// HasGoMod reports whether this version has a go.mod file.
	HasGoMod bool `json:"hasGoMod"`
	// IsRedistributable reports whether this version may be redistributed.
	IsRedistributable bool `json:"isRedistributable"`
	// Deprecated reports whether the module is marked deprecated at this version.
	Deprecated bool `json:"deprecated"`
	// DeprecationReason is the deprecation message, empty if not deprecated.
	DeprecationReason string `json:"deprecationReason"`
	// Retracted reports whether this version is retracted.
	Retracted bool `json:"retracted"`
	// RetractionReason is the retraction message, empty if not retracted.
	RetractionReason string `json:"retractionReason"`
}

ModuleVersion is one entry from a Client.Versions response.

type Option

type Option func(*params)

Option configures optional query parameters for a single API call. Each method ignores options that do not apply to it.

func WithDoc

func WithDoc(s string) Option

WithDoc sets the documentation format (text, html, md or markdown).

func WithExamples

func WithExamples() Option

WithExamples includes examples with returned documentation.

func WithExcludePseudo

func WithExcludePseudo() Option

WithExcludePseudo drops majors whose latest version is a pseudo-version (untagged commits). It reflects the ExcludePseudo flag of the proposed pkg.go.dev MajorVersions endpoint (golang/go#76718) and applies to MajorVersions only.

func WithFilter

func WithFilter(f string) Option

WithFilter applies a regular-expression filter to listing results.

func WithGOARCH

func WithGOARCH(s string) Option

WithGOARCH sets the GOARCH documentation build context.

func WithGOOS

func WithGOOS(s string) Option

WithGOOS sets the GOOS documentation build context.

func WithImports

func WithImports() Option

WithImports includes the list of packages the target imports.

func WithLicenses

func WithLicenses() Option

WithLicenses includes licenses in the result.

func WithLimit

func WithLimit(n int) Option

WithLimit caps the number of items returned.

func WithModule

func WithModule(m string) Option

WithModule sets the module path for package-scoped calls.

func WithQuery

func WithQuery(q string) Option

WithQuery sets the package search query (Search only).

func WithReadme

func WithReadme() Option

WithReadme includes the README in the result (Module only).

func WithSize

func WithSize() Option

WithSize includes module download sizes in the result. A size is the Content-Length of the module zip on the Go module proxy (see WithGoproxy), fetched with a HEAD request. It applies to Module (Module.Size, one extra request) and Versions (ModuleVersion.Size, one concurrent request per listed version). Both return ErrProxyDisabled when WithSize is set but GOPROXY is "off"/"direct"-only.

func WithSymbol

func WithSymbol(s string) Option

WithSymbol sets the symbol search query (Search only).

func WithToken

func WithToken(t string) Option

WithToken resumes a listing from a pagination token.

func WithVersion

func WithVersion(v string) Option

WithVersion selects a module version (semver, "latest", "master" or "main").

type Package

type Package struct {
	// Path is the import path, e.g. "github.com/samber/lo". Always present.
	Path string `json:"path"`
	// ModulePath is the path of the module that contains the package. None if unknown.
	ModulePath mo.Option[string] `json:"modulePath,omitzero"`
	// Name is the package clause name (often the last path segment). None if unknown.
	Name mo.Option[string] `json:"name,omitzero"`
	// Synopsis is the one-line package summary. None if absent.
	Synopsis mo.Option[string] `json:"synopsis,omitzero"`
	// Version is the module version the package was rendered at. None if unset.
	Version mo.Option[string] `json:"version,omitzero"`
	// Goos is the GOOS the documentation was rendered for. None unless pinned via WithGOOS.
	Goos mo.Option[string] `json:"goos,omitzero"`
	// Goarch is the GOARCH the documentation was rendered for. None unless pinned via WithGOARCH.
	Goarch mo.Option[string] `json:"goarch,omitzero"`
	// Docs is the rendered package documentation. None unless requested.
	Docs mo.Option[string] `json:"docs,omitzero"`
	// Imports are the packages this package imports. SLICE: a package usually
	// imports many; populated only with WithImports.
	Imports []string `json:"imports,omitempty"`
	// IsLatest reports whether Version is the module's latest released version.
	IsLatest bool `json:"isLatest"`
	// IsRedistributable reports whether the package may be redistributed (license-wise).
	IsRedistributable bool `json:"isRedistributable"`
	// IsStandardLibrary reports whether the package is part of the Go standard library.
	IsStandardLibrary bool `json:"isStandardLibrary"`
	// Licenses are the licenses detected for the package. SLICE: a package can be
	// covered by several license files; populated only with WithLicenses.
	Licenses []License `json:"licenses,omitempty"`
}

Package is documentation and metadata about a single package, returned by Client.Package.

type PackageInfo

type PackageInfo struct {
	// Path is the package import path.
	Path string `json:"path"`
	// Name is the package clause name.
	Name string `json:"name"`
	// Synopsis is the one-line package summary.
	Synopsis string `json:"synopsis"`
	// IsRedistributable reports whether the package may be redistributed.
	IsRedistributable bool `json:"isRedistributable"`
}

PackageInfo is one entry from a Client.Packages response.

type PackagesResult

type PackagesResult struct {
	// ModulePath is the queried module. None if unknown.
	ModulePath mo.Option[string] `json:"modulePath,omitzero"`
	// Version is the version the listing was computed at. None if unset.
	Version mo.Option[string] `json:"version,omitzero"`
	// IsStandardLibrary reports whether the module is the standard library.
	IsStandardLibrary bool `json:"isStandardLibrary"`
	// Packages is the paginated page of packages in the module (see Page).
	Packages Page[PackageInfo] `json:"packages"`
}

PackagesResult lists the packages contained in a module, returned by Client.Packages.

type Page

type Page[T any] struct {
	// Items are the entries on this page. SLICE: listing endpoints return many
	// results; empty on a page past the end.
	Items []T `json:"items"`
	// NextToken is the cursor to the next page, passed back via WithToken. None on
	// the last page. The AllXxx iterators follow it automatically.
	NextToken mo.Option[string] `json:"nextToken,omitzero"`
	// Total is the total number of items across all pages.
	Total int `json:"total"`
}

Page is one page of a paginated listing endpoint: the items plus a cursor to the next page.

type Readme

type Readme struct {
	// Contents is the raw README text (Markdown). None if absent.
	Contents mo.Option[string] `json:"contents,omitzero"`
	// Filepath is the README path within the module, e.g. "README.md". None if absent.
	Filepath mo.Option[string] `json:"filepath,omitzero"`
}

Readme is a module README file.

type Reference

type Reference struct {
	// Type is the OSV reference kind: ADVISORY, ARTICLE, REPORT, FIX, PACKAGE,
	// EVIDENCE or WEB.
	Type string `json:"type"`
	URL  string `json:"url"`
}

Reference is an external link attached to a vulnerability.

type Replacement

type Replacement struct {
	// OldPath is the replaced module path.
	OldPath string `json:"oldPath"`
	// OldVersion is the specific version replaced. None when all versions are replaced.
	OldVersion mo.Option[string] `json:"oldVersion,omitzero"`
	// NewPath is the replacement module path or filesystem path.
	NewPath string `json:"newPath"`
	// NewVersion is the replacement version. None for a local (filesystem) replacement.
	NewVersion mo.Option[string] `json:"newVersion,omitzero"`
}

Replacement is one go.mod replace directive, redirecting a module (optionally pinned to OldVersion) to NewPath. A NewPath that is a filesystem path with no NewVersion is a local replacement.

type SearchResult

type SearchResult struct {
	// ModulePath is the module that contains the matched package.
	ModulePath string `json:"modulePath"`
	// PackagePath is the import path of the matched package.
	PackagePath string `json:"packagePath"`
	// Synopsis is the one-line package summary.
	Synopsis string `json:"synopsis"`
	// Version is the version the result was rendered at.
	Version string `json:"version"`
}

SearchResult is one entry from a Client.Search response.

type Symbol

type Symbol struct {
	// Path is the package import path the symbol belongs to.
	Path string `json:"path"`
	// Name is the exported identifier, e.g. "Map" or "Either.ForEach".
	Name string `json:"name"`
	// Kind is one of Function, Method, Type, Variable or Constant.
	Kind string `json:"kind"`
	// Signature is the symbol's Go declaration.
	Signature string `json:"signature"`
	// Synopsis is the one-line summary. None if absent.
	Synopsis mo.Option[string] `json:"synopsis,omitzero"`
	// Doc is the full documentation text. None if absent.
	Doc mo.Option[string] `json:"doc,omitzero"`
	// Examples are runnable examples for the symbol. SLICE: a symbol can have
	// several (bare "Example" plus named "Example_xxx"); populated only with WithExamples.
	Examples []Example `json:"examples,omitempty"`
	// Version is the module version the doc was rendered at. None if unset.
	Version mo.Option[string] `json:"version,omitzero"`
	// Goos is the GOOS the doc was rendered for. None unless pinned via WithGOOS.
	Goos mo.Option[string] `json:"goos,omitzero"`
	// Goarch is the GOARCH the doc was rendered for. None unless pinned via WithGOARCH.
	Goarch mo.Option[string] `json:"goarch,omitzero"`
}

Symbol is the full documentation of a single package symbol, derived client-side from the package documentation. See Client.Symbol.

type SymbolInfo

type SymbolInfo struct {
	// Name is the exported identifier, e.g. "Map" or "Either.ForEach".
	Name string `json:"name"`
	// Kind is one of Function, Method, Type, Variable or Constant.
	Kind string `json:"kind"`
	// Synopsis is the one-line summary of the symbol.
	Synopsis string `json:"synopsis"`
	// Parent is the enclosing type for a method/field, empty otherwise.
	Parent string `json:"parent"`
}

SymbolInfo is one entry from a Client.Symbols response: lightweight metadata about a package symbol. Use Client.Symbol to fetch the full documentation of one symbol.

type VersionRange

type VersionRange struct {
	Introduced mo.Option[string] `json:"introduced,omitzero"`
	Fixed      mo.Option[string] `json:"fixed,omitzero"`
}

VersionRange is one affected version interval, half-open [Introduced, Fixed). Versions are raw OSV semver (no "v" prefix); an Introduced of "0" means "from the beginning" and an absent Fixed means "no fix in this interval".

type Vulnerability

type Vulnerability struct {
	// ID is the Go advisory identifier, e.g. "GO-2022-0191". Always present.
	ID string `json:"id"`
	// Summary is a one-line title. May be empty on auto-generated entries.
	Summary string `json:"summary"`
	// Details is the full Markdown description.
	Details string `json:"details"`

	// Ranges are the affected version intervals of the queried module, each a
	// half-open [Introduced, Fixed); Fixed is the per-interval fix (there is no
	// single "fixed version"). SLICE: one module can be affected over several
	// DISJOINT intervals — a bug fixed in one release can be reintroduced in a
	// later branch and fixed again (e.g. stdlib GO-2022-0191: [0,1.10.6) AND
	// [1.11.0-0,1.11.3)). Versions are raw OSV semver (no "v"; "0" = from the start).
	Ranges []VersionRange `json:"ranges,omitempty"`
	// Packages are the affected import paths of the queried module. SLICE: a
	// single vulnerability can span several packages within the same module (e.g.
	// .../encoding/unicode AND .../transform). Empty on auto-generated UNREVIEWED
	// entries, which carry no package-level detail.
	Packages []AffectedPackage `json:"packages,omitempty"`

	// Aliases are external identifiers for the same vulnerability. SLICE: a Go
	// advisory routinely maps to one CVE plus one or more GHSA IDs.
	Aliases []string `json:"aliases,omitempty"`
	// Published is when the advisory was first published. None if absent.
	Published mo.Option[time.Time] `json:"published,omitzero"`
	// Modified is when the advisory last changed. None if absent.
	Modified mo.Option[time.Time] `json:"modified,omitzero"`
	// Withdrawn is set only for withdrawn (retracted) advisories; None otherwise.
	Withdrawn mo.Option[time.Time] `json:"withdrawn,omitzero"`
	// URL is the human-readable page, e.g. https://pkg.go.dev/vuln/GO-2022-0191.
	URL mo.Option[string] `json:"url,omitzero"`
	// ReviewStatus is "REVIEWED" or "UNREVIEWED" (auto-generated, less precise).
	ReviewStatus mo.Option[string] `json:"reviewStatus,omitzero"`
	// References are external links. SLICE: an advisory usually has several — fix
	// commits/CLs, the issue report, third-party advisories. See Reference.Type.
	References []Reference `json:"references,omitempty"`
	// Credits are the people/organizations credited. SLICE: a report can credit
	// multiple reporters.
	Credits []string `json:"credits,omitempty"`
}

Vulnerability is a known vulnerability from the Go vulnerability database (https://vuln.go.dev), in OSV format, scoped to the module or package queried via Vulns. The OSV report's affected[] array (one entry per affected module path — Go major versions are distinct modules) is flattened here to the single module that matched the query: its version ranges and packages are hoisted to Ranges and Packages below.