productboard

README

Productboard Go SDK

A thin, read-only Go SDK for the ProductBoard REST API v2.

Scope (v0.1)

ProductBoard publishes an official OpenAPI 3.1.1 spec — vendored here at openapi/entities.json (see openapi/SOURCE.md for provenance) and used to generate internal/api via ogen.

This SDK covers just enough of ProductBoard's generic Entities API to read Features, Releases, and Objectives:

• GetFeature / ListFeatures
• GetRelease / ListReleases
• GetObjective / ListObjectives

Read-only — no create/update/delete. ProductBoard's other APIs (Notes, Teams, Members, Webhooks, Analytics, Jira/Plugin Integrations) aren't covered. Built primarily to back a github.com/grokify/omniroadmap-core Provider adapter (see the omniroadmap/ subpackage) — grow it as real need arises, same as any other package in this ecosystem.

ProductBoard's dynamic field model

ProductBoard models Features/Releases/Objectives/etc. as generic, workspace- configurable Entities with a fields map keyed by field name, where each value's shape depends on the field's type (text, number, date, status, member, single/multi-select, timeframe, ...). The spec's EntityFieldValue schema is an 18-way undiscriminated anyOf across every possible shape, which ogen can't synthesize a typed Go sum type for — so it's patched to opaque JSON at codegen time (see openapi/SOURCE.md), and entity.go's field* helpers do the actual typing by inspecting each value's shape at runtime. Feature/Release/Objective expose only the common fields (name, description, status, owner, tags, timeframe, timestamps) as typed struct fields — anything else in an entity's fields map isn't currently surfaced.

Quick start

client, err := productboard.NewClient(
    productboard.WithAPIToken(os.Getenv("PRODUCTBOARD_API_TOKEN")),
)
if err != nil {
    log.Fatal(err)
}

features, err := client.ListFeatures(ctx)
if err != nil {
    log.Fatal(err)
}
for _, f := range features.Features {
    fmt.Println(f.Name, f.Status)
}

Development

go build ./...
go vet ./...
golangci-lint run ./...
go test ./...

To regenerate internal/api from the currently-vendored spec:

make generate

To deliberately re-fetch a newer spec (review the diff before regenerating):

make update-spec

Documentation

Overview

