pkggodev

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.
• 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:

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.

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, AllVulns, AllSymbols, AllPackages, AllImportedBy.

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.