codeatlas-sdk-go

Official Go client for the public CodeAtlas API. Standard library only, no dependencies. Homepage: https://codeatlas.com.br · API docs: https://codeatlas.com.br/docs · OpenAPI: https://codeatlas.com.br/openapi.json

Sibling SDKs: JavaScript · Python

Install

go get github.com/codeatlasdev/codeatlas-sdk-go

Requires Go 1.23 or newer.

Read the catalog (no authentication)

package main

import (
	"context"
	"fmt"
	"log"

	codeatlas "github.com/codeatlasdev/codeatlas-sdk-go"
)

func main() {
	ctx := context.Background()
	client := codeatlas.New() // base URL defaults to https://codeatlas.com.br/api/v1

	page, err := client.Services.List(ctx, &codeatlas.ListParams{Limit: 20})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(page.Count, page.Data[0].Name, page.NextCursor)

	// Iterate every service, following next_cursor.
	for svc, err := range client.Services.All(ctx, nil) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(svc.Slug)
	}

	svc, err := client.Services.Get(ctx, "zelvo-ai")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(svc.Name, svc.DeliveryTimeline)

	// Up to 50 slugs in one call. Unknown slugs are 404 items, not errors.
	results, _ := client.Services.Batch(ctx, []string{"zelvo-ai", "nope"})
	fmt.Println(results[0].Status, results[1].Status) // 200 404

	// Client-side filter: the API has no search endpoint.
	hits, _ := client.Services.Search(ctx, "whatsapp")
	fmt.Println(len(hits))

	health, _ := client.Health(ctx)
	fmt.Println(health.Status) // ok
}

Errors

Every non-2xx response is an *codeatlas.APIError carrying the API's error.code, error.message and error.hint. OAuth errors (invalid_client, ...) use the same type.

_, err := client.Services.Get(ctx, "nope")

var apiErr *codeatlas.APIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.Status, apiErr.Code, apiErr.Message, apiErr.Hint)
	// 404 not_found ... ...
}

codeatlas.IsNotFound(err)    // true
codeatlas.IsRateLimited(err) // 429; apiErr.RetryAfter has the Retry-After wait

Rate limits

Every response under /api/v1 carries RateLimit and RateLimit-Policy (IETF draft); the legacy X-RateLimit-* headers are used as a fallback. The client keeps the latest values, and a failed call carries them on the error:

rl := client.LastRateLimit()
fmt.Println(rl.Policy, rl.Remaining, "of", rl.Limit, "per", rl.Window, "- resets in", rl.Reset)
// read 119 of 120 per 1m0s - resets in 36s

Write calls (OAuth 2.0 client credentials)

Contact requests and exports need a Bearer token. Register a client once (RFC 7591), store the secret (it is shown once) and pass it to New. The client fetches the token and caches it until shortly before it expires.

creds, err := codeatlas.Register(ctx, "my-agent")
if err != nil {
	log.Fatal(err)
}
client := codeatlas.New(codeatlas.WithCredentials(creds.ClientID, creds.ClientSecret))

receipt, err := client.ContactRequests.Create(ctx, codeatlas.ContactRequestInput{
	Name:        "Ana Souza",
	Email:       "ana@example.com",
	Message:     "Quero um diagnóstico do meu atendimento.",
	ServiceSlug: "zelvo-ai",
}, codeatlas.WithIdempotencyKey("a-unique-key-per-intent")) // 8 to 128 printable ASCII; makes retries safe
fmt.Println(receipt.ID, receipt.Status) // cr_..., received

Only send a contact request after the person asked you to and gave you their name and email. Limit: 5 per hour per OAuth client.

Exports

job, err := client.Exports.Create(ctx, codeatlas.ExportCSV) // ExportJSONL | ExportCSV | ExportMD; 10 per hour per client
if err != nil {
	log.Fatal(err)
}
if _, err := client.Exports.Wait(ctx, job.ID, nil); err != nil { // polls every 1s, gives up after 60s
	log.Fatal(err)
}
file, err := client.Exports.Download(ctx, job.ID) // []byte

Sandbox

The sandbox serves the same paths and OAuth flow with fixture data: writes are validated, nothing is stored or sent.

client := codeatlas.New(
	codeatlas.WithBaseURL(codeatlas.SandboxBaseURL),
	codeatlas.WithCredentials(creds.ClientID, creds.ClientSecret),
)

The token is requested with resource set to the client's base URL, so the same credentials work for both environments.

Options

Option	Purpose
WithBaseURL(url)	API root, e.g. codeatlas.SandboxBaseURL
WithCredentials(id, secret)	OAuth client credentials for write calls
WithHTTPClient(*http.Client)	Custom timeout, proxy or transport (default timeout 15s)
WithOrigin(url)	Origin of /oauth2/* (tests only)

Development

go vet ./...
go test ./...          # includes live read tests against https://codeatlas.com.br
go test -short ./...   # offline: skips the live tests

Releases: push a tag vX.Y.Z. A public repo with go.mod and a semver tag is a published Go module.

MIT licensed.