Package productboard is a Go SDK for the ProductBoard REST API v2 (https://developer.productboard.com/reference/introduction). ProductBoard publishes an official OpenAPI spec, vendored at openapi/entities.json (see openapi/SOURCE.md for provenance) and used to generate internal/api via ogen — see generate.sh / make generate.

Scope is deliberately thin for v0.1: read-only access to Features, Releases, and Objectives via ProductBoard's generic Entities API, just enough to back an github.com/grokify/omniroadmap-core Provider adapter (see the omniroadmap/ subpackage). Full CRUD across ProductBoard's other APIs (Notes, Teams, Members, Webhooks, Analytics, Integrations) is out of scope until there's real need for it.

Index

• Constants
• Variables
• func IsNotFound(err error) bool
• func IsRateLimited(err error) bool
• func IsUnauthorized(err error) bool
• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(opts ...Option) (*Client, error)
  • func (c *Client) API() *api.Client
  • func (c *Client) BaseURL() string
  • func (c *Client) GetFeature(ctx context.Context, id string) (*Feature, error)
  • func (c *Client) GetObjective(ctx context.Context, id string) (*Objective, error)
  • func (c *Client) GetRelease(ctx context.Context, id string) (*Release, error)
  • func (c *Client) ListFeatures(ctx context.Context, opts ...ListOption) (*FeatureList, error)
  • func (c *Client) ListObjectives(ctx context.Context, opts ...ListOption) (*ObjectiveList, error)
  • func (c *Client) ListReleases(ctx context.Context, opts ...ListOption) (*ReleaseList, error)
• type Config
• type Feature
• type FeatureList
• type ListOption
  • func WithNameFilter(name string) ListOption
  • func WithPageCursor(cursor string) ListOption
• type ListOptions
• type Member
• type Objective
• type ObjectiveList
• type Option
  • func WithAPIToken(token string) Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithTimeout(timeout time.Duration) Option
• type Release
• type ReleaseList
• type SelectOption
• type Status
• type Timeframe

Constants

const (
	// SDKVersion is the version of this SDK.
	SDKVersion = "0.1.0"

	// SDKName is the name of this SDK.
	SDKName = "productboard-go"
)

Variables

var (
	ErrMissingAPIToken = errors.New("productboard: api token is required")
)

Sentinel errors for configuration and validation.

Functions

func IsNotFound

func IsNotFound(err error) bool

IsNotFound returns true if the error indicates a 404 Not Found response.

func IsRateLimited

func IsRateLimited(err error) bool

IsRateLimited returns true if the error indicates a 429 Too Many Requests response.

func IsUnauthorized

func IsUnauthorized(err error) bool

IsUnauthorized returns true if the error indicates a 401 Unauthorized response.

Types

type APIError

type APIError struct {
	StatusCode int
	Message    string
}

APIError represents an error response from the ProductBoard API.

func (*APIError) Error

func (e *APIError) Error() string

type Client

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

Client provides access to the ProductBoard API.

func NewClient

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

NewClient creates a new ProductBoard client with the given options.

Configuration is loaded in the following order (later values override earlier ones): defaults, PRODUCTBOARD_API_TOKEN environment variable, options passed to NewClient.

func (*Client) API

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

API returns the low-level ogen-generated client for advanced use, for API operations not covered by the high-level wrapper.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL returns the API base URL.

func (*Client) GetFeature

func (c *Client) GetFeature(ctx context.Context, id string) (*Feature, error)

GetFeature retrieves a feature (or subfeature) by ID.

func (*Client) GetObjective

func (c *Client) GetObjective(ctx context.Context, id string) (*Objective, error)

GetObjective retrieves an objective by ID.

func (*Client) GetRelease

func (c *Client) GetRelease(ctx context.Context, id string) (*Release, error)

GetRelease retrieves a release by ID.

func (*Client) ListFeatures

func (c *Client) ListFeatures(ctx context.Context, opts ...ListOption) (*FeatureList, error)

ListFeatures lists features and subfeatures.

func (*Client) ListObjectives

func (c *Client) ListObjectives(ctx context.Context, opts ...ListOption) (*ObjectiveList, error)

ListObjectives lists objectives.

func (*Client) ListReleases

func (c *Client) ListReleases(ctx context.Context, opts ...ListOption) (*ReleaseList, error)

ListReleases lists releases.

type Config

type Config struct {
	// APIToken is your ProductBoard API token (Personal Access Token).
	APIToken string

	// HTTPClient is the HTTP client to use for requests. If nil, a new
	// *http.Client with Timeout applied is constructed. If set, it's used
	// as-is — Timeout is not applied to a caller-supplied client.
	HTTPClient *http.Client

	// Timeout is the request timeout. Default is 60 seconds.
	Timeout time.Duration

	// BaseURL overrides the default API URL. If empty, defaultBaseURL is used.
	BaseURL string
}

Config holds the configuration for the Client.

type Feature

type Feature struct {
	ID          string
	Type        string // "feature" or "subfeature"
	Name        string
	Description string
	Status      *Status
	Owner       *Member
	Tags        []SelectOption
	Timeframe   *Timeframe
	ParentID    string // component/feature this belongs to, if any
	Archived    bool
	CreatedAt   *time.Time
	UpdatedAt   *time.Time
}

Feature represents a ProductBoard feature or subfeature.

type FeatureList

type FeatureList struct {
	Features   []Feature
	NextCursor string
}

FeatureList is a page of features, with a cursor for the next page.

type ListOption

type ListOption func(*ListOptions)

ListOption configures a list operation.

func WithNameFilter

func WithNameFilter(name string) ListOption

WithNameFilter filters results by entity name.

func WithPageCursor

func WithPageCursor(cursor string) ListOption

WithPageCursor sets the pagination cursor (from a previous ListResult's NextCursor).

type ListOptions

type ListOptions struct {
	PageCursor string
	Name       string
}

ListOptions configures list operations. ProductBoard's Entities API uses cursor-based pagination, not page numbers — PageCursor comes from the previous response's NextCursor.

type Member

type Member struct {
	ID    string
	Email string
}

Member is a workspace member reference (owner, assignee, etc.).

type Objective

type Objective struct {
	ID          string
	Name        string
	Description string
	Status      *Status
	Owner       *Member
	Timeframe   *Timeframe
	Archived    bool
	CreatedAt   *time.Time
	UpdatedAt   *time.Time
}

Objective represents a ProductBoard objective (OKR-style goal).

type ObjectiveList

type ObjectiveList struct {
	Objectives []Objective
	NextCursor string
}

ObjectiveList is a page of objectives, with a cursor for the next page.

type Option

type Option func(*Config)

Option configures the Client.

func WithAPIToken

func WithAPIToken(token string) Option

WithAPIToken sets the ProductBoard API token.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the default API URL.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom HTTP client.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the request timeout.

type Release

type Release struct {
	ID        string
	Name      string
	Status    *Status
	Timeframe *Timeframe
	Archived  bool
	CreatedAt *time.Time
	UpdatedAt *time.Time
}

Release represents a ProductBoard release.

type ReleaseList

type ReleaseList struct {
	Releases   []Release
	NextCursor string
}

ReleaseList is a page of releases, with a cursor for the next page.

type SelectOption

type SelectOption struct {
	ID    string
	Name  string
	Color string
}

SelectOption is a single value from a single/multi-select custom field.

type Status

type Status struct {
	ID   string
	Name string
}

Status is a workspace-configurable status value (id + display name), shared by all entity types that have one (features, releases, etc.).

type Timeframe

type Timeframe struct {
	StartDate   *time.Time
	EndDate     *time.Time
	Granularity string
}

Timeframe is a start/end date range with an optional granularity (year/quarter/month/day), used for initiative/feature/release planning.