pkggodev

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 20, 2026 License: MIT Imports: 6 Imported by: 0

README

Typed Go client for pkg.go.dev

tag Go Version GoDoc Build Status Go report Contributors License

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, list versions, importers and known vulnerabilities.

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

🚀 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) // clean strings, no Opt wrappers

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

// 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)
}

🧠 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.
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[Symbol]
Vulns(ctx, path, opts...) *Page[Vulnerability]
Call options

WithVersion, WithModule, WithLimit, WithToken, WithFilter, WithGOOS, WithGOARCH, WithDoc, WithQuery, WithSymbol, WithExamples, WithImports, WithLicenses, WithReadme. 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

Contributors

💫 Show your support

Give a ⭐️ if this project helped you!

GitHub Sponsors

📝 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

View Source 
const DefaultBaseURL = api.DefaultBaseURL

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

Variables

This section is empty.

Functions

This section is empty.

Types

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[Symbol, 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) AllVulns 

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

AllVulns iterates all vulnerabilities for the module or package at path.

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.

func (*Client) Module 

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

Module returns metadata for the module at path.

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.

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.

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.

func (*Client) Symbols 

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

Symbols lists the exported symbols of the package at path.

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.

func (*Client) Vulns 

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

Vulns lists known vulnerabilities for the module or package at path.

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

type ImportedByResult 

type ImportedByResult struct {
	ModulePath string       `json:"modulePath,omitempty"`
	Version    string       `json:"version,omitempty"`
	Packages   Page[string] `json:"packages"`
}

ImportedByResult lists the packages that import a given package.

type License 

type License struct {
	Contents string   `json:"contents,omitempty"`
	FilePath string   `json:"filePath,omitempty"`
	Types    []string `json:"types,omitempty"`
}

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

type Module 

type Module struct {
	Path              string    `json:"path"`
	Version           string    `json:"version,omitempty"`
	RepoURL           string    `json:"repoUrl,omitempty"`
	GoModContents     string    `json:"goModContents,omitempty"`
	CommitTime        time.Time `json:"commitTime,omitzero"`
	HasGoMod          bool      `json:"hasGoMod"`
	IsLatest          bool      `json:"isLatest"`
	IsRedistributable bool      `json:"isRedistributable"`
	IsStandardLibrary bool      `json:"isStandardLibrary"`
	Licenses          []License `json:"licenses,omitempty"`
	Readme            Readme    `json:"readme,omitzero"`
}

Module is metadata about a single module.

type ModuleVersion 

type ModuleVersion struct {
	ModulePath        string    `json:"modulePath"`
	Version           string    `json:"version"`
	LatestVersion     string    `json:"latestVersion"`
	CommitTime        time.Time `json:"commitTime"`
	HasGoMod          bool      `json:"hasGoMod"`
	IsRedistributable bool      `json:"isRedistributable"`
	Deprecated        bool      `json:"deprecated"`
	DeprecationReason string    `json:"deprecationReason"`
	Retracted         bool      `json:"retracted"`
	RetractionReason  string    `json:"retractionReason"`
}

ModuleVersion is one entry from a /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 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 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              string    `json:"path"`
	ModulePath        string    `json:"modulePath,omitempty"`
	Name              string    `json:"name,omitempty"`
	Synopsis          string    `json:"synopsis,omitempty"`
	Version           string    `json:"version,omitempty"`
	Goos              string    `json:"goos,omitempty"`
	Goarch            string    `json:"goarch,omitempty"`
	Docs              string    `json:"docs,omitempty"`
	Imports           []string  `json:"imports,omitempty"`
	IsLatest          bool      `json:"isLatest"`
	IsRedistributable bool      `json:"isRedistributable"`
	IsStandardLibrary bool      `json:"isStandardLibrary"`
	Licenses          []License `json:"licenses,omitempty"`
}

Package is documentation and metadata about a single package.

type PackageInfo 

type PackageInfo struct {
	Path              string `json:"path"`
	Name              string `json:"name"`
	Synopsis          string `json:"synopsis"`
	IsRedistributable bool   `json:"isRedistributable"`
}

PackageInfo is one entry from a /packages response.

type PackagesResult 

type PackagesResult struct {
	ModulePath        string            `json:"modulePath,omitempty"`
	Version           string            `json:"version,omitempty"`
	IsStandardLibrary bool              `json:"isStandardLibrary"`
	Packages          Page[PackageInfo] `json:"packages"`
}

PackagesResult lists the packages contained in a module.

type Page 

type Page[T any] struct {
	Items     []T    `json:"items"`
	NextToken string `json:"nextToken,omitempty"`
	Total     int    `json:"total"`
}

Page is a paginated slice of T returned by listing endpoints.

type Readme 

type Readme struct {
	Contents string `json:"contents,omitempty"`
	Filepath string `json:"filepath,omitempty"`
}

Readme is a module README.

type SearchResult 

type SearchResult struct {
	ModulePath  string `json:"modulePath"`
	PackagePath string `json:"packagePath"`
	Synopsis    string `json:"synopsis"`
	Version     string `json:"version"`
}

SearchResult is one entry from a /search response.

type Symbol 

type Symbol struct {
	Name     string `json:"name"`
	Kind     string `json:"kind"`
	Synopsis string `json:"synopsis"`
	Parent   string `json:"parent"`
}

Symbol is one entry from a /symbols response.

type Vulnerability 

type Vulnerability struct {
	ID           string `json:"id"`
	Summary      string `json:"summary"`
	Details      string `json:"details"`
	FixedVersion string `json:"fixedVersion"`
}

Vulnerability is one entry from a /vulns response.

Source Files

View all Source files

Directories

Path Synopsis
internal
api
Package api is the ogen-generated pkg.go.dev API client.
 Package api is the ogen-generated pkg.go.dev API client.

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.