> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Client

> O pacote rest é o ponto de entrada do SDK de Go. Instancie um client com uma chave de API e acesse todos os recursos — aplicações, bancos de dados, workspaces, usuário e status da plataforma — através de uma única interface.

## 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](https://squarecloud.app/pt-br/dashboard) em **Minha Conta → Regenerar API/CLI KEY**

## Instalação

```bash theme={null}
go get github.com/squarecloudofc/sdk-api-go/v2
```

O módulo é distribuído com dois pacotes:

| 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

```go theme={null}
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 `ConfigOpt`s 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                            |

```go theme={null}
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](/pt-br/sdks/go/managing_application) |
| `Databases`    | Criação, gerenciamento, credenciais e snapshots                             | [Bancos de dados](/pt-br/sdks/go/databases)                   |
| `Workspaces`   | Criação, membros, aplicações compartilhadas                                 | [Workspaces](/pt-br/sdks/go/workspaces)                       |

## Obtendo o usuário autenticado

`api.SelfUser()` retorna um `squarecloud.User` com os detalhes da conta e o plano atual.

```go theme={null}
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`:

```go theme={null}
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)
}
```

Para buscar o registro completo de um único recurso, use `GetApplication` / `GetDatabase` — veja [Gerenciando aplicações](/pt-br/sdks/go/managing_application) e [Bancos de dados](/pt-br/sdks/go/databases).

## Listando histórico de snapshots da conta

`api.UserSnapshots(scope)` retorna todos os snapshots que você possui para um determinado domínio:

```go theme={null}
appSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeApplications)
if err != nil {
	panic(err)
}

dbSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeDatabases)
if err != nil {
	panic(err)
}
```

Veja [Snapshots](/pt-br/sdks/go/snapshots) para detalhes sobre os payloads de snapshot.

## Status da plataforma

`api.ServiceStatus()` expõe a saúde agregada da plataforma (os mesmos dados exibidos na página pública de status).

```go theme={null}
status, err := api.ServiceStatus()
if err != nil {
	panic(err)
}

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // resumo legível
```

<Note>
  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.
</Note>

## Opções de requisição

Todos os métodos aceitam `...rest.RequestOpt`s 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 |

```go theme={null}
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`:

```go theme={null}
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
}
```

Dois helpers simplificam as verificações mais comuns:

* `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`)

```go theme={null}
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")
	}
}
```

Os códigos de erro são os mesmos usados pelo `@squarecloud/api-types` — veja a [tabela completa de códigos na referência do SDK de JS](/pt-br/sdks/js/client#codigos-de-erro-apierrorcode).