Requisitos
- Go 1.24 ou mais recente
- Zero dependências externas — o SDK é construído apenas sobre a biblioteca padrão do Go
- Uma chave de API válida — solicite uma no Dashboard da Square Cloud em Minha Conta → Regenerar API/CLI KEY
Instalação
go get github.com/squarecloudofc/sdk-api-go/v2
| Pacote | Caminho de import | Conteúdo |
|---|
rest | github.com/squarecloudofc/sdk-api-go/v2/rest | Client HTTP, interfaces de recursos, opções de requisição, erros, stream SSE |
squarecloud | github.com/squarecloudofc/sdk-api-go/v2/squarecloud | Todos os tipos e structs de requisição/resposta |
Instanciando o client
package main
import (
"fmt"
"os"
"github.com/squarecloudofc/sdk-api-go/v2/rest"
)
func main() {
client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
defer client.Close()
api := rest.New(client)
user, err := api.SelfUser()
if err != nil {
panic(err)
}
fmt.Println(user.Name)
}
rest.NewClient(token, opts...) constrói o client HTTP subjacente; rest.New(client) o encapsula em rest.Rest, a interface que expõe todos os recursos. Sempre use defer client.Close() para liberar conexões ociosas.
Configuração do client (ConfigOpt)
rest.NewClient aceita ConfigOpts opcionais após o token:
| Opção | Padrão | Descrição |
|---|
rest.WithLogger(*slog.Logger) | descartado | Logger estruturado para depurar requisições/respostas |
rest.WithHTTPClient(*http.Client) | timeout de 30s | *http.Client customizado (proxies, transports, timeouts) |
rest.WithURL(string) | https://api.squarecloud.app/v2 | URL base da API |
rest.WithUserAgent(string) | padrão do SDK | Header User-Agent customizado |
client := rest.NewClient(
os.Getenv("SQUARECLOUD_API_KEY"),
rest.WithLogger(slog.Default()),
rest.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)
Módulos
rest.Rest incorpora uma interface por domínio de recurso, além dos métodos de usuário e de status documentados nesta página:
| Interface | Cobertura | Documentação |
|---|
Applications | Gerenciamento, upload, arquivos, envs, snapshots, deploys, rede, tempo real | Gerenciando aplicações |
Databases | Criação, gerenciamento, credenciais e snapshots | Bancos de dados |
Workspaces | Criação, membros, aplicações compartilhadas | Workspaces |
Obtendo o usuário autenticado
api.SelfUser() retorna um squarecloud.User com os detalhes da conta e o plano atual.
user, err := api.SelfUser()
if err != nil {
panic(err)
}
fmt.Println(user.ID) // "abcdef0123456789abcdef01"
fmt.Println(user.Name) // "John Doe"
fmt.Println(user.Email) // "john@example.com"
fmt.Println(user.Locale) // "en-US"
fmt.Println(user.Plan.Name) // ex.: "standard"
fmt.Println(user.Plan.Duration) // duração do plano, ex.: "monthly"
fmt.Println(user.Plan.Memory.Limit) // MB
fmt.Println(user.Plan.Memory.Available) // MB
fmt.Println(user.Plan.Memory.Used) // MB
fmt.Println(user.CreatedAt)
| Campo | Tipo | Descrição |
|---|
ID | string | ID do usuário (24 chars hex) |
Name | string | Nome de exibição |
Email | string | E-mail da conta |
Locale | string | Localidade preferida, ex.: "en-US" |
Plan | squarecloud.UserPlan | Name, Memory{Limit, Available, Used} (MB) e Duration |
CreatedAt | string | Data de criação da conta |
Listando suas aplicações e bancos de dados
api.GetApplications() e api.GetDatabases() listam tudo que você possui através do endpoint /users/me, retornando descritores compactos squarecloud.UserApplication / squarecloud.UserDatabase:
apps, err := api.GetApplications()
if err != nil {
panic(err)
}
for _, app := range apps {
fmt.Printf("%s (%s) — %dMB\n", app.Name, app.ID, app.RAM)
}
dbs, err := api.GetDatabases()
if err != nil {
panic(err)
}
for _, db := range dbs {
fmt.Printf("%s (%s)\n", db.Name, db.ID)
}
GetApplication / GetDatabase — veja Gerenciando aplicações e Bancos de dados.
Listando histórico de snapshots da conta
api.UserSnapshots(scope) retorna todos os snapshots que você possui para um determinado domínio:
appSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeApplications)
if err != nil {
panic(err)
}
dbSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeDatabases)
if err != nil {
panic(err)
}
api.ServiceStatus() expõe a saúde agregada da plataforma (os mesmos dados exibidos na página pública de status).
status, err := api.ServiceStatus()
if err != nil {
panic(err)
}
fmt.Println(status.Status) // "ok" | "degraded" | "down"
fmt.Println(status.Message) // resumo legível
Diferente da maioria dos endpoints v2, essa rota não encapsula o payload no envelope padrão { status, code, response } — ela responde com { status, message } diretamente.
Opções de requisição
Todos os métodos aceitam ...rest.RequestOpts ao final para customizar a requisição individual:
| Opção | Descrição |
|---|
rest.WithContext(ctx) | Anexa um context.Context para cancelamento ou deadlines |
rest.WithQueryParam(key, value) | Adiciona um parâmetro de query |
rest.WithHeader(key, value) | Define um header da requisição |
rest.WithToken(token) | Sobrescreve o token de autenticação apenas para essa requisição |
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
user, err := api.SelfUser(rest.WithContext(ctx))
if err != nil {
panic(err)
}
Tratamento de erros
Qualquer resposta não-2xx é retornada como um *rest.APIError expondo StatusCode, Code e Message. Desembrulhe com o idiomático errors.As:
app, err := api.GetApplication("invalid-id")
if err != nil {
var apiErr *rest.APIError
if errors.As(err, &apiErr) {
fmt.Println(apiErr.StatusCode) // ex.: 404
fmt.Println(apiErr.Code) // ex.: "APP_NOT_FOUND"
fmt.Println(apiErr.Message)
}
return
}
rest.ErrorCode(err) string — retorna o código de erro da API (ou "" quando o erro não é um *rest.APIError)rest.IsRateLimit(err) bool — informa se o erro é algum dos códigos de rate limit (KEEP_CALM, RATE_LIMIT, RATE_LIMIT_EXCEEDED, RATELIMIT, DELAY_NOW)
if err != nil {
if rest.IsRateLimit(err) {
time.Sleep(5 * time.Second)
// tentar novamente...
}
switch rest.ErrorCode(err) {
case "APP_NOT_FOUND":
fmt.Println("a aplicação não existe")
case "ACCESS_DENIED":
fmt.Println("chave de API inválida")
}
}
@squarecloud/api-types — veja a tabela completa de códigos na referência do SDK de JS.
