Go SDK for the typeship API

The Go client for typeship's own API. Generated by typeship from its own spec, so it is also a sample of what your Go users get.

github.com/typeship-ax/go is the Go SDK for the typeship API, generated by typeship from its own OpenAPI spec. It has the same shape as every Go SDK typeship generates: net/http only, context-first methods, (T, error) returns, typed error structs, iterators for pagination, and gofmt-clean source. If you want to see what your Go users will get before you generate anything, read this module.

Install

go get github.com/typeship-ax/go

Go 1.21 or newer. go.mod has no require block.

Create a client

The module path ends in go, but the package it declares is typeship, which is the identifier the import binds and the one you type:

import "github.com/typeship-ax/go"

client, err := typeship.New(typeship.WithBearerToken(os.Getenv("TYPESHIP_TOKEN")))
if err != nil {
	return err
}

The key comes from the console under api keys. Pass it, or set TYPESHIP_TOKEN. New takes the same options as any generated Go client: WithBaseURL, WithTimeout, WithMaxRetries, WithHTTPClient, WithOnRequest, WithOnResponse, WithOnError, WithDebug, and WithValidation. See Go.

Generate a package

Generate.Run runs the generator on a spec and returns the files. Nothing is stored. The free plan generates the first 25 operations; paid plans generate the whole spec:

result, err := client.Generate.Run(ctx, &typeship.GenerateRunParams{
	Spec:      typeship.SpecInput{URL: typeship.Ptr("https://api.acme.example.com/openapi.json")},
	Platforms: []string{"sdk", "cli"},
	Language:  typeship.Ptr("go"),
})
if err != nil {
	return err
}
for _, file := range result.Files {
	path := filepath.Join("out", file.Path)
	os.MkdirAll(filepath.Dir(path), 0o755)
	os.WriteFile(path, []byte(file.Content), 0o644)
}
fmt.Println(*result.Meta.OperationCount, "operations")

Work with projects

project, err := client.Projects.Create(ctx, &typeship.ProjectsCreateParams{
	Name:      "Acme API",
	SpecURL:   typeship.Ptr("https://api.acme.example.com/openapi.json"),
	Platforms: []string{"sdk", "cli", "mcp"},
	Languages: []string{"typescript", "go"},
	Destinations: map[string]typeship.Destination{
		"typescript": {Repo: typeship.Ptr("acme/acme-node")},
		"go":         {Repo: typeship.Ptr("acme/acme-go")},
	},
	AutoRegen: typeship.Ptr(true),
})
if err != nil {
	return err
}

// Regenerate on demand. Each entry is a Generation or a GenerationFailure,
// so the item is a union with an accessor per variant.
generations, err := client.Projects.Generate(ctx, project.ID)
if err != nil {
	return err
}
for _, item := range generations.Data {
	if generation, err := item.AsGeneration(); err == nil && generation.Status == "succeeded" {
		fmt.Println(*generation.Language, *generation.Meta.FileCount)
	}
}

// Walk history: the iterator fetches every page.
it := client.Projects.ListGenerations(ctx, project.ID, nil)
for it.Next() {
	generation := it.Value()
	fmt.Println(generation.CreatedAt, generation.Trigger, generation.Status)
}
if err := it.Err(); err != nil {
	return err
}

Every method

Service	Methods
`Generate`	`Run(ctx, params)`
`Projects`	`List(ctx, params)`, `Create(ctx, params)`, `Get(ctx, id)`, `Update(ctx, id, params)`, `Delete(ctx, id)`, `Generate(ctx, id)`, `ListGenerations(ctx, id, params)`
`Generations`	`Get(ctx, id)`, `GetFile(ctx, id, params)`
`SpecVersions`	`List(ctx, projectID, params)`, `Get(ctx, id)`, `GetContent(ctx, id)`
`Account`	`Me(ctx)`
`Usage`	`Retrieve(ctx)`
`APIKeys`	`List(ctx, params)`, `Revoke(ctx, id)`

Every method takes variadic RequestOptions last. Struct fields carry the API's snake_case names in their JSON tags. api.md inside the module is the complete reference, and the API reference has every schema.

Errors

Every method returns (T, error). Each documented status has its own type, and all of them unwrap to *APIError:

_, err := client.Projects.Generate(ctx, "prj_...")

var payment *typeship.PaymentRequiredError
var notFound *typeship.NotFoundError
switch {
case errors.As(err, &payment):
	// free plan allowance used up; payment.Message says so
case errors.As(err, &notFound):
	// no such project on this account
}

See Errors for the envelope and codes.

Go