Go SDK

# Download the single-file client into a package folder of your module.
mkdir -p atlas && curl -fsSL -o atlas/atlas.go https://atlas.wrxstack.com/sdk/go/atlas.go

# Check it arrived intact.
curl -fsSL -o atlas.go.sha256 https://atlas.wrxstack.com/sdk/go/atlas.go.sha256
(cd atlas && shasum -a 256 -c ../atlas.go.sha256)

package main

import (
	"log"
	"os"

	// The folder you downloaded the client into, inside your own module.
	"your.module/path/atlas"
)

func main() {
	// Read the token from the environment - never hard-code it in source.
	client, err := atlas.NewClient(os.Getenv("ATLAS_TOKEN"))
	if err != nil {
		log.Fatal(err)
	}
	_ = client
}

res, err := client.GetTasks(map[string]string{"limit": "5"})
if err != nil {
	log.Fatal(err)
}

// List endpoints answer an { "items": [...], "nextCursor": ... } envelope.
page := res.(map[string]any)
for _, item := range page["items"].([]any) {
	task := item.(map[string]any)
	fmt.Println(task["id"], task["title"])
}

_, err := client.PostTasks(map[string]any{"title": ""}, nil)

var forbidden *atlas.ForbiddenError
var unauthorized *atlas.UnauthorizedError
var apiErr *atlas.ApiError
switch {
case errors.As(err, &forbidden):
	// 403: the token is missing a scope. Body is the parsed problem+json.
	if body, ok := forbidden.Body.(map[string]any); ok {
		fmt.Println("need scopes:", body["requiredScopes"])
	}
case errors.As(err, &unauthorized):
	// 401: token invalid or revoked - re-authenticate.
	log.Fatal("unauthorized")
case errors.As(err, &apiErr):
	// 409 / 422 / 429: no dedicated type, so branch on Status.
	fmt.Println(apiErr.Status, apiErr.Message)
}

var retryable = map[int]bool{429: true, 500: true, 502: true, 503: true, 504: true}

// retryDelay reports how long to wait, or ok=false to stop retrying.
func retryDelay(err error, attempt int) (time.Duration, bool) {
	var server *atlas.ServerError
	var apiErr *atlas.ApiError
	switch {
	case errors.As(err, &server):
		return backoff(attempt), true // 5xx: transient
	case errors.As(err, &apiErr) && apiErr.Status == 429:
		// The 429 body carries the authoritative retry delay, in seconds.
		if body, ok := apiErr.Body.(map[string]any); ok {
			if rl, ok := body["rateLimit"].(map[string]any); ok {
				if secs, ok := rl["retryAfterSec"].(float64); ok {
					return time.Duration(secs) * time.Second, true
				}
			}
		}
		return backoff(attempt), true
	default:
		return 0, false
	}
}

func backoff(attempt int) time.Duration {
	d := time.Duration(1<<uint(attempt-1)) * time.Second
	if d > 30*time.Second {
		d = 30 * time.Second
	}
	return d + time.Duration(rand.Intn(1000))*time.Millisecond // jitter
}

func withRetries[T any](call func() (T, error), maxAttempts int) (T, error) {
	for attempt := 1; ; attempt++ {
		res, err := call()
		if err == nil {
			return res, nil
		}
		delay, ok := retryDelay(err, attempt)
		if !ok || attempt == maxAttempts {
			var zero T
			return zero, err
		}
		time.Sleep(delay)
	}
}

// The generated client sends a fixed header set and takes no per-call context,
// so attach an Idempotency-Key by composing the write directly. Reuse one key
// across every retry so the API replays (24h) instead of duplicating.
func createTask(ctx context.Context, token, key string, body map[string]any) (map[string]any, error) {
	payload, err := json.Marshal(body)
	if err != nil {
		return nil, err
	}
	req, err := http.NewRequestWithContext(
		ctx, http.MethodPost, "https://api-atlas.wrxstack.com/v1/tasks", bytes.NewReader(payload),
	)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", key)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var created map[string]any
	return created, json.NewDecoder(resp.Body).Decode(&created)
}

// headerTransport adds a static header to every request the client makes.
type headerTransport struct {
	base    http.RoundTripper
	headers map[string]string
}

func (t *headerTransport) RoundTrip(req *http.Request) (*http.Response, error) {
	for k, v := range t.headers {
		req.Header.Set(k, v)
	}
	return t.base.RoundTrip(req)
}

func newClient(token string) (*atlas.Client, error) {
	httpClient := &http.Client{
		Timeout: 30 * time.Second,
		Transport: &headerTransport{
			base:    http.DefaultTransport,
			headers: map[string]string{"X-Request-Source": "atlas-cli"},
		},
	}
	return atlas.NewClient(
		token,
		atlas.WithBaseURL("https://api-atlas.wrxstack.com"), // the default; override for staging
		atlas.WithHTTPClient(httpClient),
	)
}