Go SDK [community]

Community SDK

هذا SDK يتم صيانته بالكامل من قِبل المجتمع.

Remnawave Go SDK هي مكتبة للتفاعل بسهولة مع RestAPI.

✨ الميزات الرئيسية

• مُنشأ باستخدام ogen v1.19.0: مفكك ترميز JSON بدون انعكاس لإنتاجية عالية
• آمن النوع: التحقق في وقت الترجمة وفق مواصفة OpenAPI 3.0
• تصميم قائم على وحدات التحكم: عملاء فرعيون منظمون للوصول النظيف إلى API
• توقيعات مبسطة: بدون هياكل Params المطولة للعمليات البسيطة
• دعم السياق: دعم أولي لـ context.Context
• OpenTelemetry: أدوات تتبع مضمنة
• خيارات الطلب: تخصيص لكل طلب عبر ...RequestOption
• محررون: دعم الوسيط (middleware) للطلبات/الاستجابات

التثبيت

go get github.com/Jolymmiles/remnawave-api-go/v2@latest

warning

احرص دائمًا على اختيار الإصدار الصحيح من SDK وتثبيته بما يتوافق مع إصدار خلفية Remnawave.

إصدار SDK	إصدار لوحة Remnawave
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

الاستخدام

مثال أساسي

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    // Create base client
    baseClient, err := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    if err != nil {
        log.Fatal(err)
    }

    // Wrap with organized sub-clients
    client := remapi.NewClientExt(baseClient)

    // Get user by UUID - simplified signature
    resp, err := client.Users().GetUserByUuid(ctx, "user-uuid-here")
    if err != nil {
        log.Fatal(err)
    }

    switch r := resp.(type) {
    case *remapi.UserResponse:
        fmt.Printf("User: %s\n", r.Response.Username)
    case *remapi.NotFoundError:
        fmt.Println("User not found")
    case *remapi.BadRequestError:
        fmt.Printf("Validation error: %v\n", r.Errors)
    }
}

إنشاء المستخدمين وإدارتهم

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)

    // Create user
    createResp, err := client.Users().CreateUser(ctx, &remapi.CreateUserRequest{
        Username: "john_doe",
    })
    if err != nil {
        log.Fatal(err)
    }

    user := createResp.(*remapi.UserResponse).Response
    fmt.Printf("Created user: %s (UUID: %s)\n", user.Username, user.UUID)

    // Disable user
    _, 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())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User enabled")

    // Delete user
    _, err = client.Users().DeleteUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User deleted")
}

إدارة العقد

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)

    // Get all nodes
    nodesResp, err := client.Nodes().GetAllNodes(ctx)
    if err != nil {
        log.Fatal(err)
    }

    nodes := nodesResp.(*remapi.NodesResponse).Response
    fmt.Printf("Total nodes: %d\n", len(nodes))

    for _, node := range nodes {
        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())
        node := nodeResp.(*remapi.NodeResponse).Response
        fmt.Printf("\nNode details: %s\n", node.Name)
    }
}

التصفح بالصفحات

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

معالجة الأخطاء

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)

    resp, err := client.Users().GetUserByUuid(ctx, "invalid-uuid")
    if err != nil {
        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",
                ve.Code, ve.Message, ve.Path)
        }
    case *remapi.NotFoundError:
        fmt.Println("Resource not found")
    case *remapi.InternalServerError:
        fmt.Printf("Server error: %s\n", e.Message.Value)
    }
}

وحدات التحكم المتاحة

وحدة التحكم	الوصف
client.ApiTokens()	إدارة رموز API
client.Auth()	المصادقة
client.BandwidthStatsNodes()	إحصاءات النطاق الترددي للعقد
client.BandwidthStatsUsers()	إحصاءات النطاق الترددي للمستخدمين
client.ConfigProfile()	ملفات تعريف الإعداد
client.ExternalSquad()	الفرق الخارجية
client.Hosts()	إدارة المضيفين
client.HostsBulkActions()	العمليات الجماعية على المضيفين
client.HwidUserDevices()	أجهزة HWID
client.InfraBilling()	فواتير البنية التحتية
client.InternalSquad()	الفرق الداخلية
client.Keygen()	توليد المفاتيح
client.Nodes()	إدارة العقد
client.NodesUsageHistory()	تاريخ استخدام العقد
client.Passkey()	مصادقة Passkey
client.RemnawaveSettings()	إعدادات اللوحة
client.Snippets()	مقاطع الكود
client.Subscription()	إدارة الاشتراكات
client.SubscriptionPageConfig()	إعداد صفحة الاشتراك
client.SubscriptionSettings()	إعدادات الاشتراك
client.SubscriptionTemplate()	قوالب الاشتراك
client.Subscriptions()	اشتراكات متعددة
client.System()	معلومات النظام
client.UserSubscriptionRequestHistory()	تاريخ الطلبات
client.Users()	إدارة المستخدمين
client.UsersBulkActions()	العمليات الجماعية على المستخدمين

أنواع الأخطاء

النوع	حالة HTTP	الوصف
BadRequestError	400	أخطاء التحقق مع التفاصيل
UnauthorizedError	401	مطلوب المصادقة
ForbiddenError	403	الوصول مرفوض
NotFoundError	404	المورد غير موجود
InternalServerError	500	خطأ في الخادم

روابط المشروع

• مستودع GitHub: remnawave-api-go على GitHub
• المؤلف: Jolymmiles