> ## 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

> El paquete rest es el punto de entrada al SDK de Go. Instancia un cliente con una clave de API y accede a cada recurso — aplicaciones, bases de datos, workspaces, usuario y servicio de plataforma — a través de una única interfaz.

## Requisitos

* **Go 1.24** o más reciente
* **Cero dependencias externas** — el SDK está construido únicamente sobre la biblioteca estándar de Go
* Una clave de API válida — solicita una en el [Panel de Square Cloud](https://squarecloud.app/es/dashboard) en **My Account → Regenerate API/CLI KEY**

## Instalación

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

El módulo incluye dos paquetes:

| Paquete       | Ruta de import                                        | Contenido                                                                        |
| ------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
| `rest`        | `github.com/squarecloudofc/sdk-api-go/v2/rest`        | Cliente HTTP, interfaces de recursos, opciones de solicitud, errores, stream SSE |
| `squarecloud` | `github.com/squarecloudofc/sdk-api-go/v2/squarecloud` | Todos los tipos y structs de solicitud/respuesta                                 |

## Instanciar el cliente

```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...)` construye el cliente HTTP subyacente; `rest.New(client)` lo envuelve en `rest.Rest`, la interfaz que expone cada recurso. Usa siempre `defer client.Close()` para liberar las conexiones inactivas.

### Configuración del cliente (`ConfigOpt`)

`rest.NewClient` acepta `ConfigOpt`s opcionales después del token:

| Opción                              | Predeterminado                   | Descripción                                                  |
| ----------------------------------- | -------------------------------- | ------------------------------------------------------------ |
| `rest.WithLogger(*slog.Logger)`     | descartado                       | Logger estructurado para depurar solicitudes/respuestas      |
| `rest.WithHTTPClient(*http.Client)` | timeout de 30s                   | `*http.Client` personalizado (proxies, transports, timeouts) |
| `rest.WithURL(string)`              | `https://api.squarecloud.app/v2` | URL base de la API                                           |
| `rest.WithUserAgent(string)`        | valor predeterminado del SDK     | Header `User-Agent` personalizado                            |

```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` embebe una interfaz por dominio de recursos, además de los métodos de usuario y servicio documentados en esta página:

| Interfaz       | Cobertura                                                                             | Documentación                                              |
| -------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `Applications` | Gestión, subida, archivos, variables de entorno, snapshots, deploys, red, tiempo real | [Gestionar aplicaciones](/es/sdks/go/managing_application) |
| `Databases`    | Creación, gestión, credenciales y snapshots                                           | [Bases de datos](/es/sdks/go/databases)                    |
| `Workspaces`   | Creación, miembros, aplicaciones compartidas                                          | [Workspaces](/es/sdks/go/workspaces)                       |

## Obtener el usuario autenticado

`api.SelfUser()` devuelve un `squarecloud.User` con los detalles de la cuenta y el plan actual.

```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)             // e.g. "standard"
fmt.Println(user.Plan.Duration)         // duración del plan, e.g. "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                   | Descripción                                                |
| ----------- | ---------------------- | ---------------------------------------------------------- |
| `ID`        | `string`               | ID del usuario (24 caracteres hex)                         |
| `Name`      | `string`               | Nombre visible                                             |
| `Email`     | `string`               | Email de la cuenta                                         |
| `Locale`    | `string`               | Locale preferido, e.g. `"en-US"`                           |
| `Plan`      | `squarecloud.UserPlan` | `Name`, `Memory{Limit, Available, Used}` (MB) y `Duration` |
| `CreatedAt` | `string`               | Fecha de creación de la cuenta                             |

## Listado de tus aplicaciones y bases de datos

`api.GetApplications()` y `api.GetDatabases()` listan todo lo que posees a través del endpoint `/users/me`, devolviendo descriptores 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 obtener el registro completo de un único recurso, usa `GetApplication` / `GetDatabase` — consulta [Gestionar aplicaciones](/es/sdks/go/managing_application) y [Bases de datos](/es/sdks/go/databases).

## Listado del historial de snapshots (a nivel de cuenta)

`api.UserSnapshots(scope)` devuelve todos los snapshots que posees para un dominio dado:

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

Consulta [Snapshots](/es/sdks/go/snapshots) para más detalles sobre los payloads de snapshots.

## Estado de la plataforma

`api.ServiceStatus()` expone el estado de salud agregado de la plataforma (los mismos datos que se muestran en la página de estado pública).

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

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // resumen legible para humanos
```

<Note>
  A diferencia de la mayoría de los endpoints v2, esta ruta **no** envuelve su payload en el sobre estándar `{ status, code, response }` — responde directamente con `{ status, message }`.
</Note>

## Opciones de solicitud

Cada método acepta `...rest.RequestOpt`s al final para personalizar la solicitud individual:

| Opción                            | Descripción                                                    |
| --------------------------------- | -------------------------------------------------------------- |
| `rest.WithContext(ctx)`           | Adjunta un `context.Context` para cancelación o deadlines      |
| `rest.WithQueryParam(key, value)` | Añade un parámetro de query                                    |
| `rest.WithHeader(key, value)`     | Establece un header de la solicitud                            |
| `rest.WithToken(token)`           | Sobrescribe el token de autenticación solo para esta solicitud |

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

## Manejo de errores

Cualquier respuesta no-2xx se devuelve como un `*rest.APIError` que expone `StatusCode`, `Code` y `Message`. Desenvuélvelo con el 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) // e.g. 404
		fmt.Println(apiErr.Code)       // e.g. "APP_NOT_FOUND"
		fmt.Println(apiErr.Message)
	}
	return
}
```

Dos helpers simplifican las comprobaciones comunes:

* `rest.ErrorCode(err) string` — devuelve el código de error de la API (o `""` cuando el error no es un `*rest.APIError`)
* `rest.IsRateLimit(err) bool` — indica si el error es alguno de los 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)
		// reintentar...
	}

	switch rest.ErrorCode(err) {
	case "APP_NOT_FOUND":
		fmt.Println("application does not exist")
	case "ACCESS_DENIED":
		fmt.Println("invalid API key")
	}
}
```

Los códigos de error son los mismos que usa `@squarecloud/api-types` — consulta la [tabla completa de códigos en la referencia del SDK de JS](/es/sdks/js/client#codigos-de-error-apierrorcode).