ecosystems

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Jul 22, 2026 License: MIT Imports: 17 Imported by: 1

README

ecosystems-go

Go client library for the ecosyste.ms APIs. See API documentation for details.

Installation

go get github.com/ecosyste-ms/ecosystems-go

Usage

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/ecosyste-ms/ecosystems-go"
)

func main() {
    // User agent is required - identify your application
    client, err := ecosystems.NewClient("my-app/1.0")
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Bulk lookup packages by PURL
    results, err := client.BulkLookup(ctx, []string{
        "pkg:gem/rails",
        "pkg:npm/lodash",
        "pkg:pypi/requests",
    })
    if err != nil {
        log.Fatal(err)
    }

    for purl, pkg := range results {
        fmt.Printf("%s: %s (%s)\n", purl, pkg.Name, *pkg.LatestReleaseNumber)
    }

    // Lookup a single package
    pkg, err := client.Lookup(ctx, "pkg:gem/rake")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("rake has %d versions\n", pkg.VersionsCount)

    // Get a specific version
    version, err := client.GetVersion(ctx, "rubygems.org", "rake", "13.0.0")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("rake 13.0.0 integrity: %s\n", *version.Integrity)

    // Get all versions
    versions, err := client.GetAllVersions(ctx, "rubygems.org", "rake")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("rake has %d versions\n", len(versions))
}

PURL Helpers

The library includes helpers for working with Package URLs:

import (
    "github.com/ecosyste-ms/ecosystems-go"
    packageurl "github.com/package-url/packageurl-go"
)

// Parse a PURL string (handles with or without pkg: prefix)
purl, err := ecosystems.ParsePURL("gem/rails@7.0.0")

// Convert PURL to ecosyste.ms registry name
registry := ecosystems.PURLToRegistry(purl) // "rubygems.org"

// Convert PURL to ecosyste.ms package name format
name := ecosystems.PURLToName(purl) // "rails"

// Lookup using PURL directly
pkg, err := client.LookupPURL(ctx, purl)
version, err := client.GetVersionPURL(ctx, purl)
versions, err := client.GetAllVersionsPURL(ctx, purl)

Repository Metadata

The client also wraps repository-oriented ecosyste.ms services:

repoURL := "https://github.com/rails/rails"

repo, err := client.GetRepository(ctx, repoURL)
packages, err := client.LookupPackagesByRepositoryURL(ctx, repoURL, 25)
advisories, err := client.GetAdvisoriesByRepoURL(ctx, repoURL, 100)
commits, err := client.GetCommitsSummary(ctx, repoURL)
issues, err := client.GetIssuesSummary(ctx, repoURL)
dependents, err := client.GetDependentPackages(ctx, "rubygems.org", "rails", 30)

List methods follow Link: rel="next" pagination and stop at the requested item cap when one is provided.

Options

client, err := ecosystems.NewClient("my-app/1.0",
    ecosystems.WithFrom("you@example.com"),      // From header (email)
    ecosystems.WithAPIKey("your-api-key"),       // API key for higher rate limits
    ecosystems.WithHTTPClient(customHTTPClient),
    ecosystems.WithPackagesServer("https://custom.packages.server"),
    ecosystems.WithReposServer("https://custom.repos.server"),
    ecosystems.WithAdvisoriesServer("https://custom.advisories.server"),
    ecosystems.WithCommitsServer("https://custom.commits.server"),
    ecosystems.WithIssuesServer("https://custom.issues.server"),
)

Generated Code

The packages/ and repos/ directories contain generated OpenAPI clients. To regenerate after spec updates:

# NOTE that update-specs requires the `vendir` tool (https://github.com/carvel-dev/vendir) to run
make update-specs  # Download latest OpenAPI specs
make generate      # Regenerate Go clients

Testing

make test              # Unit tests
make test-integration  # Integration tests (hits live API)

License

MIT

Documentation

Overview

Package ecosystems provides a client for the ecosyste.ms APIs.

This package wraps the generated OpenAPI clients for packages.ecosyste.ms and repos.ecosyste.ms, providing a higher-level API for common operations.

Index

Constants

View Source 
const (
	DefaultPackagesServer   = packages.ServerURLHTTPSPackagesEcosysteMsAPIV1
	DefaultReposServer      = repos.ServerURLHTTPSReposEcosysteMsAPIV1
	DefaultAdvisoriesServer = advisories.ServerURLHTTPSAdvisoriesEcosysteMsAPIV1
	DefaultCommitsServer    = commits.ServerURLHTTPSCommitsEcosysteMsAPIV1
	DefaultIssuesServer     = issues.ServerURLHTTPSIssuesEcosysteMsAPIV1
	DefaultTimeout          = 30 * time.Second
	MaxBulkLookupSize       = 100
)

Variables

This section is empty.

Functions

func PURLToName 

func PURLToName(purl packageurl.PackageURL) string

PURLToName converts a PURL to the ecosyste.ms package name format.

func PURLToRegistry 

func PURLToRegistry(purl packageurl.PackageURL) string

PURLToRegistry converts a PURL type to the ecosyste.ms registry name.

func ParsePURL 

func ParsePURL(s string) (packageurl.PackageURL, error)

ParsePURL parses a PURL string.

func SupportedPURLTypes 

func SupportedPURLTypes() []string

SupportedPURLTypes returns all PURL types that have registry mappings.

Types

type Client 

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

func NewClient 

func NewClient(userAgent string, opts ...Option) (*Client, error)

NewClient creates a new ecosyste.ms API client. The userAgent parameter is required and should identify your application.

