Client

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 en My Account → Regenerate API/CLI KEY

Instalación

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

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

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
`Databases`	Creación, gestión, credenciales y snapshots	Bases de datos
`Workspaces`	Creación, miembros, aplicaciones compartidas	Workspaces

Obtener el usuario autenticado

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

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:

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 y Bases de datos.

Listado del historial de snapshots (a nivel de cuenta)

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

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

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

Consulta 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).

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

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

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 }.

Opciones de solicitud

Cada método acepta ...rest.RequestOpts 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

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:

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)

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.

Servicios

Runtimes

Plataforma

Solución de problemas

CLI

SDKs

Changelog

Requisitos

Instalación

Instanciar el cliente

Configuración del cliente (`ConfigOpt`)

Módulos

Obtener el usuario autenticado

Listado de tus aplicaciones y bases de datos

Listado del historial de snapshots (a nivel de cuenta)

Estado de la plataforma

Opciones de solicitud

Manejo de errores

​Requisitos

​Instalación

​Instanciar el cliente

​Configuración del cliente (ConfigOpt)

​Módulos

​Obtener el usuario autenticado

​Listado de tus aplicaciones y bases de datos

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

​Estado de la plataforma

​Opciones de solicitud

​Manejo de errores

Requisitos

Instalación

Instanciar el cliente

Configuración del cliente (`ConfigOpt`)

Módulos

Obtener el usuario autenticado

Listado de tus aplicaciones y bases de datos

Listado del historial de snapshots (a nivel de cuenta)

Estado de la plataforma

Opciones de solicitud

Manejo de errores