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.

Plainrouter is the paid ads platform for developers and agents. Its hosted Meta Ads MCP server lets Claude, ChatGPT, Codex, Cursor and other MCP clients read a Meta ad account and propose changes that pass policy checks. MCP setup, Agent Skills and the other SDKs live in plainrouter/sdk.

Install

go get github.com/plainrouter/sdk-go@v0.7.1

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 (core main 4e2af005e84e21e599189b7965556cbdde08f09f)
• 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. Its constructors reject JSON booleans in integer fields and unknown keys in closed request objects before sending, including values supplied through permissive maps. These guards are generated from the signed spec; numbers and numeric strings are preserved.

The six Actions and Launch list operations accept int64 pages through 10^16. Leave page unset to omit it and use the server default of page 1. The server also accepts integer strings; the Go setters take integers. See CHANGELOG.md for the complete contract delta.

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. Launcher import uses this URL with a trailing /api/v1 removed.

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.