dtrpg

README

dtrpg-sdk.go

A Go SDK for the DriveThruRPG API.

Provides configuration, authentication/session lifecycle, and a library client for listing orders, product lists, and preparing downloads.

Requires Go 1.24+.

Installation

go get github.com/pilgrimagesoftware/dtrpg-sdk.go

Building from source

This repository uses the dtrpg-api repository as a submodule (API/). The openapi package's go:generate directive reads API/openapi.yaml and writes build-time OpenAPI metadata (openapi.DefaultServerURL, openapi.Operations) into openapi/generated.go. Clone with submodules, or initialize them after cloning:

git clone --recursive https://github.com/pilgrimagesoftware/dtrpg-sdk.go.git

# or, if already cloned:
git submodule update --init --recursive

Regenerate the metadata after API/openapi.yaml changes:

go generate ./...

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	dtrpg "github.com/pilgrimagesoftware/dtrpg-sdk.go"
)

func main() {
	sdk := dtrpg.NewSdkWithConfig(dtrpg.NewConfig("my-app-key"))

	// After receiving an auth response from the API:
	response := dtrpg.NewAuthTokenResponse("jwt-token", "refresh-token", 1_800_000_000)
	session, err := sdk.ApplyAuthResponse(response)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(session.Token())

	// Create an authenticated library client:
	client, err := sdk.LibraryClient()
	if err != nil {
		log.Fatal(err)
	}
	products, err := client.ListOrderProducts(context.Background(), dtrpg.LibraryItemsParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(products)
}

See the package documentation (go doc) for the full API reference, including Config, AuthSession/AuthState, LibraryClient, and the library model types (OrderProductItem, ProductListItem, etc.).

Development

go build ./...
go vet ./...
gofmt -l .
golangci-lint run
go test -race ./...

Release Process

See RELEASE.md.

License

MIT — see LICENSE.md.

Documentation

Overview

Package dtrpg is the root of the DriveThruRPG Go SDK. It wires together configuration (aliased from the library package), the authentication session lifecycle (package auth), and the library API client (package library) behind a single Sdk entry point.

Index

• Constants
• Variables
• type AuthSession
• type AuthSessionError
• type AuthState
• type AuthTokenResponse
  • func NewAuthTokenResponse(token, refreshToken string, refreshTokenTTL uint64) AuthTokenResponse
• type Config
  • func NewConfig(applicationKey string) Config
  • func NewConfigWithBaseURL(applicationKey, baseURL string) Config
• type LibraryClient
• type LibraryItemsParams
• type PageParams
• type Sdk
  • func NewSdk() *Sdk
  • func NewSdkWithConfig(config Config) *Sdk
  • func (s *Sdk) ApplyAuthResponse(response AuthTokenResponse) (*auth.AuthSession, error)
  • func (s *Sdk) ClearSession()
  • func (s *Sdk) Config() *Config
  • func (s *Sdk) Configure(config Config)
  • func (s *Sdk) InvalidateSession(err AuthSessionError) (AuthSessionError, error)
  • func (s *Sdk) LibraryClient() (*library.Client, error)
  • func (s *Sdk) RequireConfig() (*Config, error)
  • func (s *Sdk) RequireSession() (*auth.AuthSession, error)
  • func (s *Sdk) Session() *auth.AuthSession
• type SessionTransition

Constants

const DefaultAPIVersion = library.DefaultAPIVersion

DefaultAPIVersion is the API version path segment used when no custom version is provided.

const DefaultBaseURL = library.DefaultBaseURL

DefaultBaseURL is the production DriveThruRPG API base URL used when no custom URL is provided.

Variables

var ErrUnauthenticated = errors.New("dtrpg: sdk does not have an authenticated session")

ErrUnauthenticated indicates the SDK has no active authentication session.

Obtain a session by calling Sdk.ApplyAuthResponse with a successful token response from the API.

var ErrUnconfigured = errors.New("dtrpg: sdk is not configured")

ErrUnconfigured indicates the SDK has not been configured with a Config yet.

Call Sdk.Configure or construct the SDK with NewSdkWithConfig before making API calls.

Types

type AuthSession

type AuthSession = auth.AuthSession

AuthSession is an active authentication session with the DriveThruRPG API. See auth.AuthSession for field documentation.

type AuthSessionError

type AuthSessionError = auth.AuthSessionError

AuthSessionError is a structured authentication error returned by the DriveThruRPG API. See auth.AuthSessionError.

type AuthState

type AuthState = auth.AuthState

AuthState is the authentication failure state reported by the DriveThruRPG API. See auth.AuthState.

type AuthTokenResponse

type AuthTokenResponse = auth.AuthTokenResponse

AuthTokenResponse is the raw authentication token payload returned by the DriveThruRPG API. See auth.AuthTokenResponse.

func NewAuthTokenResponse

func NewAuthTokenResponse(token, refreshToken string, refreshTokenTTL uint64) AuthTokenResponse

NewAuthTokenResponse constructs a new AuthTokenResponse from its fields.

type Config

type Config = library.Config

Config holds the application-level settings required to make requests to the DriveThruRPG API. See library.Config for field documentation; it lives in the library package to avoid an import cycle between this package, auth, and library, and is aliased here for the common single-import call site.

func NewConfig

func NewConfig(applicationKey string) Config

NewConfig creates a Config targeting the production API with the given applicationKey.

func NewConfigWithBaseURL

func NewConfigWithBaseURL(applicationKey, baseURL string) Config

NewConfigWithBaseURL creates a Config with a custom baseURL, overriding the production endpoint.

type LibraryClient

type LibraryClient = library.Client

LibraryClient is an authenticated HTTP client for DriveThruRPG library endpoints. See library.Client.

type LibraryItemsParams

type LibraryItemsParams = library.LibraryItemsParams

LibraryItemsParams holds query parameters for the order-products (library items) endpoint. See library.LibraryItemsParams.

type PageParams

type PageParams = library.PageParams

PageParams holds query parameters for paginated collection endpoints. See library.PageParams.

type Sdk

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

Sdk is the DriveThruRPG SDK client.

Sdk coordinates SDK-level configuration and authentication session lifecycle. It must be configured before any authenticated API calls can succeed.

Lifecycle

1. Create an Sdk instance, optionally supplying a Config upfront. 2. After a successful API login, call ApplyAuthResponse to store the session. 3. Use RequireSession to obtain the active session before making requests. 4. Call InvalidateSession when the API reports a session error, or ClearSession to log out.

func NewSdk

func NewSdk() *Sdk

NewSdk creates an unconfigured Sdk instance. Call Configure before making any API calls, or prefer NewSdkWithConfig if the configuration is available at construction time.

func NewSdkWithConfig

func NewSdkWithConfig(config Config) *Sdk

NewSdkWithConfig creates an Sdk instance pre-loaded with the given Config.

func (*Sdk) ApplyAuthResponse

func (s *Sdk) ApplyAuthResponse(response AuthTokenResponse) (*auth.AuthSession, error)

ApplyAuthResponse stores a new authentication session derived from a raw API token response.

Returns ErrUnconfigured if the SDK has not been configured yet. On success, returns the newly stored session.

func (*Sdk) ClearSession

func (s *Sdk) ClearSession()

ClearSession removes the current authentication session without recording an error.

Use this for voluntary log-out flows. For API-reported session failures, prefer InvalidateSession.

func (*Sdk) Config

func (s *Sdk) Config() *Config

Config returns the current configuration, or nil if the SDK is unconfigured.

func (*Sdk) Configure

func (s *Sdk) Configure(config Config)

Configure sets or replaces the SDK's configuration.

This can be called at any time, including after the SDK has been used. Replacing the configuration does not automatically clear an existing session.

func (*Sdk) InvalidateSession

func (s *Sdk) InvalidateSession(err AuthSessionError) (AuthSessionError, error)

InvalidateSession removes the current session and records the API-reported error that caused it.

Returns ErrUnauthenticated if there is no session to invalidate. On success, returns the provided err so callers can inspect or propagate it.

func (*Sdk) LibraryClient

func (s *Sdk) LibraryClient() (*library.Client, error)

LibraryClient creates a library.Client from the current configuration and session.

Returns ErrUnconfigured if the SDK has not been configured, or ErrUnauthenticated if there is no active session.

func (*Sdk) RequireConfig

func (s *Sdk) RequireConfig() (*Config, error)

RequireConfig returns the current configuration, or ErrUnconfigured if absent.

Use this in call chains where a missing config should surface as an error.

func (*Sdk) RequireSession

func (s *Sdk) RequireSession() (*auth.AuthSession, error)

RequireSession returns the current session, or ErrUnauthenticated if absent.

Use this in call chains where a missing session should surface as an error.

func (*Sdk) Session

func (s *Sdk) Session() *auth.AuthSession

Session returns the current authentication session, or nil if unauthenticated.

type SessionTransition

type SessionTransition = auth.SessionTransition

SessionTransition is the outcome of invalidating an AuthSession. See auth.SessionTransition.