func (*Client) BulkLookup 

func (c *Client) BulkLookup(ctx context.Context, purls []string) (map[string]*packages.PackageWithRegistry, error)

BulkLookup looks up multiple packages by PURL. Returns a map keyed by PURL with package data. PURLs are processed in batches of the configured size (defaults to MaxBulkLookupSize). Use WithBatchSize to lower the batch size when the server rejects larger requests.

func (*Client) GetAdvisoriesByRepoURL added in v0.3.0 

func (c *Client) GetAdvisoriesByRepoURL(ctx context.Context, repositoryURL string, maxItems int) ([]advisories.Advisory, error)

GetAdvisoriesByRepoURL returns advisories associated with a source repository.

func (*Client) GetAllVersions 

func (c *Client) GetAllVersions(ctx context.Context, registry, name string) ([]packages.Version, error)

GetAllVersions gets all versions of a package.

func (*Client) GetAllVersionsPURL 

func (c *Client) GetAllVersionsPURL(ctx context.Context, purl packageurl.PackageURL) ([]packages.Version, error)

GetAllVersionsPURL gets all versions for a package using a PURL.

func (*Client) GetCommitsSummary added in v0.3.0 

func (c *Client) GetCommitsSummary(ctx context.Context, repositoryURL string) (*commits.Repository, error)

GetCommitsSummary looks up commit summary metadata for a source repository.

func (*Client) GetDependentPackages added in v0.3.0 

func (c *Client) GetDependentPackages(ctx context.Context, registry, name string, maxItems int) ([]packages.Package, error)

GetDependentPackages returns packages that depend on registry/name.

func (*Client) GetIssuesSummary added in v0.3.0 

func (c *Client) GetIssuesSummary(ctx context.Context, repositoryURL string) (*issues.Repository, error)

GetIssuesSummary looks up issue and pull-request summary metadata for a source repository.

func (*Client) GetRepository 

func (c *Client) GetRepository(ctx context.Context, url string) (*repos.Repository, error)

GetRepository looks up a repository by URL.

func (*Client) GetVersion 

func (c *Client) GetVersion(ctx context.Context, registry, name, version string) (*packages.VersionWithDependencies, error)

GetVersion gets a specific version of a package.

func (*Client) GetVersionPURL 

func (c *Client) GetVersionPURL(ctx context.Context, purl packageurl.PackageURL) (*packages.VersionWithDependencies, error)

GetVersionPURL gets a specific version using a PURL.

func (*Client) ListRegistries 

func (c *Client) ListRegistries(ctx context.Context) ([]packages.Registry, error)

ListRegistries returns all available registries.

func (*Client) Lookup 

func (c *Client) Lookup(ctx context.Context, purl string) (*packages.PackageWithRegistry, error)

Lookup looks up a single package by PURL.

func (*Client) LookupByRegistryAndName 

func (c *Client) LookupByRegistryAndName(ctx context.Context, registry, name string) (*packages.Package, error)

LookupByRegistryAndName looks up a package by registry and name.

func (*Client) LookupPURL 

func (c *Client) LookupPURL(ctx context.Context, purl packageurl.PackageURL) (*packages.Package, error)

LookupPURL looks up a package by its PURL using the registry/name endpoint. This is useful when you need the full Package type rather than PackageWithRegistry.

func (*Client) LookupPackagesByPURL added in v0.3.0 

func (c *Client) LookupPackagesByPURL(ctx context.Context, purl string) ([]packages.PackageWithRegistry, error)

LookupPackagesByPURL looks up package records matching a PURL.

func (*Client) LookupPackagesByRepositoryURL added in v0.3.0 

func (c *Client) LookupPackagesByRepositoryURL(ctx context.Context, repositoryURL string, maxItems int) ([]packages.PackageWithRegistry, error)

LookupPackagesByRepositoryURL looks up package records published from a source repository.

type Option 

type Option func(*clientConfig)

func WithAPIKey 

func WithAPIKey(key string) Option

WithAPIKey sets the API key for authenticated requests. This provides higher rate limits and access to additional features.

func WithAdvisoriesServer added in v0.3.0 

func WithAdvisoriesServer(server string) Option

func WithBatchSize added in v0.2.0 

func WithBatchSize(size int) Option

WithBatchSize sets the number of PURLs sent per BulkLookup request. Values <= 0 or greater than MaxBulkLookupSize fall back to MaxBulkLookupSize. Useful for clients that need to stay within stricter server-side limits.

func WithCommitsServer added in v0.3.0 

func WithCommitsServer(server string) Option

func WithFrom 

func WithFrom(email string) Option

WithFrom sets the From header (email address) for API requests. This helps ecosyste.ms identify who is making requests.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

func WithIssuesServer added in v0.3.0 

func WithIssuesServer(server string) Option

func WithPackagesServer 

func WithPackagesServer(server string) Option

func WithReposServer 

func WithReposServer(server string) Option

Source Files

View all Source files

Directories

Path Synopsis
Package advisories provides primitives to interact with the openapi HTTP API.
 Package advisories provides primitives to interact with the openapi HTTP API.
Package commits provides primitives to interact with the openapi HTTP API.
 Package commits provides primitives to interact with the openapi HTTP API.
Package issues provides primitives to interact with the openapi HTTP API.
 Package issues provides primitives to interact with the openapi HTTP API.
Package packages provides primitives to interact with the openapi HTTP API.
 Package packages provides primitives to interact with the openapi HTTP API.
Package repos provides primitives to interact with the openapi HTTP API.
 Package repos provides primitives to interact with the openapi HTTP API.

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.