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

> Il pacchetto rest è il punto di ingresso all'SDK Go. Istanzia un client con una chiave API e accedi a ogni risorsa — applicazioni, database, workspace, utente e servizio della piattaforma — tramite un'unica interfaccia.

## Requisiti

* **Go 1.24** o più recente
* **Zero dipendenze esterne** — l'SDK è costruito esclusivamente sulla libreria standard di Go
* Una chiave API valida — richiedine una nella [Dashboard di Square Cloud](https://squarecloud.app/it/dashboard) in **My Account → Regenerate API/CLI KEY**

## Installazione

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

Il modulo fornisce due pacchetti:

| Pacchetto     | Percorso di import                                    | Contenuto                                                                       |
| ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------- |
| `rest`        | `github.com/squarecloudofc/sdk-api-go/v2/rest`        | Client HTTP, interfacce delle risorse, opzioni di richiesta, errori, stream SSE |
| `squarecloud` | `github.com/squarecloudofc/sdk-api-go/v2/squarecloud` | Ogni tipo e struct di richiesta/risposta                                        |

## Istanziare il 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...)` costruisce il client HTTP sottostante; `rest.New(client)` lo avvolge in `rest.Rest`, l'interfaccia che espone ogni risorsa. Usa sempre `defer client.Close()` per rilasciare le connessioni inattive.

### Configurazione del client (`ConfigOpt`)

`rest.NewClient` accetta `ConfigOpt` opzionali dopo il token:

| Opzione                             | Default                          | Descrizione                                               |
| ----------------------------------- | -------------------------------- | --------------------------------------------------------- |
| `rest.WithLogger(*slog.Logger)`     | scartato                         | Logger strutturato per il debug di richieste/risposte     |
| `rest.WithHTTPClient(*http.Client)` | timeout 30s                      | `*http.Client` personalizzato (proxy, transport, timeout) |
| `rest.WithURL(string)`              | `https://api.squarecloud.app/v2` | URL base dell'API                                         |
| `rest.WithUserAgent(string)`        | default dell'SDK                 | Header `User-Agent` personalizzato                        |

```go theme={null}
client := rest.NewClient(
	os.Getenv("SQUARECLOUD_API_KEY"),
	rest.WithLogger(slog.Default()),
	rest.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)
```

## Moduli

`rest.Rest` incorpora un'interfaccia per ogni dominio di risorse, oltre ai metodi utente e di servizio documentati in questa pagina:

| Interfaccia    | Copertura                                                                      | Documentazione                                              |
| -------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `Applications` | Gestione, upload, file, variabili d'ambiente, snapshot, deploy, rete, realtime | [Gestire le applicazioni](/it/sdks/go/managing_application) |
| `Databases`    | Creazione, gestione, credenziali e snapshot                                    | [Database](/it/sdks/go/databases)                           |
| `Workspaces`   | Creazione, membri, applicazioni condivise                                      | [Workspace](/it/sdks/go/workspaces)                         |

## Ottenere l'utente autenticato

`api.SelfUser()` restituisce un `squarecloud.User` con i dettagli dell'account e il piano attuale.

```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)         // plan duration, 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                   | Descrizione                                                |
| ----------- | ---------------------- | ---------------------------------------------------------- |
| `ID`        | `string`               | ID utente (24 caratteri esadecimali)                       |
| `Name`      | `string`               | Nome visualizzato                                          |
| `Email`     | `string`               | Email dell'account                                         |
| `Locale`    | `string`               | Locale preferito, ad esempio `"en-US"`                     |
| `Plan`      | `squarecloud.UserPlan` | `Name`, `Memory{Limit, Available, Used}` (MB) e `Duration` |
| `CreatedAt` | `string`               | Data di creazione dell'account                             |

## Elencare le tue applicazioni e i tuoi database

`api.GetApplications()` e `api.GetDatabases()` elencano tutto ciò che possiedi tramite l'endpoint `/users/me`, restituendo descrittori compatti `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)
}
```

Per recuperare il record completo di una singola risorsa, usa `GetApplication` / `GetDatabase` — consulta [Gestire le applicazioni](/it/sdks/go/managing_application) e [Database](/it/sdks/go/databases).

## Elencare la cronologia degli snapshot (a livello di account)

`api.UserSnapshots(scope)` restituisce ogni snapshot che possiedi per un determinato dominio:

```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 [Snapshot](/it/sdks/go/snapshots) per i dettagli sui payload degli snapshot.

## Stato della piattaforma

`api.ServiceStatus()` espone lo stato di salute aggregato della piattaforma (gli stessi dati mostrati nella pagina di stato pubblica).

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

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // human-readable summary
```

<Note>
  A differenza della maggior parte degli endpoint v2, questa route **non** avvolge il suo payload nella busta standard `{ status, code, response }` — risponde direttamente con `{ status, message }`.
</Note>

## Opzioni di richiesta

Ogni metodo accetta `...rest.RequestOpt` finali per personalizzare la singola richiesta:

| Opzione                           | Descrizione                                                      |
| --------------------------------- | ---------------------------------------------------------------- |
| `rest.WithContext(ctx)`           | Allega un `context.Context` per cancellazione o scadenze         |
| `rest.WithQueryParam(key, value)` | Aggiunge un parametro di query                                   |
| `rest.WithHeader(key, value)`     | Imposta un header della richiesta                                |
| `rest.WithToken(token)`           | Sovrascrive il token di autenticazione solo per questa richiesta |

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

## Gestione degli errori

Qualsiasi risposta non-2xx viene restituita come `*rest.APIError`, che espone `StatusCode`, `Code` e `Message`. Estrailo con l'idiomatico `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
}
```

Due helper semplificano i controlli più comuni:

* `rest.ErrorCode(err) string` — restituisce il codice di errore dell'API (oppure `""` quando l'errore non è un `*rest.APIError`)
* `rest.IsRateLimit(err) bool` — indica se l'errore corrisponde a uno dei codici di 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)
		// retry...
	}

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

I codici di errore sono gli stessi usati da `@squarecloud/api-types` — consulta la [tabella completa dei codici nel riferimento dell'SDK JS](/it/sdks/js/client#codici-di-errore-apierrorcode).