sdk

README

Turnkey GO SDK

The Turnkey Go SDK is an early tool for interacting with the Turnkey API.

There is much work to be done, but it is completly usable in its current form. The main thing to keep in mind is that each requests needs to be manually provided the client.Authenticator.

Usage

API key

In order to use the SDK, you will need an API key. When creating API keys, the private key never leaves the local system, but the public key must be registered to your Turnkey account.

The easiest way to manage your API keys is with the Turnkey CLI, but you can also create one using this SDK. See this example.

Example

import (
	"fmt"
	"log"

	"github.com/tkhq/go-sdk"
	"github.com/tkhq/go-sdk/pkg/api/client/sessions"
	"github.com/tkhq/go-sdk/pkg/api/models"
)

func main() {
	// NB: make sure to create and register an API key, first.
	client, err := sdk.New("") // your local API key name
	if err != nil {
		log.Fatal("failed to create new SDK client:", err)
	}

	p := sessions.NewGetWhoamiParams().WithBody(&models.GetWhoamiRequest{
		OrganizationID: client.DefaultOrganization(),
	})

	resp, err := client.V0().Sessions.GetWhoami(p, client.Authenticator)
	if err != nil {
		log.Fatal("failed to make WhoAmI request:", err)
	}

	fmt.Println("UserID: ", *resp.Payload.UserID)
}

Error Handling

By default, the SDK will wrap Turnkey API error responses inside the returned error. You can inspect the raw API body by type-asserting the error to *runtime.APIError and reading the response body:

if err != nil {
  // log the high-level error using your preferred logger
  log.Printf("failed to make request: %v", err)

  // extract and inspect the raw API response
  if apiErr, ok := err.(*runtime.APIError); ok && apiErr.Response != nil {
    b, _ := io.ReadAll(apiErr.Response.Body())
    log.Printf("Turnkey API raw response: %s", string(b))
  }

  return nil, err
}

Custom Logging

By default, the SDK prints Turnkey API responses to stdout when requests fail. If you’d like to control this output (for example, to send logs to Zap, Logrus, or Datadog), you can provide your own logger:

type myLogger struct{}
func (l *myLogger) Printf(format string, v ...interface{}) {
    log.Printf("[SDK] "+format, v...)
}

client, err := sdk.New(
    sdk.WithAPIKeyName("default"),
    sdk.WithLogger(&myLogger{}), // plug in your logger
)

If no logger is provided, the SDK falls back to fmt.Printf("Turnkey API response: ...") to preserve current behavior.

Development

Changelog and Releases

The SDK uses git-chglog for changelog management and publishes versions to pkg.go.dev.

Commit Conventions

Note: these are not strictly enforced yet, but rather offers general guidelines.

To ensure your changes appear correctly in the changelog, use these commit prefixes:

• feat: for new features
• fix: for bug fixes
• perf: for performance improvements
• refactor: for code refactoring
• docs:, test:, ci: (these are excluded from changelog)

Example: feat(api): add new wallet creation endpoint

Managing Changes

1. Install git-chglog:

   go install github.com/git-chglog/git-chglog/cmd/git-chglog@latest
   

2. Preview changelog for next version:

   make changelog-next v=1.0.0
   

3. Update changelog without releasing:

   make changelog
   

Creating Releases

To prepare a new release:

make prepare-release v=1.0.0

This will generate and update CHANGELOG.md. Please review the changes and manually modify as needed.

Commit and push the changes, get the PR approved, merge, and move to the next step.

To publish a new release (off of main):

make publish-release v=1.0.0

This will:

1. Create a git tag
2. Push changes to GitHub
3. Trigger pkg.go.dev indexing

Note:

• Use semantic versioning (e.g., v1.0.0, v0.1.0-beta)
• New versions appear on pkg.go.dev within a few minutes
• If needed, manually trigger pkg.go.dev indexing:

  GOPROXY=proxy.golang.org go list -m github.com/tkhq/go-sdk@v1.0.0
  

Updating the SDK

With Nix

1. Install Nix: https://nixos.org/download.html
2. Run nix develop to get a new nix shell
3. Update the swagger file in api/ with a new one
4. Run make generate

Without Nix

The following assumes you have Go 1.20 installed locally:

1. Install go-swagger:

go install github.com/go-swagger/go-swagger/cmd/swagger@v0.30.5

1. Update the swagger file in api/ with a new one
2. Run make generate

Note: depending on how you downloaded, your go-swagger may be located in a few locations such as /Users/<your username>/go/bin/swagger or /opt/homebrew/bin/swagger. If both are present, we would recommend using the former, for better version granularity

Custom Templates

While custom templates should be avoided where possible, sometimes it's worth the extra maintenance burden to provide a more streamlined UX. To use a custom template, copy the original template from the go-swagger repo to the templates directory

Current Modifications

// file: schemavalidator.gotmpl

// mod: less verbose enum variants
// note: seems strange, but there's an edgecase with the current logic where '_' is not supported leading to names like AllCapsALLCAPSALLTHETIME
-      {{- $variant := print $gotype (pascalize (cleanupEnumVariant .)) }}
+      {{- $variant := print ( pascalize ( camelcase (printf "%q" . ))) }}

