plainrouter

README

PlainRouter Go SDK

The official Go SDK for the PlainRouter Signals Conversion API. The root package provides a compact, idiomatic entry point; the complete generated contract is available from github.com/plainrouter/sdk-go/openapi.

Install

go get github.com/plainrouter/sdk-go@latest

Authenticate

Create one client with your PlainRouter bearer token:

package main

import (
	"context"
	"log"

	plainrouter "github.com/plainrouter/sdk-go"
)

func main() {
	client := plainrouter.New("YOUR_TOKEN")

	report, _, err := client.Operations.GetEmqReport(context.Background()).Execute()
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("%+v", report)
}

Keep tokens out of source control; load them from your environment or secret manager.

Pass an empty token to use zero-auth synthetic sandbox operations. Applications that need generated wire models, request builders, or low-level configuration can use client.OpenAPI() or import the openapi subpackage directly.

Migrating from v0.5

The generated contract moved from the root package to github.com/plainrouter/sdk-go/openapi. Existing NewConfiguration, NewAPIClient, and ContextAccessToken calls remain as deprecated migration helpers. Code that names generated request or response types should import the openapi subpackage and change the qualifier from plainrouter to openapi.

Contract and generation

• API contract: signed OpenAPI 0.5.0
• Generator: OpenAPI Generator 7.25.0, checksum-pinned by scripts/generate.sh
• Module path: github.com/plainrouter/sdk-go
• Documentation: plainrouter.com/docs

Run scripts/generate.sh to regenerate the openapi subpackage and scripts/check-generated.sh to verify that committed output matches the signed contract. The root package is repository-owned and intentionally small.

License

Apache-2.0

Documentation

Overview

Package plainrouter provides the official Go client for the PlainRouter Signals Conversion API.

Getting started

Create one Client and reuse it. New targets the production PlainRouter API by default and applies the bearer token to every request:

client := plainrouter.New(os.Getenv("PLAINROUTER_TOKEN"))
report, response, err := client.Operations.GetEmqReport(context.Background()).Execute()

Keep tokens out of source code and load them from an environment variable or secret manager. Most methods return a decoded result, the underlying HTTP response, and an error. Inspect the response when handling API errors or reading response metadata.

API groups

Client exposes three service groups:

• Client.Events submits conversion events and reads event delivery state.
• Client.Operations provides reporting, reconciliation, replay, deletion, and destination test operations.
• Client.Sandbox discovers and validates isolated synthetic sandbox events without granting access to production data.

The complete generated contract is available from the github.com/plainrouter/sdk-go/openapi subpackage and through Client.OpenAPI.

See the PlainRouter documentation for authentication, consent-aware event shapes, sandbox usage, and operational guidance.

Example

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	plainrouter "github.com/plainrouter/sdk-go"
)

func main() {
	client := plainrouter.New(os.Getenv("PLAINROUTER_TOKEN"))

	report, response, err := client.Operations.GetEmqReport(context.Background()).Execute()
	if response != nil {
		defer response.Body.Close()
	}
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v\n", report)
}

Index

• Variables
• func NewAPIClient(configuration *openapi.Configuration) *openapi.APIClient
• func NewConfiguration() *openapi.Configuration
• type Client
  • func New(token string, options ...Option) *Client
  • func (client *Client) OpenAPI() *openapi.APIClient
• type Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithUserAgent(userAgent string) Option

Examples

• Package

Variables

var ContextAccessToken = openapi.ContextAccessToken

ContextAccessToken is the generated client's bearer-token context key.

Deprecated: create a curated client with New, which applies its token to every request automatically.

Functions

func NewAPIClient

func NewAPIClient(configuration *openapi.Configuration) *openapi.APIClient

NewAPIClient creates the complete generated client.

Deprecated: use New for the curated entry point or import the github.com/plainrouter/sdk-go/openapi package directly.

func NewConfiguration

func NewConfiguration() *openapi.Configuration

NewConfiguration creates low-level generated client configuration.

Deprecated: use New with WithBaseURL, WithHTTPClient, or WithUserAgent.

Types

type Client

type Client struct {
	Events     *openapi.EventAPIService
	Operations *openapi.OperationsAPIService
	Sandbox    *openapi.SandboxAPIService
	// contains filtered or unexported fields
}

Client is the curated entry point for the PlainRouter API.

Events, Operations, and Sandbox expose the generated service groups without placing every generated model and accessor in the root package index.

func New

func New(token string, options ...Option) *Client

New creates a PlainRouter client. Pass an empty token for the zero-auth synthetic sandbox operations.

func (*Client) OpenAPI

func (client *Client) OpenAPI() *openapi.APIClient

OpenAPI returns the complete generated client for advanced use cases.

type Option

type Option func(*openapi.Configuration)

Option configures a Client created by New.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the default PlainRouter API base URL. It is intended for tests, proxies, and self-hosted compatible endpoints.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient supplies the HTTP client used for requests. A nil client is ignored and leaves the standard HTTP client in place.

func WithUserAgent

func WithUserAgent(userAgent string) Option

WithUserAgent overrides the generated client's default User-Agent header.