diff --git a/docs/sdk/go-sdk.md b/docs/sdk/go-sdk.md index 840f174..60e267d 100644 --- a/docs/sdk/go-sdk.md +++ b/docs/sdk/go-sdk.md @@ -14,11 +14,14 @@ Remnawave Go SDK is a library for convenient interaction with the RestAPI. ✨ Key Features -- **Generated with ogen**: Zero-reflection JSON decoder for high throughput +- **Generated with [ogen](https://github.com/ogen-go/ogen) v1.19.0**: Zero-reflection JSON decoder for high throughput - **Type-safe**: Compile-time validation against OpenAPI 3.0 spec - **Controller-based design**: Organized sub-clients for clean API access - **Simplified signatures**: No verbose Params structs for simple operations - **Context support**: First-class `context.Context` support +- **OpenTelemetry**: Built-in tracing instrumentation +- **Request options**: Per-request customization via `...RequestOption` +- **Editors**: Request/response middleware support ## Installation @@ -32,6 +35,8 @@ Always pick and pin the correct version of the SDK to match the version of the R | SDK Version | Remnawave Panel Version | | ----------- | ----------------------- | +| v2.6.1 | 2.6.1 | +| v2.5.3 | 2.5.3 | | v2.3.0-6 | 2.3.0 | | v2.2.6-3 | 2.2.6 | @@ -109,7 +114,7 @@ func main() { client := remapi.NewClientExt(baseClient) // Create user - createResp, err := client.Users().CreateUser(ctx, &remapi.CreateUserRequestDto{ + createResp, err := client.Users().CreateUser(ctx, &remapi.CreateUserRequest{ Username: "john_doe", }) if err != nil { @@ -117,24 +122,24 @@ func main() { } user := createResp.(*remapi.UserResponse).Response - fmt.Printf("Created user: %s (UUID: %s)\n", user.Username, user.Uuid) + fmt.Printf("Created user: %s (UUID: %s)\n", user.Username, user.UUID) // Disable user - _, err = client.Users().DisableUser(ctx, user.Uuid.String()) + _, err = client.Users().DisableUser(ctx, user.UUID.String()) if err != nil { log.Fatal(err) } fmt.Println("User disabled") // Enable user - _, err = client.Users().EnableUser(ctx, user.Uuid.String()) + _, err = client.Users().EnableUser(ctx, user.UUID.String()) if err != nil { log.Fatal(err) } fmt.Println("User enabled") // Delete user - _, err = client.Users().DeleteUser(ctx, user.Uuid.String()) + _, err = client.Users().DeleteUser(ctx, user.UUID.String()) if err != nil { log.Fatal(err) } @@ -177,13 +182,13 @@ func main() { fmt.Printf("Total nodes: %d\n", len(nodes)) for _, node := range nodes { - fmt.Printf(" - %s (%s): connected=%v\n", + fmt.Printf(" - %s (%s): connected=%v\n", node.Name, node.Address, node.IsConnected) } // Get single node if len(nodes) > 0 { - nodeResp, _ := client.Nodes().GetOneNode(ctx, nodes[0].Uuid.String()) + nodeResp, _ := client.Nodes().GetOneNode(ctx, nodes[0].UUID.String()) node := nodeResp.(*remapi.NodeResponse).Response fmt.Printf("\nNode details: %s\n", node.Name) } @@ -192,6 +197,57 @@ func main() { +
+Pagination + +```go +package main + +import ( + "context" + "fmt" + "log" + + remapi "github.com/Jolymmiles/remnawave-api-go/v2/api" +) + +func main() { + ctx := context.Background() + + baseClient, _ := remapi.NewClient( + "https://your-panel.example.com", + remapi.StaticToken{Token: "YOUR_API_TOKEN"}, + ) + client := remapi.NewClientExt(baseClient) + + // Use PaginationHelper for iterating through pages + pager := remapi.NewPaginationHelper(50) // 50 items per page + + for pager.HasMore { + resp, err := client.Users().GetAllUsers(ctx, + pager.Limit, // size + pager.Offset, // start + ) + if err != nil { + log.Fatal(err) + } + + users := resp.(*remapi.GetAllUsersResponse) + for _, user := range users.Response.Users { + fmt.Printf("User: %s (UUID: %s)\n", user.Username, user.UUID) + } + + // Advance to next page + pager.SetTotal(int(users.Response.Total)) + pager.NextPage() + } + + fmt.Printf("Total users: %d\n", *pager.Total) +} +``` + +
+
Error handling @@ -220,23 +276,21 @@ func main() { log.Fatal("Network error:", err) } + // Available error types depend on the endpoint — check the generated + // Res interface (e.g. UsersGetUserByUuidRes) for the full list. switch e := resp.(type) { + case *remapi.UserResponse: + fmt.Printf("User found: %s\n", e.Response.Username) case *remapi.BadRequestError: fmt.Println("Validation errors:") for _, ve := range e.Errors { - fmt.Printf(" - %s: %s (path: %v)\n", + fmt.Printf(" - %s: %s (path: %v)\n", ve.Code, ve.Message, ve.Path) } - case *remapi.UnauthorizedError: - fmt.Println("Invalid or expired token") - case *remapi.ForbiddenError: - fmt.Println("Access denied") case *remapi.NotFoundError: fmt.Println("Resource not found") case *remapi.InternalServerError: fmt.Printf("Server error: %s\n", e.Message.Value) - case *remapi.UserResponse: - fmt.Printf("User found: %s\n", e.Response.Username) } } ``` @@ -247,20 +301,32 @@ func main() { | Controller | Description | |------------|-------------| -| `client.Users()` | User management | -| `client.UsersBulkActions()` | Bulk user operations | -| `client.Nodes()` | Node management | +| `client.ApiTokens()` | API token management | +| `client.Auth()` | Authentication | +| `client.BandwidthStatsNodes()` | Node bandwidth statistics | +| `client.BandwidthStatsUsers()` | User bandwidth statistics | +| `client.ConfigProfile()` | Config profiles | +| `client.ExternalSquad()` | External squads | | `client.Hosts()` | Host management | | `client.HostsBulkActions()` | Bulk host operations | -| `client.Auth()` | Authentication | -| `client.Subscription()` | Subscription management | -| `client.SubscriptionSettings()` | Subscription settings | -| `client.SubscriptionTemplate()` | Templates | -| `client.ConfigProfile()` | Config profiles | +| `client.HwidUserDevices()` | HWID devices | +| `client.InfraBilling()` | Infrastructure billing | | `client.InternalSquad()` | Internal squads | -| `client.ExternalSquad()` | External squads | +| `client.Keygen()` | Key generation | +| `client.Nodes()` | Node management | +| `client.NodesUsageHistory()` | Node usage history | +| `client.Passkey()` | Passkey authentication | +| `client.RemnawaveSettings()` | Panel settings | +| `client.Snippets()` | Code snippets | +| `client.Subscription()` | Subscription management | +| `client.SubscriptionPageConfig()` | Subscription page config | +| `client.SubscriptionSettings()` | Subscription settings | +| `client.SubscriptionTemplate()` | Subscription templates | +| `client.Subscriptions()` | Multiple subscriptions | | `client.System()` | System info | -| `client.ApiTokens()` | API tokens | +| `client.UserSubscriptionRequestHistory()` | Request history | +| `client.Users()` | User management | +| `client.UsersBulkActions()` | Bulk user operations | ## Error Types