// mod: typed and iterable enum variants
-var {{ camelize .Name }}Enum []interface{}
+var {{ pascalize .Name }}Enum []{{ template "dereffedSchemaType" . }}
-    {{ camelize .Name }}Enum = append({{ camelize .Name }}Enum, v)
+    {{ pascalize .Name }}Enum = append({{ pascalize .Name }}Enum, v)
-  if err := validate.EnumCase(path, location, value, {{ camelize .Name }}Enum, {{ if .IsEnumCI }}false{{ else }}true{{ end }}); err != nil {
+  if err := validate.EnumCase(path, location, value, {{ pascalize .Name }}Enum, {{ if .IsEnumCI }}false{{ else }}true{{ end }}); err != nil {

Documentation

Overview

Package sdk provides a Go SDK with which to interact with the Turnkey API service.

Index

• Constants
• func NewHTTPClient(formats strfmt.Registry) *client.TurnkeyAPI
• func SetClientVersion(inner http.RoundTripper, clientVersion string) http.RoundTripper
• type Authenticator
  • func (auth *Authenticator) AuthenticateRequest(req runtime.ClientRequest, reg strfmt.Registry) (err error)
• type Client
  • func New(options ...OptionFunc) (*Client, error)
  • func (c *Client) DefaultOrganization() *string
  • func (c *Client) V0() *client.TurnkeyAPI
• type Logger
• type OptionFunc
  • func WithAPIKey(apiKey *apikey.Key) OptionFunc
  • func WithAPIKeyName(keyname string) OptionFunc
  • func WithClientVersion(clientVersion string) OptionFunc
  • func WithLogger(logger Logger) OptionFunc
  • func WithRegistry(registry strfmt.Registry) OptionFunc
  • func WithTransportConfig(transportConfig client.TransportConfig) OptionFunc

Constants

const DefaultClientVersion = "go-sdk"

Functions

func NewHTTPClient

func NewHTTPClient(formats strfmt.Registry) *client.TurnkeyAPI

NewHTTPClient returns a new base HTTP API client. Most users will call New() instead. Deprecated: Use New(WithRegistry(formats)) instead.

func SetClientVersion

func SetClientVersion(inner http.RoundTripper, clientVersion string) http.RoundTripper

Types

type Authenticator

type Authenticator struct {
	// Key optionally overrides the globally-parsed APIKeypair with a custom key.
	Key *apikey.Key
}

Authenticator provides a runtime.ClientAuthInfoWriter for use with the swagger API client.

func (*Authenticator) AuthenticateRequest

func (auth *Authenticator) AuthenticateRequest(req runtime.ClientRequest, reg strfmt.Registry) (err error)

AuthenticateRequest implements runtime.ClientAuthInfoWriter. It adds the X-Stamp header to the request based by generating the Stamp with the request body and API key.

type Client

type Client struct {
	// Client is the base HTTP API Client.
	Client *client.TurnkeyAPI

	// Authenticator provides a client option authentication provider which should be attached to every API request as a clientOption.
	Authenticator *Authenticator

	// APIKey is the API key to be used for API request signing.
	APIKey *apikey.Key
}

Client provides a handle by which to interact with the Turnkey API.

func New

func New(options ...OptionFunc) (*Client, error)

New returns a new API Client with the given API key name from the default keystore.

func (*Client) DefaultOrganization

func (c *Client) DefaultOrganization() *string

DefaultOrganization returns the first organization found in the APIKey's set of organizations.

func (*Client) V0

func (c *Client) V0() *client.TurnkeyAPI

V0 returns the raw initial Turnkey API client. WARNING: this is a temporary API which requires a bit more work to use than the one which will be eventually offered.

type Logger

type Logger interface {
	Printf(format string, v ...interface{})
}

Logger defines a minimal logging interface. Compatible with stdlib log.Logger, zap.SugaredLogger, etc.

type OptionFunc

type OptionFunc func(c *config) error

OptionFunc defines a function which sets configuration options for a Client.

func WithAPIKey

func WithAPIKey(apiKey *apikey.Key) OptionFunc

WithAPIKey sets the API key used for this API client. Users would normally use WithAPIKeyName. This offers a lower-level custom API key.

func WithAPIKeyName

func WithAPIKeyName(keyname string) OptionFunc

WithAPIKeyName sets the API key to the key loaded from the local keystore with the provided name.

func WithClientVersion

func WithClientVersion(clientVersion string) OptionFunc

WithClientVersion overrides the client version used for this API client.

func WithLogger

func WithLogger(logger Logger) OptionFunc

WithLogger sets a custom logger for the SDK. Defaults to fmt.Printf if none is provided.

func WithRegistry

func WithRegistry(registry strfmt.Registry) OptionFunc

WithRegistry sets the registry formats used for this API client.

func WithTransportConfig

func WithTransportConfig(transportConfig client.TransportConfig) OptionFunc

WithTransportConfig sets the TransportConfig used for this API client.